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/assets.nix

@@ -4,38 +4,24 @@
   librsvg,
 }:
 
-# Static assets the rust workspace reads at runtime: the project's
-# branding SVG/PNG family + the claude system-prompt template +
-# claude-settings JSON. Lives as its own derivation so a tweak to
-# branding/agent-configs.svg or hive-ag3nt/prompts/system.md doesn't
-# invalidate the rust derivation's cargo cache (closes #555 follow-up
-# to #538 — naersk previously paired with `src = ./.;` invalidating
-# every rust build on any branding/prompt edit; crane inherited that
-# coupling and this split breaks it cleanly).
+# Branding SVG/PNG family + claude prompts, split out from the rust
+# workspace so a tweak here doesn't invalidate the rust cargo cache.
+# Rationale + agent-configs PNG rendering: docs/gotchas.md::Split asset
+# derivations away from the rust workspace.
 #
 # Output layout:
-#
-#   $out/share/hyperhive/branding/{hyperhive.svg, hyperhive.png,
-#                                  agent-configs.svg, agent-configs.png}
+#   $out/share/hyperhive/branding/{hyperhive,agent-configs}.{svg,png}
 #   $out/share/hyperhive/prompts/{system.md, claude-settings.json}
-#
-# The agent-configs PNG is rendered at build time from the SVG via
-# rsvg-convert — same shape as the old `hive-c0re/build.rs` rasteriser,
-# just hoisted into nix so the librsvg dependency stays *here* instead
-# of in the rust derivation's nativeBuildInputs.
 
 stdenv.mkDerivation {
   pname = "hyperhive-assets";
   version = "0.1.0";
-  # `src` is intentionally narrow — only branding/ + the hive-ag3nt/prompts/
-  # subdir, NOT the whole tree. Keeps the input hash decoupled from
-  # rust source / docs / nix module edits.
+  # Narrow `srcs` (branding/ + hive-ag3nt/prompts/) is what decouples
+  # this derivation's input hash from the rest of the tree.
   srcs = [
     ../branding
     ../hive-ag3nt/prompts
   ];
-  # `unpackPhase` would normally extract each src to its own dir; we
-  # just want them side-by-side, so hand-roll a flat copy.
   unpackPhase = ''
     runHook preUnpack
     cp -r ${../branding} branding
@@ -46,10 +32,8 @@ stdenv.mkDerivation {
 
   nativeBuildInputs = [ librsvg ];
 
-  # No real build step — just render the agent-configs PNG alongside
-  # its SVG. 300×300 matches branding/hyperhive.png, which is the size
-  # Forgejo's avatar endpoint accepts without resampling on upload (the
-  # same constraint hive-c0re/build.rs encoded).
+  # 300×300 matches branding/hyperhive.png — the size Forgejo's avatar
+  # endpoint accepts without resampling on upload.
   buildPhase = ''
     runHook preBuild
     rsvg-convert --width 300 --height 300 \