# Agent Guidelines — hermenix Rules and best practices for any AI agent working in this repository. Read this file before making any changes. --- ## Mandatory First Step — Always Present a Plan Before making **any** change to this repository, you MUST present a short plan to the user and wait for their approval. This applies to every task, no matter how small. Your plan must include: 1. **What** you intend to change (files, modules, seed content) 2. **Why** the change is needed 3. **How** you will do it (which files you will edit, in what order) 4. **What you will NOT do** (e.g., "I will not run hermenix setup or build the image") Only after the user approves the plan may you proceed with edits. --- ## Hard Rules — Never Break These ### ❌ NEVER run builds or disk-writing steps directly — ZERO EXCEPTIONS **DO NOT RUN ANY OF THESE COMMANDS DIRECTLY AT ANY TIME, FOR ANY REASON:** ``` nix build # never directly — see the test-proxy exception below nix flake check # never directly hermenix setup # unless the user is actively running it themselves with you watching hermenix migrate # same — it writes into a live guest dd ... of=/var/lib/hermes-vm/** # writing any disk image nixos-rebuild switch / test / build (on any host consuming this flake) ``` **Test-proxy exception (the only allowed build path for agents):** Agents **may** run the repo's test wrapper scripts. Those scripts are the deliberate proxy through which builds happen — they scope what gets evaluated/built and never touch live disks under `/var/lib/hermes-vm/**`: ``` bin/runtest # CLI unit tests (nu/tests/) — no nix build bin/runtest-debug bin/runvmtest # guest VM checks via nix build of flake checks only bin/runvmtest-debug ``` Do **not** invent your own `nix build .#...` / `nix flake check` invocations. If a check is not reachable through those wrappers, describe it and let the operator run it. **Why the direct ban exists:** - `hermenix setup` creates/writes disk images and generates host secrets (a binary cache signing key) — destructive if repeated carelessly, and it's the operator's host, not yours to act on. - `hermenix migrate` writes into a running guest and rewrites its config, even though it never touches the migration source. - A `nixos-rebuild switch` on a consuming host is a live, production-affecting action — for `hl-fwdesk` specifically, it's the machine running the operator's actual daily-use Hermes deployment. - Bare `nix build` / `nix flake check` can take a long time and consume real resources on a machine you don't control from here. **Your job:** Write good Nix, good Nu, and good docs. The operator runs `hermenix setup`, `hermenix migrate`, image builds outside the test wrappers, and any `nixos-rebuild` themselves, on the host, watching each step. ### ❌ NEVER run `hermenix vm rollback` or `hermenix ctl reseed` without fresh confirmation Both are destructive to live guest state — `rollback` replaces the current state disk with an old snapshot; `reseed` overwrites `SOUL.md`, memories, and `config.yaml` with the seed. A prior approval for a different task does not carry over. Ask again, in the moment, before either. ### ❌ NEVER edit `guest/hardware.nix`'s disk labels blindly `fileSystems."/"` and `"/boot"` assume labels `nixos` and `ESP`. Getting this wrong produces a guest that won't boot after its first self-rebuild. Only change these after the operator has run `lsblk -f` inside the actual guest and told you the real labels. ### ❌ NEVER commit live secrets to `guest/hermes/home` That directory is a **template seed** for fresh deployments — it gets copied into the guest on first boot and is world-readable in git history forever after. Real credentials belong in the guest's own `~/.hermes/.env` (`hermenix ctl secrets edit`), never in this repo, never in the Nix store. ### ❌ NEVER move or delete source data during a migration When carrying over an existing Hermes deployment (see `hermenix migrate` / `nu/host/migrate.nu`), only ever read from and copy the source. Leave it in place and untouched until the operator has verified the new deployment end-to-end. This is the rollback safety net — don't remove it. ### ❌ NEVER commit or push unless explicitly asked Same as any other repo: describe your changes and let the operator review before committing. --- ## Safe Operations These are always safe to perform without asking: - Reading any file in this repo - Editing `modules/host.nix` to add/adjust options (gated behind `mkIf cfg.enable`, following the existing style) - Editing anything under `nu/` — check changes by parsing (`nu nu/hermenix.nu --help` and `nu nu/hermenix.nu --help` parse the whole tree without running any subcommand body) before handing it back - Editing `guest/hermes/home` / `guest/hermes/workspace` template seed content (as long as it stays free of real secrets — see above) - Editing `README.md` / `GUIDELINES.md` / `AGENTS.md` / anything under `docs/` - `nix-instantiate --parse .nix` — syntax check only, no eval, no build - Running `bin/runtest`, `bin/runtest-debug`, `bin/runvmtest`, `bin/runvmtest-debug` (the test-proxy path above) --- ## When In Doubt If you are unsure whether a command is safe, **assume it is NOT SAFE and don't run it.** Describe what you would do and ask. --- ## Repository Layout ``` hermenix/ ├── flake.nix # guest image + hermenix CLI package + nixosModules.default + checks ├── modules/host.nix # services.hermenix — host-side NixOS module ├── nu/ │ ├── hermenix.nu # top-level CLI dispatch │ ├── lib/ # shared helpers (common.nu, guest.nu) │ ├── host/ # setup, migrate, remote │ ├── vm/ # hermenix vm * │ ├── ctl/ # hermenix ctl * │ ├── tests/ # CLI unit tests (nutest) │ ├── completions.nu # generated tab completions │ └── gen-completions.nu # regenerates completions.nu from usage blocks ├── bin/ # runtest / runvmtest wrappers (agent-safe test proxy) ├── guest/ │ ├── flake.nix # the GUEST's own /etc/nixos flake — belongs to the agent │ ├── common.nix # guest NixOS config baked into the bootstrap image │ ├── hardware.nix # guest disk layout — verify labels before ever editing │ ├── local.nix.example # shape of /etc/hermenix/local.nix on the host │ ├── vm-tests/ # NixOS VM checks (bridged / unbridged / migrate) │ └── hermes/ │ ├── home/ # template seed → ~/.hermes on first boot │ └── workspace/ # template seed → ~/workspace on first boot ├── tests/ # static module evaluation checks (no VM boot) ├── docs/ # operator documentation (see README index) ├── AGENTS.md # pointer at this file for coding agents ├── GUIDELINES.md # this file └── README.md # quickstart + doc index ``` Operator-facing docs live under [`docs/`](docs/). Start at the [README](README.md).