diff --git a/docs/gotchas.md b/docs/gotchas.md
index 23181fa3..7cfec7a7 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -323,11 +323,10 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
 ## Nix options reference (`nix/docs/default.nix`)
 
 `pkgs.nixosOptionsDoc` over two evaluated module trees:
-`hostEval` (a stub NixOS system loading `self.nixosModules.default`
-with every hyperhive subsystem `mkForce false` so heavy build
-inputs stay out of the eval) and `agentEval` (reuses the already-evaluated
-`agent-base` container config so the per-agent options tree is
-identical to what a real agent container sees).
+`hostEval` (a stub NixOS system loading `hive-c0re.nix` with every
+hyperhive subsystem `mkForce false` so heavy build inputs stay out of
+the eval) and `agentEval` (evaluates `agent-base.nix` fresh for the
+per-agent options tree).
 
 Three output trees consumed by `flake.nix`, all **markdown**:
 
@@ -356,3 +355,33 @@ Host options live entirely under `services.hyperhive.*`. The
 options tree picks up everything under that root — picking against
 stray roots produces an empty tree and renders the host page as
 template chrome with no `<h2>` headers.
+
+### Docs drv stability: `nixSrc` + stub overlay
+
+Naively, the docs evaluation depends on `self` (the flake's store path),
+so every commit — even Rust-only or frontend-only changes — produces new
+docs drv hashes. The remote builder must rebuild docs from scratch for
+every PR branch, and if its store is full the build fails with a cached
+failure that blocks CI for the whole branch.
+
+The fix (`nix/docs/default.nix`):
+
+1. **`nixSrc`** — `builtins.path` on the `nix/` directory, wrapped in
+   `builtins.unsafeDiscardStringContext` to strip `self`'s store-path
+   context. The resulting store path is content-addressed from the nix/
+   file contents only. Docs drvs only change when a `.nix` file changes.
+
+2. **`docsStubOverlay`** — replaces `self.overlays.default` with stub
+   packages (`pkgs.emptyFile` / `pkgs.emptyDirectory`) for the docs eval.
+   `nixosOptionsDoc` renders `defaultText` for all package options anyway;
+   the stubs prevent attribute-missing eval errors without pulling in the
+   Rust or frontend build closure.
+
+3. Both `hostEval` and `agentEval` are evaluated from `nixSrc` paths
+   (not `self`), so the docs drv dependency chain ends at `nixSrc`.
+
+Why `builtins.unsafeDiscardStringContext`? The path string
+`toString self + "/nix"` carries `self`'s string context, which would
+make `builtins.path` include `self` as a build dependency even after
+content-addressing the directory. Discarding the context makes the
+resulting `nixSrc` truly independent of `self`'s store path.