diff --git a/nix/packages/default.nix b/nix/packages/default.nix
index 90487908..25b8a848 100644
--- a/nix/packages/default.nix
+++ b/nix/packages/default.nix
@@ -221,11 +221,14 @@ in
   # 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
-  # ./reference-docs.nix. (`docs` below is the auto-generated
-  # nix-options reference, a different artifact.) `self` is needed to
-  # read each workspace crate's own README.md into the virtual
-  # `crates/` subdir.
-  reference-docs = pkgs.callPackage ./reference-docs.nix { inherit self; };
+  # ./reference-docs.nix. `self` is needed to read each workspace
+  # crate's own README.md into the virtual `crates/` subdir;
+  # `docsAttrs.bundle` (the same tree `docs` below exposes standalone)
+  # is projected into the virtual `options/` subdir the same way.
+  reference-docs = pkgs.callPackage ./reference-docs.nix {
+    inherit self;
+    optionsMd = docsAttrs.bundle;
+  };
   # XDG icon set + .desktop entries for hyperhive processes.
   # Narrow input: only the branding SVG, so unrelated source changes
   # don't bust this derivation's cache.
diff --git a/nix/packages/reference-docs.nix b/nix/packages/reference-docs.nix
index d8eae450..d44169ed 100644
--- a/nix/packages/reference-docs.nix
+++ b/nix/packages/reference-docs.nix
@@ -2,6 +2,7 @@
   stdenv,
   lib,
   self,
+  optionsMd,
 }:
 
 # The repo `docs/` markdown tree, shipped as a standalone derivation so
@@ -10,21 +11,19 @@
 # prompt assets they don't need, and so the `hyperhive/website` repo can
 # reuse the exact same tree as a flake input.
 #
-# The docs/ tree is copied verbatim (never transformed). On top of that,
-# `$out/crates/<crate>.md` is synthesized — one per workspace crate
-# with a README.md, virtualized under docs/ (mara's ask: "behaves as if
-# hive-core/README.md lives at docs/crates/hive-core.md"). The
-# crate's own README stays the single source of truth; this derivation
-# only projects it into the docs tree, so there is no second copy to keep
-# in sync by hand. `docs.nix` (website repo) needs no changes to pick these
-# up — it already walks every subdirectory + `.md` file generically.
+# The docs/ tree is copied verbatim. Two more subdirs are virtualized on
+# top of it, same reasoning for both: project an external source of
+# truth into the tree instead of hand-copying (and drifting) it.
+# `docs.nix` (website repo) needs no changes to pick either up — it
+# already walks every subdirectory generically.
 #
 # Output layout:
-#   $out/              — the repo docs/ tree verbatim (e.g. $out/setup.md)
-#   $out/crates/<crate>.md — one per workspace crate README, plus the
-#                            hand-written docs/crates/README.md
-#                            landing page (copied verbatim like any
-#                            other docs/ file, not generated here)
+#   $out/                   — the repo docs/ tree verbatim
+#   $out/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
+#                             the crate READMEs below, so no rewriting.
 
 let
   cargoToml = builtins.fromTOML (builtins.readFile ../../Cargo.toml);
@@ -58,7 +57,7 @@ stdenv.mkDerivation {
   # the alternative is hand-copying READMEs into docs/ and letting them
   # drift, which is the exact duplication this issue exists to avoid.
   src = ../../docs;
-  inherit self;
+  inherit self optionsMd;
 
   dontBuild = true;
   dontConfigure = true;
@@ -68,6 +67,7 @@ stdenv.mkDerivation {
     mkdir -p $out
     cp -r ./* $out/
     mkdir -p "$out/crates"
+    cp -r "$optionsMd" "$out/options"
 
     ${lib.concatMapStrings (member: ''
       if [ -f "$self/${member}/README.md" ]; then
@@ -94,7 +94,7 @@ stdenv.mkDerivation {
   dontFixup = true;
 
   meta = {
-    description = "hyperhive reference docs (the repo docs/ tree, plus a virtual crates/<crate>.md per workspace crate README)";
+    description = "hyperhive reference docs (the repo docs/ tree, plus virtual crates/<crate>.md and options/*.md subdirs)";
     homepage = "https://forge.darkest.space/hyperhive/hyperhive";
   };
 }