feat(#2089): additive claude.md pointer to in-container docs

hive-ag3nt/prompts/docs-pointer.md

@@ -0,0 +1,19 @@
+# hyperhive reference docs
+
+The hyperhive reference docs are mounted read-only in this directory
+(the harness exposes the path as `$HIVE_DOCS_DIR`). They are the
+canonical reference for how this swarm actually works - the turn loop,
+the tool surface, persistence, conventions, runbooks, and the
+approval/CI/forge/matrix workflows.
+
+- On a fresh deploy, or any time you are unsure how a hyperhive
+  mechanism behaves, read `setup.md` first, then the topic file for the
+  area you are touching (e.g. `turn-loop.md`, `persistence.md`,
+  `tools/`, `conventions.md`, `gotchas.md`).
+- Prefer these docs over guessing: they describe the live system, not a
+  generic one.
+
+This pointer is additive. It does not replace your own memory or project
+instructions - your `~/.claude/CLAUDE.md` and any harness/project memory
+still apply in full. Nothing here overrides what you already know about
+yourself; it only tells you where the shared reference material lives.

hive-ag3nt/src/turn.rs

@@ -708,10 +708,12 @@ async fn run_claude(prompt: &str, files: &TurnFiles, bus: &Bus) -> Result<(bool,
         .arg("--allowedTools")
         .arg(mcp::allowed_tools_arg());
     // hyperhive.docs.enable wires HIVE_DOCS_DIR to the in-container
-    // reference-docs tree. Expose it to claude as an additional
-    // directory so the docs are readable; the agent is NOT pointed at
-    // them (no CLAUDE.md autoload) — surfacing a pointer is the open
-    // follow-up. Unset (docs disabled) → the flag is not passed.
+    // reference-docs tree (with a generic CLAUDE.md pointer at its root).
+    // Expose it to claude as an additional directory so the docs are
+    // readable; harness-base.nix also sets
+    // CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 so claude loads that
+    // pointer additively (never replacing the agent's own CLAUDE.md).
+    // Unset (docs disabled) → the flag is not passed.
     if let Some(docs_dir) = std::env::var_os("HIVE_DOCS_DIR")
         && !docs_dir.is_empty()
     {