diff --git a/flake.nix b/flake.nix
index d9d3fbee..85b4f623 100644
--- a/flake.nix
+++ b/flake.nix
@@ -212,6 +212,13 @@
           # NOT of `packages.default`, so the binary derivation stays
           # cached when a prompt edit ripples through.
           assets = pkgs.callPackage ./nix/assets.nix { };
+          # The repo docs/ markdown tree as a standalone derivation —
+          # agents read it in-container (added as a claude additional
+          # directory) and the website repo reuses it as a flake input,
+          # neither of which needs the branding/prompt assets. See
+          # nix/reference-docs.nix. (`docs` above is the auto-generated
+          # nix-options reference, a different artifact.)
+          reference-docs = pkgs.callPackage ./nix/reference-docs.nix { };
           # Pre-built per-container system closures. Exposed as packages
           # so operators can `nix build .#agent-base-toplevel` (or wire
           # them into their host system closure via the
@@ -255,6 +262,10 @@
           # so the harness module can wire $HIVE_ASSETS_DIR straight
           # to `${pkgs.hyperhive-assets}/share/hyperhive`.
           hyperhive-assets = self.packages.${prev.stdenv.hostPlatform.system}.assets;
+          # Standalone docs/ tree (see nix/reference-docs.nix). Exposed
+          # via the overlay so the harness module can build the
+          # in-container agent docs dir from it.
+          hyperhive-docs = self.packages.${prev.stdenv.hostPlatform.system}.reference-docs;
         };
         claude-unstable =
           final: prev:
diff --git a/hive-ag3nt/src/turn.rs b/hive-ag3nt/src/turn.rs
index be80156b..e44c732b 100644
--- a/hive-ag3nt/src/turn.rs
+++ b/hive-ag3nt/src/turn.rs
@@ -694,6 +694,16 @@ async fn run_claude(prompt: &str, files: &TurnFiles, bus: &Bus) -> Result<(bool,
         .arg(mcp::builtin_tools_arg())
         .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.
+    if let Some(docs_dir) = std::env::var_os("HIVE_DOCS_DIR")
+        && !docs_dir.is_empty()
+    {
+        cmd.arg("--add-dir").arg(&docs_dir);
+    }
     let mut child = cmd
         .stdin(Stdio::piped())
         .stdout(Stdio::piped())
diff --git a/nix/assets.nix b/nix/assets.nix
index a623607c..46b4ce9c 100644
--- a/nix/assets.nix
+++ b/nix/assets.nix
@@ -1,6 +1,5 @@
 {
   stdenv,
-  lib,
   librsvg,
 }:
 
@@ -12,6 +11,10 @@
 # Output layout:
 #   $out/share/hyperhive/branding/{hyperhive,agent-configs}.{svg,png}
 #   $out/share/hyperhive/prompts/{system.md, claude-settings.json}
+#
+# The repo docs/ tree is a SEPARATE derivation (nix/reference-docs.nix)
+# so agents can consume the docs without the branding+prompt assets and
+# the website repo can reuse it — see that file.
 
 stdenv.mkDerivation {
   pname = "hyperhive-assets";
@@ -56,6 +59,5 @@ stdenv.mkDerivation {
   meta = {
     description = "hyperhive static assets (branding + claude prompts)";
     homepage = "https://forge.darkest.space/hyperhive/hyperhive";
-    license = lib.licenses.mit;
   };
 }
diff --git a/nix/reference-docs.nix b/nix/reference-docs.nix
new file mode 100644
index 00000000..74a5c8c2
--- /dev/null
+++ b/nix/reference-docs.nix
@@ -0,0 +1,41 @@
+{
+  stdenv,
+}:
+
+# The repo `docs/` markdown tree, shipped as a standalone derivation so
+# agents can read the reference docs in-container (added as a claude
+# additional directory by the harness) WITHOUT pulling the branding +
+# prompt assets they don't need, and so the `hyperhive/website` repo can
+# reuse the exact same tree as a flake input.
+#
+# Pure data: the docs are copied verbatim (never transformed), so there
+# is no writable/build step — `$out` is the docs tree as-is.
+#
+# Output layout:
+#   $out/  — the repo `docs/` tree verbatim (e.g. `$out/setup.md`)
+
+stdenv.mkDerivation {
+  pname = "hyperhive-docs";
+  version = "0.1.0";
+  # Narrow src (just docs/) keeps this derivation's input hash decoupled
+  # from the rest of the tree — a doc edit only re-hashes this.
+  src = ../docs;
+
+  # No build: pure markdown, nothing to compile or render.
+  dontBuild = true;
+  dontConfigure = true;
+
+  installPhase = ''
+    runHook preInstall
+    mkdir -p $out
+    cp -r ./* $out/
+    runHook postInstall
+  '';
+
+  dontFixup = true;
+
+  meta = {
+    description = "hyperhive reference docs (the repo docs/ tree)";
+    homepage = "https://forge.darkest.space/hyperhive/hyperhive";
+  };
+}
diff --git a/nix/templates/harness-base.nix b/nix/templates/harness-base.nix
index 1da1bf1a..7a2c2473 100644
--- a/nix/templates/harness-base.nix
+++ b/nix/templates/harness-base.nix
@@ -210,6 +210,17 @@ in
     '';
   };
 
+  options.hyperhive.docs.enable = lib.mkEnableOption ''
+    make the hyperhive reference docs (the repo `docs/` tree, shipped
+    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/`. The agent is NOT yet pointed at the docs (no
+    auto-loaded `CLAUDE.md` pointer) — surfacing a pointer is a tracked
+    follow-up. Default-on for the root/manager agent (see `manager.nix`),
+    off elsewhere; any agent can flip it from its `agent.nix`.
+  '';
+
   options.hyperhive.allowedBashPatterns = lib.mkOption {
     type = lib.types.listOf lib.types.str;
     default = [ ];
@@ -1239,6 +1250,14 @@ in
       # (compact-on-overflow) still fires when the session is truly full.
       HIVE_COMPACT_WATERMARK_TOKENS = "0";
     }
+    // lib.optionalAttrs config.hyperhive.docs.enable {
+      # hyperhive.docs.enable: the in-container reference-docs tree
+      # (`pkgs.hyperhive-docs`, the repo docs/ verbatim). The harness
+      # reads this and passes it to claude as `--add-dir` so the docs are
+      # readable; the agent is not auto-pointed at them. See
+      # hive-ag3nt::turn.
+      HIVE_DOCS_DIR = "${pkgs.hyperhive-docs}";
+    }
     // lib.optionalAttrs (config.hyperhive._bashEnvFragments != "") {
       # Non-interactive bash invocations (claude's `Bash` tool runs
       # `bash -c`) source $BASH_ENV at startup — drops every active
diff --git a/nix/templates/manager.nix b/nix/templates/manager.nix
index 370bd9e1..b6a9d1ea 100644
--- a/nix/templates/manager.nix
+++ b/nix/templates/manager.nix
@@ -1,7 +1,14 @@
-{ ... }:
+{ lib, ... }:
 {
   # Entry-point for the privileged root agent (ruth). Referenced from
   # `flake.nix` (`nixosConfigurations.ruth`) and the meta-flake's
   # `applied/ruth/flake.nix`.
   imports = [ ./harness-base.nix ];
+
+  # The root/manager bootstraps a fresh hive, so it gets the hyperhive
+  # reference docs made available by default (readable at
+  # `$HIVE_DOCS_DIR/`, added via `claude --add-dir`). `mkDefault` so a
+  # manager's own `agent.nix` can still turn it off. Other agents default
+  # off.
+  hyperhive.docs.enable = lib.mkDefault true;
 }