docs: restructure CLAUDE.md quick-reminders as index pointers (#430)

This commit is contained in:
lexis 2026-05-26 01:13:20 +02:00
commit 18e86d0adb

View file

@ -215,33 +215,15 @@ read them à la carte.
- **"Why does the nspawn flag look like that?"** →
[`docs/gotchas.md`](docs/gotchas.md).
## Quick reminders
## Conventions & process
- **Commit before test.** Stage and commit when work *looks*
ready, then run validation. Failures get a follow-up commit
rather than an amend.
- **Commit messages: short, lowercase, no `Co-Authored-By`
trailer.** Imperative mood.
- **`rebuild` is the reconcile verb.** Anything that changes
per-container state on the host should be re-applied there so
the dashboard's `↻ R3BU1LD` is sufficient to recover.
- **Identity = socket.** No auth tokens — the socket path
identifies the principal.
- **Actions are factored** between admin socket and dashboard via
`actions.rs` and `dashboard.rs::lifecycle_action`, so the two
surfaces never drift.
- **Two-step spawn:** `request_init_config` → edit `agent.nix`
`request_apply_commit`. The first apply_commit creates the
container; subsequent ones rebuild it. `request_spawn` still
works but is deprecated.
- **Rate-limit sentinel:** `{state_dir}/hyperhive-rate-limited`
is written by the harness on 429 and cleared on retry.
`ContainerView.rate_limited` reads it for the dashboard badge.
- **Auth-failed sentinel:** `{state_dir}/hyperhive-needs-login`
is written on a 401 mid-turn (OAuth credentials expired).
Harness requeues the inflight message and parks in
`wait_for_login` until the operator re-auths via the web UI.
- **Context window:** defaults are in `services.hive-c0re.contextWindowTokens`
(host nix, affects all agents). Per-agent default model via
`hyperhive.model` in `agent.nix`. Watermarks are 75%/50% of the
effective window.
The docs below own the details — this section just points at them.
- **Commit style, naming, identity, reconcile verb:**
[`docs/conventions.md`](docs/conventions.md).
- **NixOS / nspawn quirks** (bind mounts, conf flags, etc.): →
[`docs/gotchas.md`](docs/gotchas.md).
- **Turn loop, sentinels (rate-limit, auth-failed), context
window:** → [`docs/turn-loop.md`](docs/turn-loop.md).
- **Two-step spawn, approval flow, flake.lock validation:**
[`docs/approvals.md`](docs/approvals.md).