doc clean
This commit is contained in:
1 parent
c2a7f94821
commit
30427e3975
34 files changed
+1119
-1758
No files matched your search
+64
-26
@@ -24,20 +24,37 @@ Only after the user approves the plan may you proceed with edits.
|
||||
|
||||
## Hard Rules — Never Break These
|
||||
|
||||
### ❌ NEVER run builds or disk-writing steps — ZERO EXCEPTIONS
|
||||
### ❌ NEVER run builds or disk-writing steps directly — ZERO EXCEPTIONS
|
||||
|
||||
**DO NOT RUN ANY OF THESE COMMANDS AT ANY TIME, FOR ANY REASON:**
|
||||
**DO NOT RUN ANY OF THESE COMMANDS DIRECTLY AT ANY TIME, FOR ANY REASON:**
|
||||
|
||||
```
|
||||
nix build # unless it's to test the vm via 'bin/runvmtest'
|
||||
nix flake check
|
||||
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)
|
||||
```
|
||||
|
||||
**Why:**
|
||||
**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
|
||||
@@ -47,14 +64,14 @@ nixos-rebuild switch / test / build (on any host consuming this flake)
|
||||
- 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.
|
||||
- These commands can take a long time and consume real resources on a
|
||||
machine you don't control from here.
|
||||
- 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`, the image build, and any
|
||||
`nixos-rebuild` themselves, on the host, watching each step.
|
||||
`hermenix setup`, `hermenix migrate`, image builds outside the test wrappers,
|
||||
and any `nixos-rebuild` themselves, on the host, watching each step.
|
||||
|
||||
### ❌ NEVER run `hermes-vm rollback` or `hermes-ctl reseed` without fresh confirmation
|
||||
### ❌ 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
|
||||
@@ -73,12 +90,12 @@ and told you the real labels.
|
||||
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`
|
||||
(`hermes-ctl secrets edit`), never in this repo, never in the Nix store.
|
||||
(`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 `nu/hermenix.nu`'s
|
||||
`migrate` subcommand), only ever read from and copy the source. Leave it in
|
||||
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.
|
||||
|
||||
@@ -96,13 +113,16 @@ 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 `nu/hermenix.nu` — check any change by parsing it (`nu
|
||||
nu/hermenix.nu --help` and `nu nu/hermenix.nu <subcommand> --help` parse
|
||||
the whole file without running any subcommand body) before handing it back
|
||||
- Editing anything under `nu/` — check changes by parsing
|
||||
(`nu nu/hermenix.nu --help` and `nu nu/hermenix.nu <subcommand> --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`
|
||||
- Editing `README.md` / `GUIDELINES.md` / `AGENTS.md` / anything under `docs/`
|
||||
- `nix-instantiate --parse <file>.nix` — syntax check only, no eval, no build
|
||||
- Running `bin/runtest`, `bin/runtest-debug`, `bin/runvmtest`,
|
||||
`bin/runvmtest-debug` (the test-proxy path above)
|
||||
|
||||
---
|
||||
|
||||
@@ -117,15 +137,33 @@ don't run it.** Describe what you would do and ask.
|
||||
|
||||
```
|
||||
hermenix/
|
||||
├── flake.nix # bootstrap flake: builds the guest image + the hermenix CLI package, exposes nixosModules.default
|
||||
├── modules/host.nix # services.hermenix — the host-side NixOS module
|
||||
├── nu/hermenix.nu # the hermenix CLI: `setup` (guided host-side setup) and `migrate` (carry over existing data)
|
||||
├── 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, not the operator
|
||||
│ ├── common.nix # guest NixOS config baked into the bootstrap image
|
||||
│ ├── hardware.nix # guest disk layout — verify labels before ever editing
|
||||
│ ├── 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 (SOUL.md, config.yaml, memories/, skills/)
|
||||
│ └── workspace/ # template seed -> ~/workspace on first boot
|
||||
└── README.md # full usage docs
|
||||
│ ├── 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).
|
||||
Reference in new issue
Block a user