From 18e86d0adb92d09688d57bca9f26ad753a96722c Mon Sep 17 00:00:00 2001
From: lexis <lexis@hyperhive>
Date: Tue, 26 May 2026 01:13:20 +0200
Subject: [PATCH] docs: restructure CLAUDE.md quick-reminders as index pointers
 (#430)

---
 CLAUDE.md | 40 +++++++++++-----------------------------
 1 file changed, 11 insertions(+), 29 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 4fe5940d..1689e9c5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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).