git:20261010.e2548cd to git:20261012.9c38819

# Repository Agent Guide

This flake manages NixOS hosts, macOS via nix-darwin, shared Home Manager profiles, and Colmena

deployments. Keep repository guidance here; the global rules and global skills shared across

projects live in [agents/](./agents/README.md).

## Where Changes Belong

- `flake.nix` defines inputs; `outputs/default.nix` composes outputs for `x86_64-linux`,

`aarch64-linux`, and `aarch64-darwin`.

- `modules/` contains system modules; `home/` contains Home Manager modules. Put shared behavior

here rather than duplicating it in host configurations.

- `hosts/` contains host-specific configuration; `outputs/<system>/src/` wires hosts into outputs.

- `vars/` and `lib/` provide shared values and helpers. Use `myvars` and existing abstractions

instead of hardcoding usernames or paths.

- `secrets/` contains agenix definitions. The encrypted `.age` files live in the private

`~/codes/nix-secrets` repository, never in this public one — never copy a `.age` file here. Use

the `nix-config-secrets` skill.

- `overlays/` and `hardening/` hold package overlays and hardened (nixpak/bwrap) wrappers.

- Desktop (Niri and Noctalia) config is mostly out-of-store symlinks that hot-reload without a

rebuild; use the `nix-config-desktop` skill before changing it.

## Commands and Platforms

- Prefer recipes in [Justfile](./Justfile); use `just --list` to discover available commands and

`just --show <recipe>` to inspect behavior before running them.

- The Justfile uses Nushell. Preserve `[linux]` / `[macos]` guards and host naming conventions.

- Deploy by hostname: NixOS desktops are `<hostname>-niri` (`just niri`); other NixOS hosts, VMs,

and macOS hosts use the bare hostname (`just local`, mapping to `nixos-switch`, or `darwin-build`

/ `darwin-switch` on macOS). Arguments differ per platform; check both when changing shared

behavior.

- `nix develop` provides formatters and linters. If needed, `nix shell nixpkgs#just nixpkgs#nushell`

provides the task runner and its shell.

## Validation

- For Nix changes, run `just fmt` and inspect the diff: it formats all Nix files. Nix style is

- For supported non-Nix files, use `prettier --write <file>` and `prettier --check <file>`;

configuration lives in `.prettierrc.yaml`. Spelling checks use `typos` and `.typos.toml`.

- Run `just test` for configuration changes; it evaluates `.#evalTests` across Linux and Darwin and

exits non-zero unless the result is `true`. The bare `nix eval .#evalTests` exits 0 even on

`false`, so run `just test` or compare its `--json` output yourself.

- Eval tests are `expr.nix` / `expected.nix` pairs under `outputs/<system>/tests/`. Update focused

cases when changing behavior covered by those tests.

- Use `nix flake check` for broader flake checks. A host build can validate changes beyond eval:

`nix build .#nixosConfigurations.<host>.config.system.build.toplevel`.

- Documentation-only changes need formatting checks and `git diff --check`; Nix tests may be

skipped. Report checks run, skipped, or blocked, including the command and reason for failures.

## Nix Conventions

- Before a non-trivial change, find how nixpkgs (or the upstream project) already does it and follow

that shape instead of inventing a local convention. This covers a new package or overlay, a

hardening wrapper, a systemd unit, a kernel or driver option, and a version bump that changes the

build inputs. Look at the by-name siblings under `pkgs/by-name/<xx>/<name>/`, the recent history

of the file you are changing, and the upstream contributing docs.

- Use `kebab-case.nix` filenames and `inherit (...)` for attribute imports.

- Prefer `lib.mkIf`, `lib.optional`, and `lib.optionals` for conditional configuration.

- Use `lib.mkDefault` for defaults and `lib.mkForce` only when necessary.

- Give module options a `description` and preserve platform-specific conditions.

## AI Disclosure

Follow the

[Nixpkgs Automation/AI policy](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#automationai-policy)

for disclosure of AI-assisted contributions:

- Every commit containing non-trivial AI-generated code, documentation, or commit-message text MUST

include an `Assisted-by:` Git trailer, even when the generated text was subsequently edited.

- The trailer MUST identify the tool and the primary model's name and version, for example:

`Assisted-by: DeepSeek Harness (gpt-6.1-sol)`. Record the actual identifiers used; if unavailable,

obtain them before committing rather than guessing. `Co-authored-by:` does not satisfy this rule.

- Preserve applicable `Assisted-by:` trailers when amending, rebasing, or squashing commits. Before

committing, verify that the final message contains the required disclosure.

- AI-generated PR descriptions, reviews, and issue comments MUST disclose AI assistance separately;

commit trailers alone do not cover them. Routine formatting and short boilerplate completions are

exempt. Research, testing, debugging, and private review are exempt when no substantial generated

output is included in the contribution; disclose significant technical influence where relevant.

## Security

Security architecture, control limitations, rollout checks, and prioritized work are documented in

[SECURITY.md](./SECURITY.md). Keep it consistent with changes to security boundaries or defaults.

## Workarounds

Temporary workarounds, version pins, carried patches, and known gaps are recorded in

[WORKAROUNDS.md](./WORKAROUNDS.md), each with a removal condition. Add a row in the same change that

introduces one, and re-evaluate entries when their `Revisit` trigger comes up.

## Command Hazards

- `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`, `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; `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>` installs one MicroVM guest's runner on the physical

host and restarts its unit there. A later host activation re-points the guest at the runner baked

into the host's system; see WA-026 in [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).

- MicroVM state is stored in `/var/lib/microvms/<name>/{etc,var,home}.img`. Preserve these images

when changing the guest configuration.

- `just clean`, `just gc`, `just ggc`, and `just game` remove state or rewrite history. Use them

only for the intended cleanup or history operation.

- `just penvof` reads a process environment and can expose secrets. Use normal process inspection

commands when environment values are not required.

## Task Skills

Repo-scoped task procedures live in `.agents/skills/` (leading dot; agents discover them and list

them in their skill catalog). `agents/` without the dot holds the global rules and skills.

## Related Repositories

When a change here affects one of these, make both edits in the same task, one branch or PR per

repository, and cross-link them — no need to be told.

- `~/codes/k8s-gitops` — Flux cluster state for the k3s cluster whose hosts are defined in

`hosts/k8s` and `hosts/12kingdoms-youko` (NFS golden store, kube-vip block, `br0`). Host

networking, VM images, or cluster addons usually change both repositories together.

- `~/codes/containers` — container images consumed by k8s-gitops; a tag bump is often a two-repo

change.

- `~/codes/nix-secrets` — the private agenix store behind `secrets/` and the `mysecrets` input:

ciphertext and recipient rules for the secrets declared here.

- `wallpapers`, `nur-ryan4yin`, `pyclipsync`, `nu_scripts`, `mattpocock-skills`, `i-have-adhd` —

flake inputs from the user's own repositories; bump with `just upp <input>` after their source

changes, do not edit them from here.

## Further Context

- [Repository overview](./README.md)

- [Workarounds & known gaps](./WORKAROUNDS.md)

- [Outputs and tests](./outputs/README.md)

- [Hosts](./hosts/README.md), [system modules](./modules/README.md), and

[Home Manager](./home/README.md)

- [Secrets](./secrets/README.md), [backups](./BACKUP.md), and

[hardened app wrappers](./hardening/README.md)

- [Installing NixOS from the ISO](./nixos-installer/README.md)