diff --git a/nix/packages/reference-docs.nix b/nix/packages/reference-docs.nix
index 121a3ca8..3079a812 100644
--- a/nix/packages/reference-docs.nix
+++ b/nix/packages/reference-docs.nix
@@ -16,15 +16,15 @@
 # `docs.nix` (website repo) needs no changes to pick either up — it
 # already walks every subdirectory generically.
 #
-# For crates that is `$out/crates/<crate>.md`, one per workspace crate
+# For crates that is `$out/4-implementation/crates/<crate>.md`, one per workspace crate
 # with a README.md (mara's ask: "behaves as if hive-core/README.md lives
-# at docs/crates/hive-core.md" — lint:allow, a path this derivation
+# at docs/4-implementation/crates/hive-core.md" — lint:allow, a path this derivation
 # creates in $out, so the repo has no such file). The crate's own README
 # stays the single source of truth.
 #
 # Output layout:
 #   $out/                   — the repo docs/ tree verbatim
-#   $out/crates/<crate>.md  — one per workspace crate README
+#   $out/4-implementation/crates/<crate>.md — one per workspace crate README
 #   $out/options/*.md       — the nixosOptionsDoc bundle (`packages.docs`,
 #                             nix/docs/default.nix), copied verbatim —
 #                             already self-contained CommonMark, unlike
@@ -59,26 +59,26 @@ stdenv.mkDerivation {
     runHook preInstall
     mkdir -p $out
     cp -r ./* $out/
-    mkdir -p "$out/crates"
+    mkdir -p "$out/4-implementation/crates"
     cp -r "$optionsMd" "$out/options"
 
     for member in $members; do
       [ -f "$self/$member/README.md" ] || continue
       # Rewrite relative links that were correct from the crate's own
       # position in the repo tree but aren't once the file is
-      # virtually one level under docs/ instead:
-      #   ../docs/x.md      (crate root -> repo docs/)   -> ../x.md  lint:allow (stand-in name)
-      #     (crates/ -> docs/ is one directory shallower than
-      #     <crate>/ -> docs/ was, so the leading docs/ segment drops)
+      # virtually two levels under docs/ instead:
+      #   ../docs/x.md      (crate root -> repo docs/)   -> ../../x.md  lint:allow (stand-in name)
+      #     (4-implementation/crates/ -> docs/ is one directory deeper than
+      #     <crate>/ -> docs/ was, so the leading docs/ segment becomes ../)
       #   ../<sibling-crate> (that crate's own directory, no file; forge
       #     renders it as a directory listing) -> ./<sibling-crate>.md,
       #     since every crate README lives flat beside it under crates/.
-      fixups=(-e 's,\]\(\.\./docs/,](../,g')
+      fixups=(-e 's,\]\(\.\./docs/,](../../,g')
       for other in $members; do
         [ "$other" != "$member" ] || continue
         fixups+=(-e "s,\]\(\.\./$other(/)?\),](./$other.md),g")
       done
-      sed -E "''${fixups[@]}" "$self/$member/README.md" >"$out/crates/$member.md"
+      sed -E "''${fixups[@]}" "$self/$member/README.md" >"$out/4-implementation/crates/$member.md"
     done
 
     runHook postInstall
@@ -87,7 +87,7 @@ stdenv.mkDerivation {
   dontFixup = true;
 
   meta = {
-    description = "hyperhive reference docs (the repo docs/ tree, plus virtual crates/<crate>.md and options/*.md subdirs)";
+    description = "hyperhive reference docs (the repo docs/ tree, plus virtual 4-implementation/crates/<crate>.md and options/*.md subdirs)";
     homepage = "https://forge.darkest.space/hyperhive/hyperhive";
   };
 }