starred/nix-config
1
0 Fork 0
mirror of https://github.com/ryan4yin/nix-config.git synced 2026-11-13 12:13:46 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity

fix(skills): correct stale guidance and widen task triggers

Browse Source
This commit is contained in:
Ryan Yin committed 2026-10-10 08:42:38 +08:00
1 parent 2d07dc8da5
commit a2cfa5549c
11 files changed
+119 -139
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.agents/skills/nix-config-debug/SKILL.md
+20 -24
View File
@@ -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 <host>` (already passes `--show-trace`) |
| build | build error, hash mismatch, "marked as broken" | `just build-host <host>`, then `nix log <drv>` |
| 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 <unit>`, `journalctl -u <unit> -b` |
| proxy/DNS | proxied sites time out, node and rules look ok | `dig +short <site>` 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@<host> journalctl -b -p err`, same commands over SSH |
| MicroVM guest | guest down or unreachable | on the VM host: `systemctl status microvm@<guest>` and `microvm-tap-interfaces@<guest>`; 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 <host>` (already passes `--show-trace`) |
| build | build error, hash mismatch, "marked as broken" | `just build-host <host>`, then `nix log <drv>` |
| 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 <unit>`, `journalctl -u <unit> -b` |
| proxy/DNS | proxied sites time out, or DNS still resolves after mihomo stops | `dig +short <site>` 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@<host> journalctl -b -p err`, same commands over SSH |
| MicroVM guest | guest down or unreachable | on the VM host: `systemctl status microvm@<guest>` and `microvm-tap-interfaces@<guest>`; then `br0` |
| secrets | missing or unreadable `/run/agenix/<name>` | 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 <wf>`, `gh run view <run> --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 <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.
.agents/skills/nix-config-desktop/SKILL.md
+17 -25
View File
@@ -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/<dir>/niri-hardware.kdl` | live |
| Noctalia shared baseline | `home/linux/gui/base/noctalia/config/config.toml` | live |
| Noctalia per-host override | `home/hosts/linux/<dir>/noctalia.toml` (`host-<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/<dir>/niri-hardware.kdl` | live |
| Noctalia shared baseline | `home/linux/gui/base/noctalia/config/config.toml` | live |
| Noctalia per-host override | `home/hosts/linux/<dir>/noctalia.toml` (`host-<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/<dir>/noctalia.toml` (`[widget.net_rx]`/`[widget.net_tx]` `interface`) | store: needs `just niri` |
| `$HOME` state that must survive | `hosts/<dir>/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.
.agents/skills/nix-config-new-host/SKILL.md
+14 -11
View File
@@ -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.<name> = { 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
.agents/skills/nix-config-secrets/SKILL.md
+4 -20
View File
@@ -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.
.agents/skills/nix-config-umu-game/SKILL.md
+10 -13
View File
@@ -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/<name>.desktop` (and a copy at
`~/Games/<name>/<name>.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/<dir>/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
.agents/skills/nix-config-update/SKILL.md
+15 -18
View File
@@ -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 <host>` — builds the full system closure and catches broken packages or build
failures that eval misses.
- `just build-microvm <guest>` — 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@<host> 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 <tag> [mode]`
- k3s test nodes: `just k3s-test [mode]`
- MicroVM guest: `just microvm-deploy <guest> <host> <guest-ip>` — 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.
.agents/skills/nixpkgs-patched/SKILL.md
+13 -11
View File
@@ -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 <pr> --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 <affected-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
.agents/skills/nixpkgs-review/SKILL.md
+6 -6
View File
@@ -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
AGENTS.md
+15 -8
View File
@@ -75,14 +75,19 @@ introduces one, and re-evaluate entries when their `Revisit` trigger comes up.
- `just eval-host <host>`, `just build-host <host>`, `just build-microvm <guest>`, 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 <input>` when the update should remain uncommitted.
- `just up`, `just upp`, `just up-nix`, and `just override-pkgs <hash>` update flake inputs and
commit the lock file. Use `nix flake update <input>` 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 <unit>` 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 <tag>` activate systems through Colmena. Use the narrower recipe
that matches the intended host scope.
- `just microvm-deploy <guest> <physical-host> <guest-ip>` 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/`.
Justfile
+3 -2
View File
@@ -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')]
hosts/k8s/README.md
+2 -1
View File
@@ -36,7 +36,8 @@ just microvm-deploy <guest> <physical-host> <guest-ip>
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 <guest>` 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.