refactor(#2058): drop claude.md docs pointer, keep nix option + --add-dir

hive-ag3nt/src/turn.rs

@@ -695,17 +695,14 @@ 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 dir (the docs/ tree plus a generic `CLAUDE.md`
+    // reference-docs tree. Expose it to claude as an additional
-    // pointer at its root). Expose it to claude as an additional
+    // directory so the docs are readable; the agent is NOT pointed at
-    // directory so the docs are readable, and enable additive CLAUDE.md
+    // them (no CLAUDE.md autoload) — surfacing a pointer is the open
-    // loading so claude picks up `<dir>/CLAUDE.md` ALONGSIDE the agent's
+    // follow-up. Unset (docs disabled) → the flag is not passed.
-    // own memory files — never clobbering ~/.claude/CLAUDE.md or the
-    // project one. Unset (docs disabled) → neither flag is passed.
     if let Some(docs_dir) = std::env::var_os("HIVE_DOCS_DIR")
         && !docs_dir.is_empty()
     {
         cmd.arg("--add-dir").arg(&docs_dir);
-        cmd.env("CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD", "1");
     }
     let mut child = cmd
         .stdin(Stdio::piped())

nix/agent-claude.md

@@ -1,9 +0,0 @@
-# Hyperhive reference docs
-
-The hyperhive subsystem docs ship read-only inside this container at
-`$HIVE_DOCS_DIR/docs/` (resolve the env var, e.g.
-`ls "$HIVE_DOCS_DIR/docs"`).
-
-On a fresh deploy, read `$HIVE_DOCS_DIR/docs/setup.md` first for the
-first-run hive bootstrap commands (forge / gateway / matrix
-provisioning, spawning the first sub-agents).

nix/templates/harness-base.nix

@@ -70,23 +70,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 in-container directory claude is pointed
-  # at for the hyperhive reference docs (root/manager default-on; see
-  # `manager.nix`). Combines the standalone docs tree
-  # (`pkgs.hyperhive-docs`) under `docs/` with a generic, agent-agnostic
-  # `CLAUDE.md` pointer (`nix/agent-claude.md`) at its root. The harness
-  # adds this dir via `--add-dir` and sets
-  # `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`, so claude loads the
-  # sibling `CLAUDE.md` ADDITIVELY (never replacing the agent's own
-  # `~/.claude/CLAUDE.md` or the project one) and gets read access to
-  # `docs/`. Built as a runCommand (like `iconPng` above) so the tree is
-  # GC-rooted by the system closure — no persistent symlink into the
-  # store to dangle after a content change + GC.
-  agentDocs = pkgs.runCommand "hive-agent-docs" { } ''
-    mkdir -p $out
-    cp ${../agent-claude.md} $out/CLAUDE.md
-    cp -r ${pkgs.hyperhive-docs} $out/docs
-  '';
 in
 {
   # Shared scaffolding for every hyperhive harness container.
@@ -228,16 +211,14 @@ in
   };
 
   options.hyperhive.docs.enable = lib.mkEnableOption ''
-    point this agent at the hyperhive reference docs (the repo `docs/`
+    make the hyperhive reference docs (the repo `docs/` tree, shipped
-    tree, shipped read-only as the standalone `hyperhive-docs`
+    read-only as the standalone `hyperhive-docs` derivation) available
-    derivation). When enabled the harness adds the in-container docs dir
+    in-container. When enabled the harness exposes the docs dir to claude
-    via `claude --add-dir` and turns on additive CLAUDE.md loading
+    via `claude --add-dir`, so the markdown is readable at
-    (`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`), so claude loads a
+    `$HIVE_DOCS_DIR/`. The agent is NOT yet pointed at the docs (no
-    generic pointer `CLAUDE.md` from that dir ALONGSIDE — never replacing
+    auto-loaded `CLAUDE.md` pointer) — surfacing a pointer is a tracked
-    — the agent's own `~/.claude/CLAUDE.md` and project memory. The docs
+    follow-up. Default-on for the root/manager agent (see `manager.nix`),
-    are readable at `$HIVE_DOCS_DIR/docs/`. Default-on for the
+    off elsewhere; any agent can flip it from its `agent.nix`.
-    root/manager agent (see `manager.nix`), off elsewhere; any agent can
-    flip it from its `agent.nix`.
   '';
 
   options.hyperhive.allowedBashPatterns = lib.mkOption {
@@ -1270,13 +1251,12 @@ in
       HIVE_COMPACT_WATERMARK_TOKENS = "0";
     }
     // lib.optionalAttrs config.hyperhive.docs.enable {
-      # hyperhive.docs.enable: the in-container reference-docs dir — the
+      # hyperhive.docs.enable: the in-container reference-docs tree
-      # docs/ tree plus the agent CLAUDE.md pointer (see `agentDocs`
+      # (`pkgs.hyperhive-docs`, the repo docs/ verbatim). The harness
-      # above). The harness reads this and passes it to claude as
+      # reads this and passes it to claude as `--add-dir` so the docs are
-      # `--add-dir` with additive CLAUDE.md loading enabled, so the docs
+      # readable; the agent is not auto-pointed at them. See
-      # are discoverable without touching the agent's own memory files.
+      # hive-ag3nt::turn.
-      # See hive-ag3nt::turn.
+      HIVE_DOCS_DIR = "${pkgs.hyperhive-docs}";
-      HIVE_DOCS_DIR = "${agentDocs}";
     }
     // lib.optionalAttrs (config.hyperhive._bashEnvFragments != "") {
       # Non-interactive bash invocations (claude's `Bash` tool runs

nix/templates/manager.nix

@@ -6,9 +6,9 @@
   imports = [ ./harness-base.nix ];
 
   # The root/manager bootstraps a fresh hive, so it gets the hyperhive
-  # reference docs surfaced by default (the additive `CLAUDE.md` pointer
+  # reference docs made available by default (readable at
-  # → `$HIVE_DOCS_DIR/docs/setup.md`, added via `claude --add-dir`).
+  # `$HIVE_DOCS_DIR/`, added via `claude --add-dir`). `mkDefault` so a
-  # `mkDefault` so a manager's own `agent.nix` can still turn it off.
+  # manager's own `agent.nix` can still turn it off. Other agents default
-  # Other agents default off.
+  # off.
   hyperhive.docs.enable = lib.mkDefault true;
 }