diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index 6a3114b1..04f4a15e 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -322,6 +322,25 @@ write_settings, write_system_prompt, run_turn, drive_turn,
 emit_turn_end, wait_for_login, compact_session}` — the single code path
 every agent role runs through.
 
+### Reference docs (`hyperhive.docs.enable`)
+
+```nix
+hyperhive.docs.enable = true;  # default: false (true for the manager agent)
+```
+
+Makes the hyperhive `docs/` tree available inside the container at a nix
+store path read from `$HIVE_DOCS_DIR`, and injects a single pointer
+sentence into the agent's system prompt so it knows the docs exist and
+where to find them. The tree is served by `claude --add-dir` so the full
+markdown is readable during every turn.
+
+Enabled by default only for the root/manager agent (`manager.nix`). Any
+agent can opt in by adding the line above to its `agent.nix`.
+
+The `docs/` source is a narrow flake input (`hyperhive-docs`) tracked
+separately from the main `hyperhive` flake so editing docs re-locks only
+that input — not every agent's container gets rebuilt on a doc-only change.
+
 ### Agent icon
 
 ```nix