docs/gotchas.md: extract nix/{assets,docs,templates/weston-vnc} prose (#718 batch 3)

- assets.nix: cargo-cache-invalidation rationale → "Split asset
  derivations away from the rust workspace" section.
- templates/weston-vnc.nix: port allocation, weston bind-address
  quirk, PAM service name, Type=simple choice, idle-time=0 →
  "Weston VNC compositor (per-agent hyperhive.gui.enable)" section.
- docs/default.nix: rendering pipeline + subtree-pick + output-tree
  history → "Nix options reference" section.

In-code comments trimmed to short purpose statements + docs pointers.
description = '' blocks (operator-facing options docs) preserved per
iris #718.

`nix flake check` + `nix build .#docs` clean.

nix/docs/default.nix

@@ -4,34 +4,15 @@
   self,
   nixosSystem,
 }:
-# Options documentation for hyperhive's NixOS module surfaces.
-# Closes #616. HTML output added per mara on internal-requests #8.
-#
-# Three rendering layers:
-#   CommonMark — `pkgs.nixosOptionsDoc.optionsCommonMark`. Source of
-#                truth; kept as `.md` files in the bundle.
-#   HTML       — `pkgs.cmark-gfm` over the CommonMark output, wrapped
-#                in a minimal inline-CSS template. Primary surface; the
-#                bundle's `index.html` / `host.html` / `agent.html` are
-#                what the operator's nginx serves from
-#                `hyperhive.darkest.space/options/`.
-#
-# Three output trees consumed by `flake.nix`:
-#   docs-host   — operator-facing host-module options
-#                 (`services.hive-c0re.*`, `hyperhive.{domain,forge,matrix}.*`)
-#   docs-agent  — per-agent harness options
-#                 (`hyperhive.{model,allowedRecipients,extraMcpServers,…}`)
-#   docs        — bundled static site (index + host + agent, .html + .md)
-#
-# All asset paths inside the rendered HTML are relative (e.g.
-# `./host.html`) so the bundle can be mounted at any URL prefix
-# without rewriting; styles are inline so there's no second-fetch
-# request for the operator's browser.
+# Nix options reference: `pkgs.nixosOptionsDoc` over two evaluated
+# module trees, rendered as CommonMark + HTML + bundled static site
+# the operator's nginx serves from `/options/`. Full pipeline +
+# subtree-pick / output-tree rationale: docs/gotchas.md::Nix options
+# reference.
 let
-  # Evaluate the host module under a stub NixOS system. Stubs satisfy
-  # the few hard-required options (filesystems, stateVersion) without
-  # actually enabling the hive — we only want the option *declarations*
-  # to evaluate, not the config.
+  # Stub host system: every hyperhive subsystem `mkForce false` so
+  # heavy build inputs (matrix container, forge, etc.) stay out of
+  # the eval — only option *declarations* matter for the doc walk.
   hostEval = nixosSystem {
     system = pkgs.stdenv.hostPlatform.system;
     modules = [
@@ -46,10 +27,6 @@ let
           };
           boot.loader.grub.enable = false;
           system.stateVersion = "25.11";
-          # Force-disable every hyperhive subsystem so config evaluation
-          # doesn't pull in heavy build inputs (matrix container, forge,
-          # etc.). Options are still fully declared either way — that's
-          # what nixosOptionsDoc traverses.
           services.hyperhive.enable = lib.mkForce false;
           services.hyperhive.forge.enable = lib.mkForce false;
           services.hyperhive.matrix.enable = lib.mkForce false;
@@ -59,14 +36,12 @@ let
     ];
   };
 
-  # Agent options live in the already-evaluated `agent-base` container
-  # config. Reusing it avoids re-evaluating the harness module against
-  # a fresh stub — the options tree is identical to what a real agent
-  # container sees.
+  # Reuse the already-evaluated agent-base config — its options tree is
+  # identical to what a real agent container sees, no second eval needed.
   agentEval = self.nixosConfigurations.agent-base;
 
-  # Strip the nix-store prefix from option declaration paths and rewrite
-  # them as forge URLs so the rendered docs link back to the source.
+  # Rewrite option declaration paths from nix-store absolute paths to
+  # forge URLs so rendered docs link back to source.
   forgeRoot = "https://forge.darkest.space/hyperhive/hyperhive/src/branch/main";
   storePrefix = toString self + "/";
   transformOptions =
@@ -90,10 +65,10 @@ let
       ) opt.declarations;
     };
 
-  # Filter an evaluated `options` tree down to a set of top-level
-  # subtrees we care about. Anything outside the listed roots is
-  # dropped — keeps the rendered docs focused on hyperhive's surface
-  # instead of NixOS's 10k+ default options.
+  # Filter to a set of top-level subtree roots — keeps the rendered docs
+  # focused on hyperhive's surface instead of NixOS's 10k+ default
+  # options. Root choice matters: see docs/gotchas.md::Nix options
+  # reference for the post-#615 services.hyperhive consolidation history.
   pickSubtrees =
     options: roots:
     let
@@ -106,12 +81,6 @@ let
     in
     lib.foldl' lib.recursiveUpdate { } (map pick roots);
 
-  # Post-#615, host options live entirely under `services.hyperhive.*`
-  # (closes #630). Pre-#615 had a mix of `hyperhive.*` (forge, matrix,
-  # domain) and `services.hive-c0re.*` — picking against those roots
-  # silently produced an empty options tree on current main, so the
-  # rendered host page was just the template chrome with no `<h2>`
-  # option headers underneath.
   hostOptions = pickSubtrees hostEval.options [
     [
       "services"
@@ -133,8 +102,7 @@ let
     inherit transformOptions;
   };
 
-  # Plain-markdown page (with a short header). Source of truth; the
-  # HTML version is rendered from this.
+  # CommonMark .md = source of truth; HTML is rendered from this.
   mkMarkdownPage =
     name: title: doc:
     pkgs.runCommand "hyperhive-${name}.md" { } ''
@@ -149,16 +117,11 @@ let
       } > $out
     '';
 
-  # Inline-stylesheet, loaded as plain text from `./style.css` so it's
-  # editable with normal CSS tooling (#625). Inlined into every page
-  # so the bundle doesn't depend on a second HTTP fetch — keeps the
-  # `/options/` mount trivial for nginx (no MIME guessing for separate
-  # .css files, no cache-busting needed when this updates).
+  # Loaded as text so it's editable with normal CSS tooling and
+  # inlined into every page (no second-fetch dependency).
   styleCSS = builtins.readFile ./style.css;
 
-  # HTML page: CommonMark → cmark-gfm → minimal template with inline
-  # CSS + relative-only links. cmark-gfm rather than plain cmark so
-  # any future tables / autolinks Just Work without revisiting.
+  # CommonMark → cmark-gfm → minimal template, inline CSS, relative links.
   mkHtmlPage =
     name: title: doc:
     pkgs.runCommand "hyperhive-${name}.html" { nativeBuildInputs = [ pkgs.cmark-gfm ]; } ''
@@ -192,9 +155,7 @@ let
       } > $out
     '';
 
-  # Landing page — same template shape as the option pages but
-  # hand-authored content (short intro + cross-links). Kept tight; the
-  # detail lives on the two option pages.
+  # Landing page — same template shape, hand-authored intro + cross-links.
   indexHTML = pkgs.runCommand "hyperhive-docs-index.html" { } ''
     {
       echo '<!doctype html>'
@@ -240,14 +201,11 @@ let
   agentMD = mkMarkdownPage "docs-agent" "hyperhive — per-agent options" agentDoc;
 in
 {
-  # Individual page outputs (HTML is the primary surface; the .md
-  # source is one `nix build` step away if needed).
   host = hostHTML;
   agent = agentHTML;
 
-  # Bundled static site for nginx to serve at `/options/`. Asset paths
-  # are all relative, no root-absolute references, so the prefix can
-  # change without rebuild.
+  # Bundled static site nginx serves at `/options/`. Asset paths are
+  # all relative so the prefix can change without rebuild.
   bundle = pkgs.runCommand "hyperhive-options-docs" { } ''
     mkdir -p $out
     cp ${indexHTML} $out/index.html