From a26bbb15fc20f8498e153186aeca2db5410c8d95 Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Sat, 4 Jul 2026 11:40:29 +0200
Subject: [PATCH] feat(#2089): docs pointer via system-prompt line, drop
 CLAUDE.md mechanism

---
 hive-ag3nt/prompts/docs-pointer.md | 19 -------
 hive-ag3nt/src/prompt.rs           | 82 +++++++++++++++++++++++++++---
 nix/templates/harness-base.nix     | 47 +++++------------
 3 files changed, 86 insertions(+), 62 deletions(-)
 delete mode 100644 hive-ag3nt/prompts/docs-pointer.md

diff --git a/hive-ag3nt/prompts/docs-pointer.md b/hive-ag3nt/prompts/docs-pointer.md
deleted file mode 100644
index 21cd380e..00000000
--- a/hive-ag3nt/prompts/docs-pointer.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# 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.
diff --git a/hive-ag3nt/src/prompt.rs b/hive-ag3nt/src/prompt.rs
index a86d9054..aa584747 100644
--- a/hive-ag3nt/src/prompt.rs
+++ b/hive-ag3nt/src/prompt.rs
@@ -24,6 +24,7 @@ pub fn render(
     operator_pronouns: &str,
     hive_name: Option<&str>,
     swarm_name: Option<&str>,
+    docs_dir: Option<&str>,
 ) -> String {
     let body = filter_role_blocks(template, "agent");
     let qualified = crate::identity::qualify(label);
@@ -33,11 +34,25 @@ pub fn render(
     let swarm_identity = swarm_name
         .filter(|n| !n.is_empty())
         .map_or(String::new(), |n| format!(" in swarm `{n}`"));
-    body.replace("{label}", label)
+    let rendered = body
+        .replace("{label}", label)
         .replace("{qualified_label}", &qualified)
         .replace("{operator_pronouns}", operator_pronouns)
         .replace("{hive_identity}", &hive_identity)
-        .replace("{swarm_identity}", &swarm_identity)
+        .replace("{swarm_identity}", &swarm_identity);
+    // When the reference docs are mounted in-container (`hyperhive.docs.enable`
+    // wires `HIVE_DOCS_DIR` + `claude --add-dir`), append a single pointer
+    // sentence so the agent knows they exist. Additive: it doesn't replace the
+    // agent's own memory/project instructions. Absent env → no change.
+    match docs_dir.filter(|d| !d.is_empty()) {
+        Some(dir) => format!(
+            "{rendered}\n\nThe hyperhive reference docs (the repo `docs/` tree \
+             describing this live system) are mounted read-only at `{dir}` — read \
+             them (start at the index, then the topic file for the area you're \
+             touching) rather than guessing.\n"
+        ),
+        None => rendered,
+    }
 }
 
 /// Walk `template` line-by-line. Inside a `<!-- role:X -->` block,
@@ -124,12 +139,18 @@ pub async fn write_system_prompt(_socket: &Path, label: &str) -> Result<PathBuf>
     // verbatim (single-hive deployments see no diff).
     let hive_name = crate::identity::hive_name();
     let swarm_name = crate::identity::swarm_name();
+    // `hyperhive.docs.enable` sets HIVE_DOCS_DIR (and the harness passes it to
+    // claude via `--add-dir`); when present, render() appends a pointer line.
+    let docs_dir = std::env::var("HIVE_DOCS_DIR")
+        .ok()
+        .filter(|d| !d.is_empty());
     let body = render(
         &template,
         label,
         &pronouns,
         hive_name.as_deref(),
         swarm_name.as_deref(),
+        docs_dir.as_deref(),
     );
     let path = parent.join("claude-system-prompt.md");
     tokio::fs::write(&path, body).await?;
@@ -269,7 +290,7 @@ shared closer
         // Real template's first agent line — keeps the renderer
         // honest about the {label} / {operator_pronouns} pair the
         // harness already relied on.
-        let rendered = render(&PRODUCTION_TEMPLATE, "alice", "they/them", None, None);
+        let rendered = render(&PRODUCTION_TEMPLATE, "alice", "they/them", None, None, None);
         assert!(rendered.contains("hyperhive agent `alice`"));
         assert!(rendered.contains("**they/them** pronouns"));
         assert!(!rendered.contains("{label}"));
@@ -279,7 +300,7 @@ shared closer
     #[test]
     fn render_no_role_markers_in_output() {
         // No raw role markers should survive into the rendered prompt.
-        let rendered = render(&PRODUCTION_TEMPLATE, "alice", "she/her", None, None);
+        let rendered = render(&PRODUCTION_TEMPLATE, "alice", "she/her", None, None, None);
         assert!(!rendered.contains("<!-- role:"));
         assert!(!rendered.contains("<!-- /role:"));
         // Shared tools appear.
@@ -289,7 +310,7 @@ shared closer
 
     #[test]
     fn render_uses_agent_opener() {
-        let rendered = render(&PRODUCTION_TEMPLATE, "alice", "she/her", None, None);
+        let rendered = render(&PRODUCTION_TEMPLATE, "alice", "she/her", None, None, None);
         assert!(rendered.starts_with("You are hyperhive agent"));
     }
 
@@ -308,7 +329,14 @@ You are hyperhive agent `{label}` (qualified: `{qualified_label}`){hive_identity
 
     #[test]
     fn render_substitutes_hive_identity_when_set() {
-        let rendered = render(IDENTITY_FIXTURE, "alice", "she/her", Some("pr1ma"), None);
+        let rendered = render(
+            IDENTITY_FIXTURE,
+            "alice",
+            "she/her",
+            Some("pr1ma"),
+            None,
+            None,
+        );
         assert!(rendered.contains("on hive `pr1ma`"), "{rendered}");
         // swarm clause stays absent when only hive is set.
         assert!(!rendered.contains("in swarm"));
@@ -325,6 +353,7 @@ You are hyperhive agent `{label}` (qualified: `{qualified_label}`){hive_identity
             "she/her",
             None,
             Some("constellat1on"),
+            None,
         );
         assert!(rendered.contains("in swarm `constellat1on`"));
         assert!(!rendered.contains("on hive"));
@@ -338,6 +367,7 @@ You are hyperhive agent `{label}` (qualified: `{qualified_label}`){hive_identity
             "she/her",
             Some("pr1ma"),
             Some("constellat1on"),
+            None,
         );
         // Order: hive then swarm, both inline before "in a multi-agent
         // system" — keeps the opener grammar intact.
@@ -348,7 +378,7 @@ You are hyperhive agent `{label}` (qualified: `{qualified_label}`){hive_identity
     fn render_omits_identity_when_unset() {
         // None / None must round-trip the non-identity opener verbatim
         // — single-hive deployments see zero diff.
-        let rendered = render(IDENTITY_FIXTURE, "alice", "she/her", None, None);
+        let rendered = render(IDENTITY_FIXTURE, "alice", "she/her", None, None, None);
         assert!(!rendered.contains("on hive"));
         assert!(!rendered.contains("in swarm"));
         assert!(!rendered.contains("{hive_identity}"));
@@ -361,8 +391,44 @@ You are hyperhive agent `{label}` (qualified: `{qualified_label}`){hive_identity
         // through `identity::hive_name()` as None (the accessor
         // filters empty), but `render` should still no-op on a
         // direct `Some("")` from a test fixture or a future caller.
-        let rendered = render(IDENTITY_FIXTURE, "alice", "she/her", Some(""), Some(""));
+        let rendered = render(
+            IDENTITY_FIXTURE,
+            "alice",
+            "she/her",
+            Some(""),
+            Some(""),
+            None,
+        );
         assert!(!rendered.contains("on hive"));
         assert!(!rendered.contains("in swarm"));
     }
+
+    #[test]
+    fn render_appends_docs_pointer_when_docs_dir_set() {
+        let rendered = render(
+            &PRODUCTION_TEMPLATE,
+            "alice",
+            "she/her",
+            None,
+            None,
+            Some("/run/hive-docs"),
+        );
+        // Key on a phrase unique to the pointer sentence — "reference docs"
+        // alone also appears in the /knowledge blurb of the base template.
+        assert!(
+            rendered.contains("mounted read-only at `/run/hive-docs`"),
+            "expected docs pointer sentence with the dir:\n{rendered}"
+        );
+    }
+
+    #[test]
+    fn render_no_docs_pointer_when_docs_dir_absent_or_empty() {
+        for docs in [None, Some("")] {
+            let rendered = render(&PRODUCTION_TEMPLATE, "alice", "she/her", None, None, docs);
+            assert!(
+                !rendered.contains("mounted read-only at"),
+                "docs pointer must not appear for {docs:?}:\n{rendered}"
+            );
+        }
+    }
 }
diff --git a/nix/templates/harness-base.nix b/nix/templates/harness-base.nix
index db68a949..9733d9b7 100644
--- a/nix/templates/harness-base.nix
+++ b/nix/templates/harness-base.nix
@@ -100,24 +100,6 @@ let
   iconPng = pkgs.runCommand "hive-agent-icon.png" { nativeBuildInputs = [ pkgs.librsvg ]; } ''
     rsvg-convert -f png -w 512 -h 512 ${config.hyperhive.icon} -o $out
   '';
-  # hyperhive.docs.enable: the reference-docs tree (from
-  # `config.hyperhive.docs.source` — the narrow `hyperhive-docs` meta-flake
-  # input in a hive deployment, or `pkgs.hyperhive-docs` for standalone
-  # builds) with a generic `CLAUDE.md` pointer dropped at the root. The
-  # harness passes this dir to claude via `--add-dir`; paired with
-  # `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` claude loads
-  # `<dir>/CLAUDE.md` ADDITIVELY (alongside, never replacing, the agent's
-  # own `~/.claude/CLAUDE.md`). The pointer prose lives in
-  # `hive-ag3nt/prompts/docs-pointer.md` (prompts belong in prompts/, not
-  # nix/) and is shipped via `hyperhive-assets`. The docs source itself
-  # stays pure (no CLAUDE.md) so the website can reuse the same tree.
-  # Lazy: only forced when `hyperhive.docs.enable` references it below.
-  agentDocs = pkgs.runCommand "hyperhive-agent-docs" { } ''
-    mkdir -p $out
-    cp -r ${config.hyperhive.docs.source}/. $out/
-    chmod -R u+w $out
-    cp ${pkgs.hyperhive-assets}/share/hyperhive/prompts/docs-pointer.md $out/CLAUDE.md
-  '';
 in
 {
   # Shared scaffolding for every hyperhive harness container.
@@ -263,12 +245,11 @@ in
     read-only as the standalone `hyperhive-docs` derivation) available
     in-container. When enabled the harness exposes the docs dir to claude
     via `claude --add-dir`, so the markdown is readable at
-    `$HIVE_DOCS_DIR/`. A generic `CLAUDE.md` pointer is dropped at the dir
-    root and loaded additively (via
-    `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`), so the agent knows
-    the docs exist without its own `~/.claude/CLAUDE.md` being replaced.
-    Default-on for the root/manager agent (see `manager.nix`), off
-    elsewhere; any agent can flip it from its `agent.nix`.
+    `$HIVE_DOCS_DIR/`, and appends a single pointer sentence to the agent's
+    system prompt so it knows the docs exist (see
+    `hive-ag3nt::prompt::render`). Default-on for the root/manager agent
+    (see `manager.nix`), off elsewhere; any agent can flip it from its
+    `agent.nix`.
   '';
 
   options.hyperhive.docs.source = lib.mkOption {
@@ -1420,18 +1401,14 @@ in
       HIVE_COMPACT_WATERMARK_TOKENS = "0";
     }
     // lib.optionalAttrs config.hyperhive.docs.enable {
-      # hyperhive.docs.enable: the in-container reference-docs tree plus a
-      # generic `CLAUDE.md` pointer at its root (see `agentDocs` above).
-      # The harness reads HIVE_DOCS_DIR and passes it to claude as
-      # `--add-dir` so the docs are readable; with
-      # `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` claude also loads
-      # the pointer additively, telling the agent the docs exist without
-      # clobbering its own memory. See hive-ag3nt::turn. The docs tree
-      # itself comes from `hyperhive.docs.source` (the narrow
+      # hyperhive.docs.enable: the in-container reference-docs tree. The
+      # harness reads HIVE_DOCS_DIR and passes it to claude as `--add-dir`
+      # so the docs are readable, and appends a single pointer sentence to
+      # the system prompt (hive-ag3nt::prompt::render) telling the agent the
+      # docs exist. Source is `hyperhive.docs.source` (the narrow
       # `hyperhive-docs` meta-flake input, or `pkgs.hyperhive-docs` for
-      # standalone builds) via `agentDocs`.
-      HIVE_DOCS_DIR = "${agentDocs}";
-      CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD = "1";
+      # standalone builds). See hive-ag3nt::turn.
+      HIVE_DOCS_DIR = "${config.hyperhive.docs.source}";
     }
     // lib.optionalAttrs (config.hyperhive._bashEnvFragments != "") {
       # Non-interactive bash invocations (claude's `Bash` tool runs