From a2cfa5549cef389743096fb92ed1836ced5c55fe Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 10 Oct 2026 00:38:38 +0800 Subject: [PATCH] fix(skills): correct stale guidance and widen task triggers --- .agents/skills/nix-config-debug/SKILL.md | 44 ++++++++++----------- .agents/skills/nix-config-desktop/SKILL.md | 42 ++++++++------------ .agents/skills/nix-config-new-host/SKILL.md | 25 ++++++------ .agents/skills/nix-config-secrets/SKILL.md | 24 ++--------- .agents/skills/nix-config-umu-game/SKILL.md | 23 +++++------ .agents/skills/nix-config-update/SKILL.md | 33 +++++++--------- .agents/skills/nixpkgs-patched/SKILL.md | 24 +++++------ .agents/skills/nixpkgs-review/SKILL.md | 12 +++--- AGENTS.md | 23 +++++++---- Justfile | 5 ++- hosts/k8s/README.md | 3 +- 11 files changed, 119 insertions(+), 139 deletions(-) diff --git a/.agents/skills/nix-config-debug/SKILL.md b/.agents/skills/nix-config-debug/SKILL.md index d3d5e120..ff30506c 100644 --- a/.agents/skills/nix-config-debug/SKILL.md +++ b/.agents/skills/nix-config-debug/SKILL.md @@ -1,8 +1,9 @@ --- name: nix-config-debug description: - Use when something in this repo is broken, such as an eval or build error, a failed activation, a - crashed service, or an unreachable host or MicroVM guest. + Use when something here is broken or stops working: an eval or build error, a failed activation, a + dead or restarting unit, a mihomo or DNS outage, an unreachable host or MicroVM guest, or a failing + CI action. --- # Debugging this repository @@ -24,19 +25,20 @@ bump, and the commands that destroy rollback points are in the `nix-config-updat ## 1. Localize by layer -| Layer | Symptom | Look with | -| ------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| eval | `just test` fails, an eval error | `just eval-host ` (already passes `--show-trace`) | -| build | build error, hash mismatch, "marked as broken" | `just build-host `, then `nix log ` | -| activation | the deploy fails after building | the deploy output; `journalctl -u home-manager-$USER -b` for Home Manager | -| runtime | a unit is failed or restarting | `just list-failed`, `systemctl status `, `journalctl -u -b` | -| proxy/DNS | proxied sites time out, node and rules look ok | `dig +short ` must return a fake-ip (`198.18.x.x`); a real IP means the system resolver bypasses `dns-hijack` — mihomo README Gotchas | -| boot | errors at boot, wrong kernel | `journalctl -b -p err`; `just history` for what is booted | -| session | desktop or app misbehaves | `journalctl --user -b -p err`; the `nix-config-desktop` skill | -| remote host | anything on a Colmena host | `ssh root@ journalctl -b -p err`, same commands over SSH | -| MicroVM guest | guest down or unreachable | on the VM host: `systemctl status microvm@` and `microvm-tap-interfaces@`; then `br0` | -| secrets | missing or unreadable `/etc/agenix/*` | the `nix-config-secrets` skill | -| shell | nushell exits 1 with `File not found` | whether `~/.secrets/` exists on the host; the `nix-config-secrets` skill | +| Layer | Symptom | Look with | +| ------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| eval | `just test` fails, an eval error | `just eval-host ` (already passes `--show-trace`) | +| build | build error, hash mismatch, "marked as broken" | `just build-host `, then `nix log ` | +| activation | the deploy fails after building | the deploy output; `journalctl -u home-manager-$USER -b` for Home Manager | +| runtime | a unit is failed or restarting | `just list-failed`, `systemctl status `, `journalctl -u -b` | +| proxy/DNS | proxied sites time out, or DNS still resolves after mihomo stops | `dig +short ` must return a fake-ip (`198.18.x.x`); a real IP means the resolver bypasses `dns-hijack`; on `ai` the `resolvectl dns`/`revert` hook in `hosts/idols-ai/default.nix` ties link DNS to mihomo's lifecycle and other mihomo hosts have no such hook, so read `resolvectl status` before concluding; a statically set link DNS would outlive a dead mihomo. Config and gotchas: [mihomo README](../../../modules/nixos/desktop/networking/mihomo/README.md); regenerate with `just mihomo-gen`, then restart `mihomo.service` | +| boot | errors at boot, wrong kernel | `journalctl -b -p err`; `just history` for what is booted | +| session | desktop or app misbehaves | `journalctl --user -b -p err`; the `nix-config-desktop` skill | +| remote host | anything on a Colmena host | `ssh root@ journalctl -b -p err`, same commands over SSH | +| MicroVM guest | guest down or unreachable | on the VM host: `systemctl status microvm@` and `microvm-tap-interfaces@`; then `br0` | +| secrets | missing or unreadable `/run/agenix/` | the `nix-config-secrets` skill | +| shell | nushell exits 1 with `File not found` | whether `~/.secrets/` exists on the host; the `nix-config-secrets` skill | +| CI | a GitHub Action keeps failing | `gh run list --workflow `, `gh run view --log-failed` | ## 2. Read the evaluated value @@ -73,12 +75,6 @@ to manufacture a clean tree without authorization. ## 4. Prove the fix Re-run the exact command that failed, then `just test`, then `just build-host ` for every -affected host before anyone deploys. Report the evidence ("the unit is active, `just test` is -`true`"), not the intent. - -## Why these rules exist - -- `5ee8b728 fix(restic): use the correct systemd timer option names (#319)` - an option-name error - that only reading the evaluated value catches quickly. -- `9315055b fix(darwin): unblock home-manager activation` - an activation failure that eval and - build both passed. +affected host before anyone deploys. For a running service, confirm the live config is the one just +generated (service activation time against the file's mtime) and restart if they differ. Report the +evidence ("the unit is active, `just test` is `true`"), not the intent. diff --git a/.agents/skills/nix-config-desktop/SKILL.md b/.agents/skills/nix-config-desktop/SKILL.md index 8f2da969..fcdfaf60 100644 --- a/.agents/skills/nix-config-desktop/SKILL.md +++ b/.agents/skills/nix-config-desktop/SKILL.md @@ -1,8 +1,9 @@ --- name: nix-config-desktop description: - Use when changing the Niri/Noctalia desktop, the Wayland session, input method (fcitx5), theming, - fonts, or desktop autostart in this repo. + Use when changing what the desktop shows or runs: Niri/Noctalia config, a window that is the wrong + size, garbled, or missing after a reboot, autostart, fcitx5 or vinput input, theming and fonts, + interface names a widget reads, or `$HOME` state that must survive a tmpfs root. --- # Changing the desktop @@ -35,17 +36,20 @@ back with git, and needs no rebuild. Only the store layer needs one. ## 1. Pick the layer -| Change | Where it lives | Applies | -| --------------------------------------------- | ------------------------------------------------------------- | ------------------------ | -| Niri compositor (binds, layout, window rules) | `home/linux/gui/niri/conf/*.kdl` | live | -| Niri per-host outputs | `hosts//niri-hardware.kdl` | live | -| Noctalia shared baseline | `home/linux/gui/base/noctalia/config/config.toml` | live | -| Noctalia per-host override | `home/hosts/linux//noctalia.toml` (`host-.toml`) | store: needs `just niri` | -| Noctalia value saved by the Settings UI | `~/.local/state/noctalia/settings.toml` (not in the repo) | live, wins over the rest | -| Mozc dictionary | `home/linux/gui/base/fcitx5/mozc-config1.db` | live | -| fcitx5 profile and addons | `home/linux/gui/base/fcitx5/` | store: needs `just niri` | -| Theme (catppuccin), fonts | `home/base/core/theme.nix`, `modules/nixos/desktop/fonts.nix` | store: needs `just niri` | -| Session, portal, and systemd wiring | `modules/nixos/desktop/**`, `home/linux/gui/base/xdg/` | store: needs `just niri` | +| Change | Where it lives | Applies | +| --------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ | +| Niri compositor (binds, layout, window rules) | `home/linux/gui/niri/conf/*.kdl` | live | +| Niri per-host outputs | `hosts//niri-hardware.kdl` | live | +| Noctalia shared baseline | `home/linux/gui/base/noctalia/config/config.toml` | live | +| Noctalia per-host override | `home/hosts/linux//noctalia.toml` (`host-.toml`) | store: needs `just niri` | +| Noctalia value saved by the Settings UI | `~/.local/state/noctalia/settings.toml` (not in the repo) | live, wins over the rest | +| Mozc dictionary | `home/linux/gui/base/fcitx5/mozc-config1.db` | live | +| fcitx5 profile and addons | `home/linux/gui/base/fcitx5/` | store: needs `just niri` | +| vinput (voice input) | `home/linux/gui/base/vinput/` (tag-pinned: the `fcitx5-vinput` row in WORKAROUNDS.md §Pins) | store: needs `just niri` | +| Interface a net-speed widget reads | `home/hosts/linux//noctalia.toml` (`[widget.net_rx]`/`[widget.net_tx]` `interface`) | store: needs `just niri` | +| `$HOME` state that must survive | `hosts//preservation.nix` (tmpfs root) | store: needs `just niri` | +| Theme (catppuccin), fonts | `home/base/core/theme.nix`, `modules/nixos/desktop/fonts.nix` | store: needs `just niri` | +| Session, portal, and systemd wiring | `modules/nixos/desktop/**`, `home/linux/gui/base/xdg/` | store: needs `just niri` | Noctalia's merge order and `[include]` are in [home/linux/gui/base/README.md](../../../home/linux/gui/base/README.md). A per-host difference goes @@ -122,15 +126,3 @@ What a screenshot cannot show: Do not "test" with commands that act on the session the user is looking at: `niri msg action quit`, `niri msg action power-off-monitors`, `noctalia msg dpms-off`, `noctalia msg session lock`. - -## Why these rules exist - -- `063c31cc refactor(noctalia): hot-reload config via out-of-store symlink` - the baseline is - out-of-store precisely so shell edits do not need a switch. -- `1546e54b chore(noctalia): move OSD and notifications to the bottom-right` and - `e93cb979 fix(noctalia): keep the bar readable in light mode` - changes that parse fine and only a - screenshot can judge. -- `495c3669 fix(xdg): order autostart apps after xdg-desktop-portal` - sandboxed apps raced the - portal at login; the fix orders the unit. -- `33383414 fix(niri): match outputs by EDID to survive connector renumbering` - match outputs by - EDID, not by connector name. diff --git a/.agents/skills/nix-config-new-host/SKILL.md b/.agents/skills/nix-config-new-host/SKILL.md index ace675b0..80fe826f 100644 --- a/.agents/skills/nix-config-new-host/SKILL.md +++ b/.agents/skills/nix-config-new-host/SKILL.md @@ -1,8 +1,8 @@ --- name: nix-config-new-host description: - Use when adding a NixOS, macOS, or MicroVM host in this repo, including its outputs, networking, - secrets, and eval-test wiring. + Use when adding a NixOS, macOS, or MicroVM host in this repo, or wiring an existing machine into + `outputs/`, `hostsAddr`, secrets recipients, and the eval tests. --- # Adding a host @@ -35,11 +35,12 @@ in [hosts/README.md](../../../hosts/README.md). | macOS | `hosts/darwin-fern/` + `outputs/aarch64-darwin/src/fern.nix` (`darwinConfigurations`, no Colmena) | | MicroVM guest | `hosts/k8s/k3s-test-1-worker-1/` + `outputs/x86_64-linux/src/k3s-test-1-worker-1.nix` | -A MicroVM guest is also registered in its VM host's `microvm.nix`, and is deployed with -`just microvm-deploy`. On a VM host with the `br0` bridge it also needs a `systemd.network.networks` -unit that attaches the guest's tap to `br0`; the tap name comes from the guest IP (`192.168.5.116` -to `vm116`). Some guest outputs also expose a Colmena node for evaluation or other workflows; do not -assume the physical-host deployment is done through Colmena. +A MicroVM guest is also registered in its VM host's `microvm.nix`; deploy it with the procedure in +WA-026 of [WORKAROUNDS.md](../../../WORKAROUNDS.md), not `just microvm-deploy`. On a VM host with +the `br0` bridge it also needs a `systemd.network.networks` unit that attaches the guest's tap to +`br0`; the tap name comes from the guest IP (`192.168.5.116` to `vm116`). Some guest outputs also +expose a Colmena node for evaluation or other workflows; do not assume the physical-host deployment +is done through Colmena. ## 2. Files to create or edit @@ -60,10 +61,12 @@ assume the physical-host deployment is done through Colmena. unused `args`: haumea passes them lazily and they are still required. 5. `vars/networking.nix` - `hostsAddr. = { iface; ipv4; }` for a LAN host. That entry drives the static address, the SSH `Host` alias used for remote builds, and `known_hosts`, so a wrong - `iface` takes the host offline at activation. Skip it for a DHCP or mobile host. If the host - enables `modules.networking.mihomo` and runs systemd-resolved, it needs a DNS takeover tied to - mihomo's lifecycle (`resolvectl dns`/`revert` in `ExecStartPost`/`ExecStopPost`, see - `hosts/idols-ai/default.nix`); a static link DNS would kill DNS when mihomo dies. + `iface` takes the host offline at activation. Skip it for a DHCP or mobile host; + `homeOnly = true` only drops the SSH alias and the local exporters, not `known_hosts` or the + scrape targets. If the host enables `modules.networking.mihomo` and runs systemd-resolved, it + needs a DNS takeover tied to mihomo's lifecycle (`resolvectl dns`/`revert` in + `ExecStartPost`/`ExecStopPost`, see `hosts/idols-ai/default.nix`); a static link DNS would kill + DNS when mihomo dies. 6. `hosts/README.md` - add the host to the inventory. Pin service user and group ids (`service-user-ids.nix`, as on `shoryu`) before the host has state on diff --git a/.agents/skills/nix-config-secrets/SKILL.md b/.agents/skills/nix-config-secrets/SKILL.md index 52ced764..0ed638d9 100644 --- a/.agents/skills/nix-config-secrets/SKILL.md +++ b/.agents/skills/nix-config-secrets/SKILL.md @@ -33,7 +33,8 @@ rebuild and switch on every desktop. Nothing in this flake evaluates the sync flow: no `secrets.nix` entry, no `agenix -r`, no lock bump, so the three-step order in §2 does not apply to it. Its manifest and file list live in `~/codes/nix-secrets/dotfiles/`; this repository carries the pointer, never the inventory. Do not -list synced paths here or copy one into a Nix module. +list synced paths here or copy one into a Nix module. The flow covers the desktops only; do not set +it up on a server or a cluster node. `nushell-secrets.nu` already moved to `~/.secrets/nushell-secrets.nu`. It has no agenix entry and must not get one back. @@ -71,8 +72,8 @@ must not get one back. | Decryption key | `age.identityPaths`: the host's SSH host key; `/persistent/etc/ssh/...` on a preservation host | | Secret-bearing dotfiles edited in place | `~/codes/nix-secrets/dotfiles/` — private, not a flake input, no entry in `secrets.nix` | -The private repository groups the `.age` files: `desktop/` (only desktops decrypt them), `server/` -(any server), `certs/`, and `public/`. +The private repository keeps its `.age` files in `desktop/` (only desktops decrypt them), `server/` +(any server), and `certs/`; `public/` holds publishable plaintext, not `.age`. ## 2. Add or change a secret @@ -116,10 +117,6 @@ encrypts to the recipients in `secrets.nix`, so it needs no `sudo`. `edit` passe root `agenix` process, because `sudo` resets the environment and the invoking user's `EDITOR` would not reach it; do not add `sudo -E` or set `EDITOR` yourself. -The repository keeps a single amended commit: `git commit --amend -a --no-edit`, -`git reflog expire --expire-unreachable=now --all`, `git gc --prune=now`, then force push. Treat -amend and force push as impactful and get authorization first. - ## 4. Modes and ownership Use one of the presets in `secrets/nixos.nix` (`noaccess`, `high_security`, `user_readable`); the @@ -180,16 +177,3 @@ you set, an old copy gone) instead of assuming activation did it. reads that as a local edit and reports a conflict. - **A secret is gone after a reboot on a desktop:** it moved out of agenix and its `$HOME` directory is not in `preservation.preserveAt`, so the tmpfs root drops it. - -## Why these rules exist - -- `4909f635 security: scope privileges and stop a world-readable secret copy (#335)` - the - `environment.etc` copy trap in step 3. -- `c8e76cef fix(darwin): agenix - remove non-exist secret` - a declaration left behind after its - file was deleted. -- `4211d18a` - a shared `modules/nixos/base` module included `nix-access-tokens`, which not every - host had; the reference moved to `modules/nixos/desktop/nix.nix` (core rule 4). -- `260da1ee chore: rename the nushell secret, and forbid reading decrypted secrets` - the no-reading - rule. -- The move of `nushell-secrets.nu` out of agenix - the `flake.lock` pin, not the encryption, made - each edit of a hand-edited secret cost a rebuild and switch on every desktop. diff --git a/.agents/skills/nix-config-umu-game/SKILL.md b/.agents/skills/nix-config-umu-game/SKILL.md index 66a38c74..d368b9ef 100644 --- a/.agents/skills/nix-config-umu-game/SKILL.md +++ b/.agents/skills/nix-config-umu-game/SKILL.md @@ -2,8 +2,9 @@ name: nix-config-umu-game description: Use when installing a Windows game launcher (二次元 / gacha or any non-Steam game) on a NixOS - desktop via umu-launcher, given an installer URL or an .exe, or when such a launcher opens an - invisible, transparent, black, or empty window under Wine. + desktop via umu-launcher, given an installer URL or an .exe, when such a launcher opens an + invisible, transparent, black, or empty window under Wine, or when its download crawls behind the + proxy. --- # Installing a Windows game launcher with umu @@ -87,8 +88,11 @@ defaults, so set `PROTONPATH` there to pin a particular installed version across default with FPS and frame time at the top-left; set `ENABLE_MANGOHUD=0` in `conf` to disable it, or override `MANGOHUD_CONFIG`. Re-running `prelaunch` must be idempotent. The launcher may then download the game body itself (tens of GB) -- that is the launcher's job, not this skill's, so - the install is **done** once the window is usable. `ENABLE_LOG=1` captures `last-run.log` when - something misbehaves. + the install is **done** once the window is usable. A crawl usually means the proxy: the launcher + probes the CDN itself and mihomo routes that probe through a distant node, so the download starts + from a far mirror; routing is in the + [mihomo README](../../../modules/nixos/desktop/networking/mihomo/README.md). `ENABLE_LOG=1` + captures `last-run.log` when something misbehaves. ## Invisible / transparent launcher window @@ -158,8 +162,7 @@ installers honour it; try `/quiet` or `--silent` too, then fall back to the GUI. The script also writes `~/.local/share/applications/.desktop` (and a copy at `~/Games//.desktop`), so the game shows up in the desktop launcher. Under an impermanence setup both `~/Games` and `~/.local/share/applications` must be in the host's -`preservation.preserveAt` list; in this repo `~/Games` and `.local/share/umu` already are, and -`hosts/idols-ai/preservation.nix` now persists `.local/share/applications` too. +`preservation.preserveAt` list, in `hosts//preservation.nix`. ## Uninstall @@ -203,13 +206,7 @@ GameMode, and `ENABLE_LOG=1` to capture the run. A dGPU wrapper still goes outsi - Waiting for the game download before calling the install done: the launcher's own download is out of scope here. - On NixOS a game needing 32-bit or Vulkan needs `hardware.graphics.enable32Bit`, and Steam is a - module rather than a package -- see the `nix-config-desktop` skill. - -## Prior art - -`ESKAP3/umu-skeleton` (filesystem-as-game-manager, global.conf, tools), `gizmo-ds/endfield-run` -(`-exec` installer), `Septa-Serpenta-Seraph/Vesper` (umu + GAMEID notes), `joshsymonds/nix-config` -(research-first debugging), `olafkfreund/nixarchy` (NixOS gaming skill). + module rather than a package: `modules/nixos/desktop/gaming.nix`. ## Regression tests diff --git a/.agents/skills/nix-config-update/SKILL.md b/.agents/skills/nix-config-update/SKILL.md index 0462966d..bfd9f07c 100644 --- a/.agents/skills/nix-config-update/SKILL.md +++ b/.agents/skills/nix-config-update/SKILL.md @@ -1,7 +1,9 @@ --- name: nix-config-update description: - Use when updating flake inputs, bumping nixpkgs, or rolling an update out to hosts in this repo. + Use when a version changes here: upgrading or updating a package or nixpkgs, bumping or pinning a + flake input (a tag or commit, not a branch), or deploying the result to hosts, VMs, and MicroVM + guests. --- # Updating this flake safely @@ -31,7 +33,11 @@ deploying the result to any host. - `git status` is clean, and you are on `main` or a fresh branch for the work. If you are on an unrelated feature branch, stop and ask for the right branch before bumping. -- `just test` is green _before_ the update, so you have a baseline to compare against. +- `just test` is green _before_ the update, so you have a baseline to compare against. It and every + eval fetch the private `mysecrets` input over SSH; without that access they hang instead of + failing. +- Check [WORKAROUNDS.md](../../../WORKAROUNDS.md) for the inputs and recipes you are about to use; + an active row that names one of them replaces its command here. - Enough disk for the new closures: `df -h /nix/store`. Broad nixpkgs bumps pull a lot. - Know what will move and choose the narrowest recipe that does the job. @@ -72,7 +78,7 @@ Treat an update as a supply-chain event. - `lib.mkForce` overrides that silently replace existing settings; - eval-time network access or import-from-derivation. 4. For nixpkgs-class inputs, skim the lock diff and expect broken packages and eval deprecation - warnings (see "Lessons from past updates"). + warnings. 5. Write the audit conclusion into the update commit message. If an automatic recipe already made the commit, amend it only after reviewing the diff; do not push the unaudited commit first. @@ -85,6 +91,7 @@ Run these before any host is touched: - `just build-host ` — builds the full system closure and catches broken packages or build failures that eval misses. - `just build-microvm ` — same, for a MicroVM guest. +- `just test-vm` — the runtime security-VM check (needs `/dev/kvm`); `just test` does not run it. - `nix flake check` — broader checks when the change touches shared code. Cover every host you are about to deploy, and prefer building the closure over trusting a green @@ -126,12 +133,14 @@ ssh root@ hostname # the host that actually answers - Remote servers: `just shoryu [mode]`, `just shushou`, `just youko`, `just ruby`, `just kana` - All VM hosts at once: `just lab [mode]`; any Colmena tag: `just col [mode]` - k3s test nodes: `just k3s-test [mode]` -- MicroVM guest: `just microvm-deploy ` — deploy guests serially and check - each one before moving on. +- MicroVM guest: `just microvm-deploy` currently fails at its activation step on the guest's + read-only `/nix/store`; WA-026 in [WORKAROUNDS.md](../../../WORKAROUNDS.md) carries the manual + path. Deploy guests serially and check each one before moving on. Use `boot` plus a deliberate reboot for anything that can drop networking mid-flight: the VM hosts with the `br0` bridge, and broad nixpkgs bumps. See -[hosts/README.md](../../../hosts/README.md#deploying-vm-hosts). +[hosts/README.md](../../../hosts/README.md#deploying-vm-hosts). Pause Flux sync on the k3s cluster +before changing a node's networking, and resume it once the node is back. ## 6. Verify after deploying @@ -158,15 +167,3 @@ with the `br0` bridge, and broad nixpkgs bumps. See would roll back to, so run them last, once the update has proven stable. `just gcroot` only lists GC roots. The full list of hazardous recipes is in the Command Hazards section of [AGENTS.md](../../../AGENTS.md#command-hazards). - -## Why these rules exist - -- `0fe12bef fix(nix): preserve default sandbox shell` - a `nix.settings` change used - `sandbox-paths`, which replaced Nix's compiled defaults (including the sandbox shell used for - legacy shebangs). Use `extra-sandbox-paths`, and verify with - `nix config show | grep sandbox-paths`. -- `125bce3b fix: cuda12.8-cuda_cudart-12.8.90 is marked as broken` and - `78fc64e1 fix(neovim): disable nixvim manpage on broken nixpkgs pin` - broken packages after a - nixpkgs bump are normal; `just build-host` finds them before a deploy does. -- `4bd463a7 chore(eval): resolve catppuccin and rust-overlay deprecation warnings` - input bumps - surface deprecation warnings that become errors in a later bump. diff --git a/.agents/skills/nixpkgs-patched/SKILL.md b/.agents/skills/nixpkgs-patched/SKILL.md index 3f2afbd1..4e3d2ea2 100644 --- a/.agents/skills/nixpkgs-patched/SKILL.md +++ b/.agents/skills/nixpkgs-patched/SKILL.md @@ -3,7 +3,8 @@ name: nixpkgs-patched description: Use when temporarily carrying an unmerged nixpkgs pull request or commit in the personal ryan4yin/nixpkgs fork, updating the nixos-unstable-patched branch, or consuming that branch from - this nix-config flake. + this nix-config flake, including a WORKAROUNDS.md row whose removal condition is carrying the + patch. --- # Carrying a nixpkgs patch @@ -25,20 +26,21 @@ Before changing either repository, confirm the remotes, branch, PR commits, and git remote -v git status --short git branch --show-current -git fetch upstream nixos-unstable -git fetch origin nixos-unstable-patched +git fetch origin nixos-unstable +git fetch fork nixos-unstable-patched gh pr view --repo NixOS/nixpkgs --json state,baseRefName,commits ``` -The intended fork is `ryan4yin/nixpkgs` and the intended branch is `nixos-unstable-patched`. Confirm -those names; do not infer a remote from its position in the remote list. +The intended fork is `ryan4yin/nixpkgs` and the intended branch is `nixos-unstable-patched`. In +`~/src/nixpkgs`, `origin` is `NixOS/nixpkgs` and the fork is `fork` (or `ryan4yin`); never push the +patched branch to `origin`. Confirm the names; do not infer a remote from its position in the list. ## 2. Refresh the patched branch Do this in the nixpkgs checkout (`~/src/nixpkgs`), preserving any existing work: 1. Save a rollback ref to the current patched tip. -2. Align the branch with the current `upstream/nixos-unstable`. +2. Align the branch with the current `origin/nixos-unstable`. 3. Cherry-pick the exact PR commit(s), using `-x` so the upstream source remains recorded. 4. Resolve conflicts deliberately and inspect the complete diff against upstream. @@ -61,7 +63,7 @@ package use or a patched-branch lock update. For this workflow, inspect the diff ```bash git diff --check -git log --oneline --decorate upstream/nixos-unstable..HEAD +git log --oneline --decorate origin/nixos-unstable..HEAD ``` Run package builds or tests only when the user requests them or when the selected package is needed @@ -73,8 +75,8 @@ never imply that unrelated packages or platforms were covered. After authorization and validation: ```bash -git push --force-with-lease origin nixos-unstable-patched -git ls-remote origin refs/heads/nixos-unstable-patched +git push --force-with-lease fork nixos-unstable-patched +git ls-remote fork refs/heads/nixos-unstable-patched ``` Then in this repository, update only the patched input and inspect the lock diff: @@ -88,8 +90,8 @@ just build-host ``` The nix-config eval and host-build commands validate this configuration. They are not a reason to -build every package in the patched nixpkgs branch. Run a host build only for a host that consumes the -changed package and only when the user asks for that validation. +build every package in the patched nixpkgs branch. Run a host build only for a host that consumes +the changed package and only when the user asks for that validation. Keep the nixpkgs fork change, lock update, and unrelated configuration changes separate. Do not run `just niri`, `just local`, or a remote deployment from this skill; activation is a separate diff --git a/.agents/skills/nixpkgs-review/SKILL.md b/.agents/skills/nixpkgs-review/SKILL.md index 2e5feb26..7a5f5a90 100644 --- a/.agents/skills/nixpkgs-review/SKILL.md +++ b/.agents/skills/nixpkgs-review/SKILL.md @@ -1,8 +1,9 @@ --- name: nixpkgs-review description: - Use when reviewing an upstream NixOS/nixpkgs pull request before it is merged, including its - package changes, passthru tests, dependencies, or CI results. + Use when reviewing an upstream NixOS/nixpkgs pull request before it is merged -- a PR number or + `NixOS/nixpkgs#123` link -- including its package changes, passthru tests, dependencies, or CI + results. --- # Reviewing nixpkgs changes @@ -12,10 +13,9 @@ changes against a PR base and can build selected packages and passthru tests. It way to build a package for local use or validate a nix-config lock update. For local use, build the needed package or test directly with the project's Nix commands. -Review only the package(s) changed by the PR that are relevant to the review question. Add -`--tests` when the selected package's passthru tests are part of the review. Do not broaden a review -to unrelated packages; selecting a large source package can trigger substantial downloads and -builds. +Review only the package(s) changed by the PR that are relevant to the review question. Add `--tests` +when the selected package's passthru tests are part of the review. Do not broaden a review to +unrelated packages; selecting a large source package can trigger substantial downloads and builds. ## Choose the runner diff --git a/AGENTS.md b/AGENTS.md index d9a65adb..e32532dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,14 +75,19 @@ introduces one, and re-evaluate entries when their `Revisit` trigger comes up. - `just eval-host `, `just build-host `, `just build-microvm `, and `just test` evaluate or build without activating a system. Use these commands for previews and validation. -- `just up`, `just upp`, and `just up-nix` update flake inputs and commit the lock file. Use - `nix flake update ` when the update should remain uncommitted. +- `just up`, `just upp`, `just up-nix`, and `just override-pkgs ` update flake inputs and + commit the lock file. Use `nix flake update ` when the update should remain uncommitted. - `just niri` and `just local` activate the machine you are on through `sudo` and block on a - password prompt; the user runs them, not an agent. -- `just shoryu`, `just shushou`, `just youko`, `just lab`, and `just k3s-test` activate systems - through Colmena. Use the narrower recipe that matches the intended host scope. + password prompt; `just darwin-rollback` switches the macOS generation on the machine you are on, + and a bare `sudo systemctl restart ` activates a running service the same way. The user runs + these, not an agent. +- `just shoryu`, `just shushou`, `just youko`, `just ruby`, `just kana`, `just lab`, + `just k3s-test`, and `just col ` activate systems through Colmena. Use the narrower recipe + that matches the intended host scope. - `just microvm-deploy ` installs and activates one MicroVM guest. - Deploy guests serially and check the guest Node and host services after each activation. + WA-026 currently replaces the activation step; check [WORKAROUNDS.md](./WORKAROUNDS.md) before + deploying. Deploy guests serially and check the guest Node and host services after each + activation. - VM hosts (`shoryu`, `shushou`, `youko`) carry the `br0` bridge for their guests. Use the `boot`-based host deployment procedure for network stack or broad nixpkgs changes; see [hosts/README.md](./hosts/README.md#deploying-vm-hosts). @@ -102,13 +107,15 @@ is discovered by OpenCode and compatible tools. - [`.agents/skills/nix-config-update/SKILL.md`](./.agents/skills/nix-config-update/SKILL.md) — updating flake inputs and rolling the result out to hosts safely. - [`.agents/skills/nix-config-desktop/SKILL.md`](./.agents/skills/nix-config-desktop/SKILL.md) — - which layer owns a Niri/Noctalia setting, live reload vs a rebuild, and on-screen verification. + which layer owns a Niri/Noctalia, input-method, or autostart setting, live reload vs a rebuild, + and on-screen verification. - [`.agents/skills/nix-config-secrets/SKILL.md`](./.agents/skills/nix-config-secrets/SKILL.md) — adding, changing, or removing an agenix secret, and verifying it without reading it. - [`.agents/skills/nix-config-new-host/SKILL.md`](./.agents/skills/nix-config-new-host/SKILL.md) — wiring a new host into `hosts/`, `outputs/`, networking, secrets, and the eval tests. - [`.agents/skills/nix-config-debug/SKILL.md`](./.agents/skills/nix-config-debug/SKILL.md) — mapping - a broken eval, build, activation, unit, host, or MicroVM guest to the command that localizes it. + a broken eval, build, activation, unit, proxy or DNS outage, host, MicroVM guest, or CI job to the + command that localizes it. - [`.agents/skills/nix-config-umu-game/SKILL.md`](./.agents/skills/nix-config-umu-game/SKILL.md) — installing a Windows game launcher via the umu installer it bundles; per-game fixes stay under `~/Games/`. diff --git a/Justfile b/Justfile index ee8ebf1e..590f898c 100644 --- a/Justfile +++ b/Justfile @@ -39,7 +39,7 @@ eval-host host: build-host host: nix build $".#nixosConfigurations.{{host}}.config.system.build.toplevel" --no-link --print-build-logs -# Build a MicroVM runner locally. Deploy it with microvm-deploy so the closure is copied remotely. +# Build a MicroVM runner locally. WA-026 in WORKAROUNDS.md covers how to deploy it. [group('nix')] build-microvm guest: nix build $".#nixosConfigurations.{{guest}}.config.microvm.declaredRunner" --no-link --print-build-logs @@ -210,7 +210,8 @@ reset-launchpad: col tag mode="switch": colmena apply {{mode}} --on '@{{tag}}' --verbose --show-trace -# Deploy one microVM guest through microvm.nix's SSH deployment workflow. +# Deploy one microVM guest through microvm.nix's SSH deployment workflow (WA-026: the +# activation step currently fails; see WORKAROUNDS.md). # The host is the physical machine running the guest; the guest address is used for activation. [linux] [group('homelab')] diff --git a/hosts/k8s/README.md b/hosts/k8s/README.md index e3d41520..187ec0da 100644 --- a/hosts/k8s/README.md +++ b/hosts/k8s/README.md @@ -36,7 +36,8 @@ just microvm-deploy For example, `just microvm-deploy k3s-test-1-master-3 shushou 192.168.5.116`. The recipe installs the runner on the physical host first, then activates the guest with the microvm.nix SSH deployment -interface. +interface. WA-026 in [WORKAROUNDS.md](../../WORKAROUNDS.md) currently replaces that activation, +because the SSH switch cannot write the guest's read-only `/nix/store`. Use `just build-microvm ` to build a runner without deploying it. Preserve the guest's `etc.img`, `var.img`, and `home.img` when updating it; they contain its identity and K3s state.