diff --git a/apps/petrinaut-docs/README.md b/apps/petrinaut-docs/README.md
index 2e7f2ceecb0..48d2328e97f 100644
--- a/apps/petrinaut-docs/README.md
+++ b/apps/petrinaut-docs/README.md
@@ -90,30 +90,146 @@ its own `cookie@2.x` without changing hoisting for the rest of the monorepo.
 ## Chrome overrides
 
 [`src/styles/chrome.css`](src/styles/chrome.css), registered as Starlight's
-`customCss`, narrows both side panels to give the content column more width,
-tones down the header, and rounds the corners on markdown images so the embedded
-diagrams match the bordered cards beside them. The left nav takes its own
-`--pnd-sidebar-width` because Starlight sizes both panels from
-`--sl-sidebar-width`, and collapsing the nav has to zero one of them without
-flattening the other. The collapse toggle and resize handle come from
-`components.SiteTitle`, the header's leftmost slot, next to the rail they act
-on — and the fixed header is the one piece of chrome still on screen once the
-nav is gone. Both
-controls remember their state in `localStorage`, restored by a `head` script so
-a collapsed sidebar does not render open and then jump.
-
-## The code font
-
-Code renders in JetBrains Mono, requested through Astro's font support in
-[`astro.config.mjs`](astro.config.mjs) and emitted by `<Font>` in
-[`src/components/Head.astro`](src/components/Head.astro).
-
-A build downloads one variable file covering weights 400 to 700, subsets it to
-latin, and writes it beside the other assets, so a reader makes no request to a
-font host. The head carries a `preload` link and `font-display: swap`, and Astro
-generates a metric-matched fallback, which is what keeps text from shifting when
-the file arrives. The downloaded originals are cached under `.astro/`, which is
-ignored.
+`customCss`, holds the whole of the site's appearance in three parts.
+
+**Tokens.** Starlight's palette and type scale are restated in a flat
+monochrome key: one neutral ramp serving both themes, a header and sidebar that
+share the page background and carry no divider between them, and an accent
+pointed at the strongest foreground instead of a colour. That last one
+is why removing the blue took no hunting: Starlight routes links, the active nav
+row and the active table-of-contents row through the accent tokens. Links stay
+distinguishable by their underline. Type is 17px on a 1.65 leading with a
+heading scale shorter than Starlight's, so hierarchy comes from weight and space
+rather than size. Starlight defines `--sl-text-body` but never applies it, so
+the body size is set here or copy stays at the browser default. Blocks sit
+1.5rem apart and a section heading takes 2.25em above it, which is what makes a
+new section read as a break rather than another paragraph.
+
+Colour is left to what carries meaning: the diff badges, the asides, and the
+accents the bundle's own cards paint themselves. Nothing in the bundle is styled
+from here. Its CSS derives everything from `currentColor`, so it follows this
+palette on its own, in both themes and in any other host.
+
+**Components.** Sidebar and table-of-contents rows as pills, flat code frames
+(through the `--ec-*` variables Expressive Code reads), underlined monochrome
+links, and rounded corners on markdown images so the embedded diagrams match the
+bordered cards beside them. Controls read by fill: the search field and the
+diff-build compare chips sit one step off the page background rather than
+carrying an outline.
+
+The sidebar's depth guide is the only rule drawn anywhere in the chrome, and it
+is there because it carries information: how deep a row sits in the tree. The
+borders that framed the header, the sidebar, the on-this-page column and the
+bar it collapses into below 72rem are gone. That bar needed the one under it
+least of all: the fade band starts below it, so content dissolves before it
+reaches a line. Element borders stay where they separate content from the page: tables,
+code frames, and the markdown images that hold the diagrams.
+
+Both rails rest at 70% and come to full strength when the pointer or keyboard
+focus reaches them, over 300ms. The collapse toggle and the theme select rest
+further back at 50%: one small control in a wide header carries less than a
+column of text does. A press dips the toggle and springs it back past its own
+size.
+
+The header keeps no social links, so Starlight's `.social-icons::after` rule
+would leave a rule dividing nothing; the group is hidden while it holds no
+links, which brings it back if one is configured again. The theme select's
+focus ring is restated in the palette's greys, since the browser's own arrives
+as a thick blue rectangle over a control that has no border of its own. The hover target is the
+whole rail, so the reveal does not depend on landing on a row, and the opacity
+sits on each rail's inner element rather than the scrolling pane, which already
+owns a transition for the collapse. `prefers-reduced-transparency` turns the
+whole effect off.
+
+Under the header, over the content column only, a band blurs and tints whatever
+scrolls beneath it, so text does not meet the header on a hard edge. It runs to
+two heights: the tint over 45px and the blur over 60px. Matching them hid the
+blur completely, because the tint is opaque where the blur is strongest; the
+stretch below the tint is where a reader actually sees content blurred.
+
+`backdrop-filter` takes a single radius, so the ramp comes from the mask rather
+than from the filter: one layer fills the band at 0.5px of blur, at full strength
+for its top half and out to nothing by its bottom, which is what keeps the blur
+from ending on a line across the page.
+
+Both bands grow out of scroll and neither exists before it. The header script
+writes progress from 0 to 1 over the first 20px, and a band's height, its tint
+and its opacity all come off that one number, so an unscrolled page has nothing
+laid over it at all. Twenty is well under one row, so a band is there as soon as
+anything has gone up behind the header and the ramp only takes the hard edge off
+its arrival. Nothing eases it: the value already tracks the scroll frame by
+frame, and a transition on top would only make a band lag the rows it covers.
+
+The nav reads its own `scrollTop` rather than the window's, since the rail
+scrolls independently of the page, and carries a second band at its foot,
+mirrored: box, layer, mask and tint all run upwards from the bottom edge. That
+one is driven by what is left below the fold rather than by what has gone above
+it, so a rail short enough to need no scrolling never shows one and the band
+closes as the last rows arrive. Opening a group changes how much is left without
+scrolling anything, so a `ResizeObserver` on the rail's content recomputes it. The content band starts below
+`--sl-mobile-toc-height` as well as the header: between 50rem and 72rem
+Starlight moves the on-this-page column into a bar under the header, which the
+band would otherwise blur. The band is positioned against the viewport from
+`components.SiteTitle`, like the resize handle, and its right inset restates
+Starlight's own width for the on-this-page column since no variable holds it.
+
+**The sidebar.** The left nav takes its own `--pnd-sidebar-width` because
+Starlight sizes both panels from `--sl-sidebar-width`, and collapsing the nav has
+to zero one of them without flattening the other. The collapse toggle and resize
+handle come from `components.SiteTitle`, which renders at the header's leading
+edge, next to the rail they act on. The fixed header is also the one piece of chrome
+still on screen once the nav is gone. Both controls remember their state in
+`localStorage`, restored by a `head` script so a collapsed sidebar does not
+render open and then jump.
+
+Collapsing is animated, which is what the shape of those rules is for. The pane
+keeps its box and hides with `visibility` rather than `display: none`, so there
+is something to animate and the rows stay painted for the whole collapse. The
+content column derives its inset as `max(sidebar-width, 2rem)`, so the toggle
+moves one length between two ends instead of jumping between two unrelated
+values. Every box that sizes off the sidebar width or `--sl-content-width`
+transitions on the same curve, otherwise the column separates from the pane it
+is following.
+
+A drag is the opposite case: it already tracks the pointer frame by frame, and a
+transition on top of that makes the pane lag. The handle sets
+`data-pnd-resizing` for the length of a gesture, either a pointer drag or a held
+arrow key, and the transitions do not apply while it is set. The handle keeps a
+6px hit area with a 2px mark that fades in on hover, and writes to
+`localStorage` once on release rather than on every pointer position. All of the
+motion is behind `prefers-reduced-motion`.
+
+## Diagrams are inlined
+
+The bundle emits each rendered diagram as a plain markdown image, which is what
+keeps it portable. Behind an `<img>` an SVG is a separate document, so nothing
+on the page reaches it: not this site's palette, not its custom properties, not
+the theme it is currently set to.
+[`src/plugins/inline-diagrams.mjs`](src/plugins/inline-diagrams.mjs) replaces
+those images with the SVG itself at build time, which hands it all three. The
+generator writes every colour in the SVG as
+`var(--pnd-diagram-*, <the colour d2 drew>)`, and `chrome.css` defines those
+properties for dark mode; light mode needs nothing, because the fallbacks are
+already the light palette.
+
+The plugin is registered through `markdown.rehypePlugins`, which is why
+`@astrojs/markdown-remark` is a dependency: Astro no longer installs it by
+default, and the hook does nothing without it.
+
+## The fonts
+
+Body text renders in Inter and code in JetBrains Mono, both requested through
+Astro's font support in [`astro.config.mjs`](astro.config.mjs) and emitted by
+`<Font>` in [`src/components/Head.astro`](src/components/Head.astro). Inter
+stands in for the grotesque the reference design uses, which is not licensed for
+redistribution.
+
+A build downloads one variable file per family covering weights 400 to 700,
+subsets it to latin, and writes it beside the other assets, so a reader makes no
+request to a font host. The head carries a `preload` link and `font-display:
+swap`, and Astro generates a metric-matched fallback, which is what keeps text
+from shifting when the file arrives. The downloaded originals are cached under
+`.astro/`, which is ignored.
 
 ## Deployment
 
diff --git a/apps/petrinaut-docs/astro.config.mjs b/apps/petrinaut-docs/astro.config.mjs
index 33853d50532..570b66addf4 100644
--- a/apps/petrinaut-docs/astro.config.mjs
+++ b/apps/petrinaut-docs/astro.config.mjs
@@ -7,6 +7,7 @@ import starlight from "@astrojs/starlight";
 import { defineConfig, fontProviders } from "astro/config";
 
 import { resolveDiffCompareContext } from "./src/diff-context";
+import { rehypeInlineDiagrams } from "./src/plugins/inline-diagrams.mjs";
 
 /**
  * Renders the architecture bundle produced by `@local/petrinaut-arch-docs`.
@@ -290,10 +291,28 @@ export default defineConfig({
     define: {
       __PND_DIFF_COMPARE__: JSON.stringify(diffCompareContext),
     },
+
+    /*
+     * Lightning CSS folds the animation longhands into the `animation`
+     * shorthand, and puts the timeline in it: `animation: linear both
+     * pnd-fade-grow scroll(root)`. No browser accepts a timeline there — it was
+     * dropped from the shorthand while the spec settled — so the whole
+     * declaration is invalid and `animation-name` computes to `none`. That
+     * killed the scroll-driven fade bands in built output only, while the
+     * unminified dev server kept working, and the header script had already
+     * stood down because the browser does support the feature.
+     *
+     * esbuild minifies these rules without rewriting them.
+     */
+    build: { cssMinify: "esbuild" },
   },
 
   ...(hasAuthoredIndex ? {} : { redirects: { "/": "/architecture" } }),
 
+  // Diagrams arrive as markdown images and are inlined so the page's palette
+  // reaches them; see the plugin.
+  markdown: { rehypePlugins: [rehypeInlineDiagrams] },
+
   // The bundle's inter-page links are relative and assume slugs map to URLs
   // without a trailing slash. `format: "file"` writes `views.html` rather than
   // `views/index.html`, so there is no trailing-slash form of a URL for a reader
@@ -303,11 +322,33 @@ export default defineConfig({
   build: { format: "file" },
 
   /*
-   * One variable file covers every weight the code blocks use, downloaded and
-   * subset at build time so a reader makes no request to a font host. Italic is
-   * left out: no code style in the docs uses it.
+   * One variable file per family covers every weight the site uses, downloaded
+   * and subset at build time so a reader makes no request to a font host.
+   * Italic is left out of both: no style in the docs uses it.
+   *
+   * Inter stands in for the grotesque the reference design uses, which is not
+   * licensed for redistribution. It is the closest freely available match on
+   * the details that carry that look: a tall x-height, flat terminals, and
+   * digits that hold their width.
    */
   fonts: [
+    {
+      provider: fontProviders.fontsource(),
+      name: "Inter",
+      cssVariable: "--pnd-font-sans",
+      weights: ["400 700"],
+      styles: ["normal"],
+      subsets: ["latin"],
+      fallbacks: [
+        "-apple-system",
+        "BlinkMacSystemFont",
+        "Segoe UI",
+        "Roboto",
+        "Helvetica Neue",
+        "Arial",
+        "sans-serif",
+      ],
+    },
     {
       provider: fontProviders.fontsource(),
       name: "JetBrains Mono",
@@ -355,13 +396,6 @@ export default defineConfig({
 } catch {}`,
         },
       ],
-      social: [
-        {
-          icon: "github",
-          label: "GitHub",
-          href: "https://github.com/hashintel/hash/tree/main/libs/@hashintel/petrinaut",
-        },
-      ],
       sidebar: buildSidebar(),
       // No llms.txt plugin: the bundle emits its own `architecture.md` and
       // `architecture.json`, which `scripts/sync-bundle.mjs` copies into
diff --git a/apps/petrinaut-docs/package.json b/apps/petrinaut-docs/package.json
index 05d336031fb..f03d044e4ad 100644
--- a/apps/petrinaut-docs/package.json
+++ b/apps/petrinaut-docs/package.json
@@ -6,13 +6,14 @@
   "license": "(MIT OR Apache-2.0)",
   "type": "module",
   "scripts": {
-    "build": "astro build",
+    "build": "astro build && node scripts/check-built-css.mjs",
     "dev": "astro dev --port ${PORT:-4321}",
     "lint:tsc": "astro check --minimumSeverity error",
     "preview": "astro preview",
     "sync:bundle": "node scripts/sync-bundle.mjs"
   },
   "dependencies": {
+    "@astrojs/markdown-remark": "7.2.4",
     "@astrojs/react": "6.0.2",
     "@astrojs/starlight": "0.41.5",
     "astro": "7.1.6",
@@ -26,7 +27,9 @@
     "@types/node": "22.18.13",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "typescript": "5.9.3"
+    "hast-util-from-html": "2.0.3",
+    "typescript": "5.9.3",
+    "unist-util-visit": "5.1.0"
   },
   "engines": {
     "node": "22.x"
diff --git a/apps/petrinaut-docs/scripts/check-built-css.mjs b/apps/petrinaut-docs/scripts/check-built-css.mjs
new file mode 100644
index 00000000000..6bc497cce88
--- /dev/null
+++ b/apps/petrinaut-docs/scripts/check-built-css.mjs
@@ -0,0 +1,156 @@
+/**
+ * Checks the built stylesheets for rewrites that silently disable the chrome.
+ *
+ * This exists because one already happened. A CSS minifier folded the scroll
+ * timeline into the `animation` shorthand — `animation: linear both
+ * pnd-fade-grow scroll(root)` — and no browser accepts a timeline there, so the
+ * declaration was invalid and `animation-name` computed to `none`. The fade
+ * bands were dead in every built page while the unminified dev server kept
+ * working, and nothing failed: the header script stands down whenever the
+ * browser supports the CSS path, which it did.
+ *
+ * A build that produces no bands should not be publishable, so the shapes that
+ * carried that bug are asserted against here rather than left to a reader.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const assetsDir = path.join(import.meta.dirname, "..", "dist", "_astro");
+
+/** A timeline inside the `animation` shorthand: the rewrite that broke it. */
+const timelineInShorthand =
+  /animation\s*:[^;}]*\b(?:scroll|view)\s*\(|animation\s*:[^;}]*--pnd-nav-scroll/u;
+
+/**
+ * Every custom property naming a resting opacity, wherever it is declared.
+ *
+ * @param {string} css
+ * @returns {Set<string>}
+ */
+const idleOpacityTokens = (css) =>
+  new Set(
+    [...css.matchAll(/(--pnd-[a-z-]*idle-opacity)\s*:/gu)].map(
+      (match) => match[1],
+    ),
+  );
+
+/**
+ * The body of the `prefers-reduced-transparency` rule, braces balanced.
+ *
+ * @param {string} css
+ * @returns {string | null}
+ */
+const reducedTransparencyBlock = (css) => {
+  const opening = css.search(/@media[^{]*prefers-reduced-transparency[^{]*\{/u);
+
+  if (opening === -1) {
+    return null;
+  }
+
+  let depth = 0;
+
+  for (let at = css.indexOf("{", opening); at < css.length; at += 1) {
+    if (css[at] === "{") {
+      depth += 1;
+    } else if (css[at] === "}") {
+      depth -= 1;
+
+      if (depth === 0) {
+        return css.slice(opening, at + 1);
+      }
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Which resting opacities the reduced-transparency rule forgets to lift.
+ *
+ * A reader who asks for less transparency should get all of the chrome at full
+ * strength, and each of these tokens holds back one piece of it. Nothing ties a
+ * new token to that rule, so splitting one out silently leaves its element
+ * faded — which is how the left rail came to be the only thing still at 52.5%
+ * for exactly the readers who had asked it not to be.
+ *
+ * @param {string} css
+ * @returns {string[]}
+ */
+const unreset = (css) => {
+  const tokens = idleOpacityTokens(css);
+
+  if (tokens.size === 0) {
+    return [];
+  }
+
+  const block = reducedTransparencyBlock(css);
+
+  if (block === null) {
+    return [...tokens];
+  }
+
+  return [...tokens].filter((token) => !block.includes(`${token}:`));
+};
+
+/**
+ * @type {{
+ *   name: string,
+ *   failing: (css: string) => boolean,
+ *   detail?: (css: string) => string,
+ * }[]}
+ */
+const checks = [
+  {
+    name: "no scroll timeline folded into the `animation` shorthand",
+    failing: (css) => timelineInShorthand.test(css),
+  },
+  {
+    name: "the scroll-driven bands still declare a timeline",
+    failing: (css) =>
+      css.includes("pnd-fade-grow") && !css.includes("animation-timeline:"),
+  },
+  {
+    name: "`--pnd-fade-progress` is still registered, so it can interpolate",
+    failing: (css) =>
+      css.includes("pnd-fade-grow") &&
+      !css.includes("@property --pnd-fade-progress"),
+  },
+  {
+    name: "every resting opacity is lifted under prefers-reduced-transparency",
+    failing: (css) => unreset(css).length > 0,
+    detail: (css) => unreset(css).join(", "),
+  },
+];
+
+const files = (await readdir(assetsDir)).filter((name) =>
+  name.endsWith(".css"),
+);
+
+if (files.length === 0) {
+  console.error(`no stylesheets in ${assetsDir}; run the build first`);
+  process.exit(1);
+}
+
+const failures = [];
+
+for (const file of files) {
+  const css = await readFile(path.join(assetsDir, file), "utf8");
+
+  for (const check of checks) {
+    if (check.failing(css)) {
+      const detail = check.detail?.(css);
+      failures.push(`${file}: ${check.name}${detail ? ` (${detail})` : ""}`);
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error("built CSS check failed:");
+  for (const failure of failures) {
+    console.error(`  ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log(`built CSS check passed over ${files.length} stylesheets`);
diff --git a/apps/petrinaut-docs/src/components/Head.astro b/apps/petrinaut-docs/src/components/Head.astro
index 8d5b9f56bf2..64dd0ce63bd 100644
--- a/apps/petrinaut-docs/src/components/Head.astro
+++ b/apps/petrinaut-docs/src/components/Head.astro
@@ -1,8 +1,9 @@
 ---
 /**
- * Starlight's head, plus the font faces and preload links for the code font.
+ * Starlight's head, plus the font faces and preload links for the two families
+ * the site uses.
  *
- * Astro's `<Font>` emits both, so the family has to be requested from a
+ * Astro's `<Font>` emits both, so each family has to be requested from a
  * component in the head rather than from configuration alone.
  */
 
@@ -11,4 +12,5 @@ import { Font } from "astro:assets";
 ---
 
 <Default><slot /></Default>
+<Font cssVariable="--pnd-font-sans" preload />
 <Font cssVariable="--pnd-font-mono" preload />
diff --git a/apps/petrinaut-docs/src/components/SiteTitle.astro b/apps/petrinaut-docs/src/components/SiteTitle.astro
index 732e74cbca7..039ffd50431 100644
--- a/apps/petrinaut-docs/src/components/SiteTitle.astro
+++ b/apps/petrinaut-docs/src/components/SiteTitle.astro
@@ -51,6 +51,22 @@ import DiffBadges from "./DiffBadges.astro";
 >
 </div>
 
+{/*
+  The band of blur under the header, over the content column only. Rendered
+  here for the same reason as the resize handle: this component renders at the
+  header's leading edge, and the element is positioned against the viewport
+  rather than laid out in the header. One span, carrying the blur that the
+  band's mask ramps out. See `chrome.css`.
+*/}
+<div class="pnd-fade pnd-content-fade" aria-hidden="true"><span></span></div>
+
+{/* The same band over the nav, grown out of how far the rail has scrolled, and
+    a mirrored one at its foot for whatever is still below the fold. */}
+<div class="pnd-fade pnd-nav-fade" aria-hidden="true"><span></span></div>
+<div class="pnd-fade pnd-fade-up pnd-nav-fade-bottom" aria-hidden="true">
+  <span></span>
+</div>
+
 <script is:inline>
   (() => {
     const root = document.documentElement;
@@ -95,40 +111,121 @@ import DiffBadges from "./DiffBadges.astro";
       remember("pnd:sidebar", collapsed ? "collapsed" : "expanded");
     });
 
-    /** @param {number} edge Where the pane's trailing edge should land, in px. */
-    const resizeTo = (edge) => {
-      const width = `${Math.round(Math.min(Math.max(edge, 224), 480))}px`;
+    /**
+     * The pane width that puts its trailing edge at `edge`, clamped to the
+     * range the rail stays usable in.
+     *
+     * @param {number} edge In px, from the viewport's inline start.
+     * @returns {number}
+     */
+    const widthFrom = (edge) =>
+      Math.round(Math.min(Math.max(edge, 224), 480));
+
+    /** @param {number} width */
+    const applyWidth = (width) => {
+      root.style.setProperty("--pnd-sidebar-open-width", `${width}px`);
+    };
+
+    /** The edge the handle is currently drawn at, in px. */
+    const currentEdge = () => handle.getBoundingClientRect().left + 3;
 
-      root.style.setProperty("--pnd-sidebar-open-width", width);
-      remember("pnd:sidebar-width", width);
+    /**
+     * Marks a gesture that tracks its own input. `chrome.css` reads this to
+     * drop the toggle's width transitions while it is set: a transition on a
+     * value the pointer is already moving leaves the pane trailing the cursor
+     * by the whole duration.
+     *
+     * @param {boolean} active
+     */
+    const setResizing = (active) => {
+      if (active) {
+        root.dataset.pndResizing = "";
+      } else {
+        delete root.dataset.pndResizing;
+      }
     };
 
     handle.addEventListener("pointerdown", (event) => {
       handle.setPointerCapture(event.pointerId);
+      setResizing(true);
+
+      let width = widthFrom(currentEdge());
+      let frame = 0;
 
       /** @param {PointerEvent} move */
-      const onMove = (move) => resizeTo(move.clientX);
+      const onMove = (move) => {
+        width = widthFrom(move.clientX);
+        // A pointer reports several moves per frame at high polling rates, and
+        // every write invalidates layout for the pane, the content column and
+        // both panels sized from it. One write per frame is all a display can
+        // show anyway.
+        frame ||= requestAnimationFrame(() => {
+          frame = 0;
+          applyWidth(width);
+        });
+      };
 
       handle.addEventListener("pointermove", onMove);
       // `lostpointercapture` covers the cancelled gesture as well as the
       // released one, so the drag cannot outlive the pointer holding it.
       handle.addEventListener(
         "lostpointercapture",
-        () => handle.removeEventListener("pointermove", onMove),
+        () => {
+          handle.removeEventListener("pointermove", onMove);
+          cancelAnimationFrame(frame);
+          applyWidth(width);
+          setResizing(false);
+          // Once per gesture, not once per move: `localStorage` writes
+          // synchronously and a drag produces hundreds of positions.
+          remember("pnd:sidebar-width", `${width}px`);
+        },
         { once: true },
       );
     });
 
+    /**
+     * The width a keyboard gesture has reached, persisted when it ends.
+     *
+     * @type {number | null}
+     */
+    let keyedWidth = null;
+
     handle.addEventListener("keydown", (event) => {
       const step =
         event.key === "ArrowLeft" ? -16 : event.key === "ArrowRight" ? 16 : 0;
 
-      if (step !== 0) {
-        event.preventDefault();
-        resizeTo(handle.getBoundingClientRect().left + 3 + step);
+      if (step === 0) {
+        return;
       }
+
+      event.preventDefault();
+      // A held arrow key tracks its input as much as a drag does, so it
+      // suppresses the transition the same way rather than chasing each
+      // repeat 200ms behind.
+      setResizing(true);
+
+      keyedWidth = widthFrom(currentEdge() + step);
+      applyWidth(keyedWidth);
     });
 
+    /*
+     * Held down, an arrow key repeats about thirty times a second, and
+     * `localStorage` writes synchronously. The width is kept in hand and
+     * written once the gesture ends, the same as a drag.
+     */
+    const endKeyGesture = () => {
+      setResizing(false);
+
+      if (keyedWidth !== null) {
+        remember("pnd:sidebar-width", `${keyedWidth}px`);
+        keyedWidth = null;
+      }
+    };
+
+    // Both, because a key released after focus has moved on fires only `blur`.
+    handle.addEventListener("keyup", endKeyGesture);
+    handle.addEventListener("blur", endKeyGesture);
+
     // A gradient cannot ask whether the text fits, so the labels that do not
     // fit are marked here and the fade keys off the mark. Deferred because this
     // script is in the header, which the browser parses before the sidebar.
@@ -166,8 +263,100 @@ import DiffBadges from "./DiffBadges.astro";
       });
     };
 
+    /**
+     * Scroll, in px, over which a fade band reaches its full height. Well under
+     * one row of the rail: a band is there as soon as anything has gone up
+     * behind the header, and the ramp only takes the hard edge off its arrival.
+     *
+     * Read from `--pnd-fade-ramp` rather than repeated: the scroll-driven path
+     * in `chrome.css` takes its `animation-range` from the same token, and the
+     * two ramps have to agree.
+     */
+    const FADE_RAMP =
+      parseFloat(getComputedStyle(root).getPropertyValue("--pnd-fade-ramp")) ||
+      20;
+
+    /**
+     * Drives a scroll container's bands. `chrome.css` takes each band's height,
+     * its tint and its opacity from its number, so at 0 there is no band and
+     * nothing is laid over the content.
+     *
+     * Read once up front as well as on scroll: the page can load part-way down
+     * at an anchor, and Starlight restores the rail's scroll position on
+     * navigation.
+     *
+     * @param {EventTarget} source
+     * @param {Record<string, () => number>} readings Px remaining, per property.
+     * @returns {() => void} Recomputes, for when the content changes size.
+     */
+    const trackFade = (source, readings) => {
+      let frame = 0;
+
+      const write = () => {
+        frame = 0;
+        for (const [property, distance] of Object.entries(readings)) {
+          root.style.setProperty(
+            property,
+            String(Math.min(distance() / FADE_RAMP, 1)),
+          );
+        }
+      };
+
+      // Scroll fires faster than the display refreshes, and each write
+      // invalidates a band's height.
+      const schedule = () => {
+        frame ||= requestAnimationFrame(write);
+      };
+
+      write();
+      source.addEventListener("scroll", schedule, { passive: true });
+
+      return schedule;
+    };
+
+    /*
+     * The bands are scroll-driven animations wherever CSS can express them,
+     * which is everywhere but Firefox as of writing. There the progress cannot
+     * be resolved from layout, so it is written from a scroll listener instead,
+     * at the cost of a frame on a page that loads part-way down. `chrome.css`
+     * tests the same condition, and its animations override what is written
+     * here, so this only has to stay out of the way.
+     */
+    const cssDrivesFades =
+      CSS.supports("animation-timeline: scroll()") &&
+      CSS.supports("timeline-scope: --pnd-nav-scroll");
+
+    const watchScrollFades = () => {
+      if (cssDrivesFades) {
+        return;
+      }
+
+      const pane = document.querySelector(".sidebar-pane");
+
+      if (pane) {
+        // The rail scrolls independently of the page, so it reads its own
+        // position: what has gone above the fold, and what is left below it.
+        const refresh = trackFade(pane, {
+          "--pnd-nav-progress": () => pane.scrollTop,
+          "--pnd-nav-end-progress": () =>
+            pane.scrollHeight - pane.scrollTop - pane.clientHeight,
+        });
+
+        // Opening a group changes how much is left below the fold without
+        // scrolling anything, so the foot band has to be recomputed then too.
+        const content = pane.querySelector(".sidebar-content");
+
+        if (content) {
+          new ResizeObserver(refresh).observe(content);
+        }
+      }
+
+      trackFade(window, { "--pnd-content-progress": () => window.scrollY });
+    };
+
     const onReady = () => {
       markLabels();
+      watchScrollFades();
       allowGroupAnimation();
     };
 
diff --git a/apps/petrinaut-docs/src/plugins/inline-diagrams.mjs b/apps/petrinaut-docs/src/plugins/inline-diagrams.mjs
new file mode 100644
index 00000000000..647356d7efc
--- /dev/null
+++ b/apps/petrinaut-docs/src/plugins/inline-diagrams.mjs
@@ -0,0 +1,89 @@
+/**
+ * Inlines the bundle's rendered diagrams into the page instead of leaving them
+ * as `<img>`.
+ *
+ * The bundle emits every diagram as a plain markdown image, which keeps it
+ * portable: any host can render it with no toolchain of its own. The cost is
+ * that an SVG behind an `<img>` is a separate document, so nothing on the page
+ * reaches it — not this site's palette, not its custom properties, not the
+ * theme it is currently set to. Inlining the same file hands it all three.
+ *
+ * The generator writes each diagram's colours as `var(--pnd-diagram-*, <the
+ * colour d2 drew>)`, so a host that does none of this still gets the diagram it
+ * always got. `chrome.css` is what defines those properties here.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { fromHtml } from "hast-util-from-html";
+import { visit } from "unist-util-visit";
+
+/**
+ * Diagrams live beside the pages, under the bundle's own directory.
+ *
+ * @param {unknown} src
+ * @returns {src is string}
+ */
+const isDiagram = (src) =>
+  typeof src === "string" && src.endsWith(".svg") && src.includes("diagrams/");
+
+/**
+ * @returns {(tree: import("hast").Root, file: import("vfile").VFile) => void}
+ */
+export const rehypeInlineDiagrams = () => (tree, file) => {
+  if (typeof file.path !== "string") {
+    return;
+  }
+
+  const pageDirectory = dirname(file.path);
+
+  visit(tree, "element", (node, index, parent) => {
+    const src = node.properties?.["src"];
+
+    if (
+      node.tagName !== "img" ||
+      parent === undefined ||
+      index === undefined ||
+      !isDiagram(src)
+    ) {
+      return;
+    }
+
+    const path = resolve(pageDirectory, src);
+
+    let markup;
+
+    try {
+      markup = readFileSync(path, "utf8");
+    } catch {
+      // A page referencing a diagram the bundle did not render is the
+      // generator's problem to report; leaving the `<img>` alone keeps the
+      // broken reference visible rather than swallowing it.
+      return;
+    }
+
+    const parsed = fromHtml(markup, { space: "svg", fragment: true });
+    const svg = parsed.children.find(
+      /** @returns {child is import("hast").Element} */
+      (child) => child.type === "element" && child.tagName === "svg",
+    );
+
+    if (svg === undefined) {
+      return;
+    }
+
+    const alt = node.properties?.["alt"];
+
+    // The alt text was the image's accessible name, so it has to become the
+    // inline element's; without a role an <svg> is not exposed as an image.
+    svg.properties = {
+      ...svg.properties,
+      class: "pnd-diagram",
+      role: "img",
+      ...(typeof alt === "string" && alt !== "" ? { "aria-label": alt } : {}),
+    };
+
+    parent.children[index] = svg;
+  });
+};
diff --git a/apps/petrinaut-docs/src/styles/chrome.css b/apps/petrinaut-docs/src/styles/chrome.css
index 66a389c5c7f..e3bbdc1fd35 100644
--- a/apps/petrinaut-docs/src/styles/chrome.css
+++ b/apps/petrinaut-docs/src/styles/chrome.css
@@ -7,10 +7,698 @@
  * there, so the `:root[data-has-sidebar]` prefixes below are load-bearing
  * specificity, not decoration.
  *
+ * The file runs in three parts: the tokens, which restate Starlight's own
+ * palette and type scale in a flat monochrome key; the component rules that
+ * follow from them; and the sidebar's collapse, resize and motion behaviour.
+ *
  * Every sidebar rule is gated on `[data-has-sidebar]`: the 404 page uses the
  * splash template, which has no sidebar to toggle, resize, or collapse.
  */
 
+/* Tokens ----------------------------------------------------------------- */
+
+:root {
+  /*
+   * One neutral ramp for both themes, matching the scale openai.com uses. The
+   * chrome is monochrome. Colour is left to what carries meaning: the diff
+   * badges, the asides, and the accents the bundle's own cards paint
+   * themselves.
+   */
+  --pnd-gray-0: #fff;
+  --pnd-gray-50: #f9f9f9;
+  --pnd-gray-75: #f3f3f3;
+  --pnd-gray-100: #e8e8e8;
+  --pnd-gray-200: #cdcdcd;
+  --pnd-gray-300: #afafaf;
+  --pnd-gray-400: #8f8f8f;
+  --pnd-gray-500: #5d5d5d;
+  --pnd-gray-600: #414141;
+  --pnd-gray-700: #303030;
+  --pnd-gray-800: #212121;
+  --pnd-gray-900: #181818;
+  --pnd-gray-1000: #000;
+
+  --pnd-radius-sm: 0.375rem;
+  --pnd-radius: 0.625rem;
+  --pnd-radius-lg: 0.875rem;
+
+  --pnd-motion-duration: 200ms;
+  --pnd-motion-ease: cubic-bezier(0.32, 0.72, 0, 1);
+
+  /* The chrome sits back until it is pointed at. The toggle sits back further:
+     it is one small control against a wide header, not a column of text. */
+  --pnd-chrome-idle-opacity: 0.7;
+  --pnd-rail-idle-opacity: 0.525;
+  --pnd-toggle-idle-opacity: 0.375;
+  --pnd-chrome-fade: 300ms;
+
+  /*
+   * Resting the chrome behind an opacity composites its text against the page
+   * before anyone reads it, so what a reader sees is never the colour written
+   * here. These are the strongest greys the palette offers at each step, which
+   * is what keeps the composite as legible as the chosen opacities allow.
+   *
+   * Those opacities are a deliberate design choice and they cost contrast. At
+   * the rail's 52.5% and the toggle's 37.5% the composite is 3.1:1 dark and
+   * 3.1:1 light for rail text, against the 4.5:1 body text owes, and 2.5:1 /
+   * 2.3:1 for the toggle's icon against 3:1. Raising the grey cannot close
+   * that: at 52.5% over a white page even pure black reaches only 4.35:1, and
+   * at 37.5% only 2.6:1. Closing it means a higher resting opacity, not a
+   * different colour.
+   *
+   * Both come to full strength on hover and on keyboard focus, and
+   * `prefers-reduced-transparency` turns the fade off altogether. Measure
+   * rather than assume after any change here: the ratio is of the composited
+   * colour, which is not the one written above.
+   */
+  --pnd-rail-text: var(--pnd-gray-300);
+  --pnd-control-idle: var(--pnd-gray-200);
+
+  /*
+   * The band under the header is two heights. The tint runs the shorter one and
+   * the blur the taller, so below the tint there is a stretch where content is
+   * blurred but still visible. Matched heights hid the blur completely: its
+   * strongest layers sit at the top, which is exactly where the tint is opaque.
+   */
+  --pnd-fade-tint-height: 45px;
+  --pnd-fade-blur-height: 60px;
+
+  /* How far a scroller travels before a band is fully grown. */
+  --pnd-fade-ramp: 20px;
+}
+
+/*
+ * Transparency is a preference in the same way motion is, so a reader who has
+ * asked for less of it gets the chrome at full strength.
+ */
+@media (prefers-reduced-transparency: reduce) {
+  :root {
+    --pnd-chrome-idle-opacity: 1;
+    --pnd-rail-idle-opacity: 1;
+    --pnd-toggle-idle-opacity: 1;
+  }
+}
+
+/*
+ * Dark is the default theme (`Page.astro` stamps `data-theme="dark"`), so the
+ * dark values are the unqualified ones and light overrides below.
+ *
+ * Starlight's ramp runs from `--sl-color-white` as the strongest foreground to
+ * `--sl-color-black` as the page background, and inverts both in light mode, so
+ * `--sl-color-white` holds a black value further down. `--sl-color-gray-7` is
+ * only defined for light mode upstream, so dark has to name it or surfaces that
+ * use it fall back to nothing.
+ */
+:root {
+  --sl-color-white: var(--pnd-gray-0);
+  --sl-color-gray-1: var(--pnd-gray-75);
+  --sl-color-gray-2: var(--pnd-gray-200);
+  --sl-color-gray-3: var(--pnd-gray-400);
+  --sl-color-gray-4: var(--pnd-gray-500);
+  --sl-color-gray-5: var(--pnd-gray-700);
+  --sl-color-gray-6: var(--pnd-gray-800);
+  --sl-color-gray-7: var(--pnd-gray-900);
+  --sl-color-black: var(--pnd-gray-1000);
+
+  /* Surfaces that sit on the page background rather than replacing it. */
+  --pnd-surface: var(--pnd-gray-900);
+  --pnd-surface-strong: var(--pnd-gray-800);
+  --pnd-row-hover: var(--pnd-gray-900);
+  --pnd-row-active: var(--pnd-gray-800);
+
+  /*
+   * Monochrome accent. Starlight routes links, the active nav row and the
+   * active table-of-contents row through the accent tokens, so pointing them at
+   * the strongest foreground is what removes the blue without having to find
+   * every rule that used it. Links stay distinguishable by their underline; see
+   * the content section.
+   */
+  --sl-color-accent-low: var(--pnd-surface-strong);
+  --sl-color-accent: var(--sl-color-white);
+  --sl-color-accent-high: var(--sl-color-white);
+  --sl-color-text-accent: var(--sl-color-white);
+  --sl-color-bg-accent: var(--sl-color-white);
+  --sl-color-text-invert: var(--sl-color-black);
+
+  --sl-color-text: var(--sl-color-gray-2);
+  --sl-color-bg-inline-code: var(--pnd-surface-strong);
+
+  /*
+   * Header and sidebar share the page background and carry no divider. The only
+   * rule left in the chrome is the sidebar's depth guide, which says something:
+   * how deep a row sits in the tree.
+   */
+  --sl-color-bg-nav: var(--sl-color-bg);
+  --sl-color-bg-sidebar: var(--sl-color-bg);
+  --sl-color-hairline: var(--pnd-gray-800);
+  --sl-color-hairline-light: var(--pnd-gray-700);
+  --sl-color-hairline-shade: var(--pnd-gray-800);
+
+  --sl-color-backdrop-overlay: rgb(0 0 0 / 0.6);
+
+  /* Flat by default. The two lifted surfaces are the search dialog and the
+     mobile table-of-contents dropdown, which need to sit above the page. */
+  --sl-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.25);
+  --sl-shadow-md: 0 1px 2px rgb(0 0 0 / 0.25), 0 8px 24px rgb(0 0 0 / 0.35);
+  --sl-shadow-lg: 0 1px 2px rgb(0 0 0 / 0.3), 0 16px 48px rgb(0 0 0 / 0.45);
+}
+
+:root[data-theme="light"] {
+  --sl-color-white: var(--pnd-gray-1000);
+  --sl-color-gray-1: var(--pnd-gray-900);
+  --sl-color-gray-2: var(--pnd-gray-700);
+  --sl-color-gray-3: var(--pnd-gray-500);
+
+  /* The dark ramp's contrast-safe pair, mirrored. */
+  --pnd-rail-text: var(--pnd-gray-700);
+  --pnd-control-idle: var(--pnd-gray-800);
+  --sl-color-gray-4: var(--pnd-gray-400);
+  --sl-color-gray-5: var(--pnd-gray-200);
+  --sl-color-gray-6: var(--pnd-gray-100);
+  --sl-color-gray-7: var(--pnd-gray-75);
+  --sl-color-black: var(--pnd-gray-0);
+
+  --pnd-surface: var(--pnd-gray-50);
+  --pnd-surface-strong: var(--pnd-gray-75);
+  --pnd-row-hover: var(--pnd-gray-50);
+  --pnd-row-active: var(--pnd-gray-75);
+
+  --sl-color-bg-inline-code: var(--pnd-gray-75);
+  --sl-color-hairline: var(--pnd-gray-100);
+  --sl-color-hairline-light: var(--pnd-gray-100);
+  --sl-color-hairline-shade: var(--pnd-gray-100);
+
+  --sl-color-backdrop-overlay: rgb(0 0 0 / 0.3);
+
+  --sl-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.06);
+  --sl-shadow-md: 0 1px 2px rgb(0 0 0 / 0.06), 0 8px 24px rgb(0 0 0 / 0.08);
+  --sl-shadow-lg: 0 1px 2px rgb(0 0 0 / 0.08), 0 16px 48px rgb(0 0 0 / 0.12);
+}
+
+/* Type ------------------------------------------------------------------- */
+
+/*
+ * Starlight composes its own system stack after both of these, so each stays
+ * the fallback. The sans face is requested in `astro.config.mjs` and emitted by
+ * `components/Head.astro`, same as the mono one.
+ */
+:root {
+  --sl-font: var(--pnd-font-sans);
+  --sl-font-mono: var(--pnd-font-mono);
+
+  /*
+   * 17px on a 1.65 leading, and a heading scale shorter than Starlight's, whose
+   * desktop h1 is 42px. Hierarchy comes from weight and space instead of size.
+   */
+  --sl-text-body: 1.0625rem;
+  --sl-line-height: 1.65;
+  --sl-line-height-headings: 1.25;
+  --sl-text-h1: 2rem;
+  --sl-text-h2: 1.5rem;
+  --sl-text-h3: 1.25rem;
+  --sl-text-h4: 1.0625rem;
+  --sl-text-h5: 0.9375rem;
+
+  /* Starlight's 1rem between blocks is tight under a 1.65 leading. */
+  --sl-content-gap-y: 1.5rem;
+}
+
+/*
+ * A new section needs to read as a break, not as another paragraph. Starlight
+ * gives a heading following body copy 1.5em; at these heading sizes that is
+ * barely more than the gap between two paragraphs.
+ *
+ * Both selectors are needed. A heading that carries an anchor link is wrapped
+ * in `.sl-heading-wrapper`, and the margin lands on the wrapper, so a rule
+ * naming only the heading matches nothing on a generated page.
+ */
+.sl-markdown-content
+  :not(h1, h2, h3, h4, h5, h6, .sl-heading-wrapper)
+  + :is(.sl-heading-wrapper):not(:where(.not-content *)),
+.sl-markdown-content
+  :not(h1, h2, h3, h4, h5, h6, .sl-heading-wrapper)
+  + :is(h1, h2, h3, h4, h5, h6):not(:where(.not-content *)) {
+  margin-top: 2.25em;
+}
+
+/*
+ * Starlight defines `--sl-text-body` but never applies it, so body copy sits at
+ * the browser default until something sets it here. Headings and the chrome are
+ * sized in rem, so this reaches paragraphs, lists and table cells only.
+ */
+body {
+  font-size: var(--sl-text-body);
+  letter-spacing: -0.011em;
+}
+
+/* The tightening that reads as deliberate at heading sizes is too much at
+   body size, so the two are set apart rather than inherited. */
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  letter-spacing: -0.022em;
+}
+
+/* Header ---------------------------------------------------------------- */
+
+.header {
+  border-bottom: 0;
+  box-shadow: none;
+}
+
+.site-title {
+  gap: 0.6rem;
+  font-size: var(--sl-text-sm);
+  font-weight: 500;
+  letter-spacing: 0.09em;
+  text-transform: uppercase;
+}
+
+.site-title img {
+  height: 1.5rem;
+}
+
+/* Header controls ------------------------------------------------------- */
+
+/*
+ * Starlight draws a rule between the social links and the theme select from
+ * `.social-icons::after`, on the container rather than on a link, so it
+ * survives having no links to divide. Hidden by the absence of links rather
+ * than outright, so restoring one in the config brings the group back.
+ */
+.right-group .social-icons:not(:has(a)) {
+  display: none;
+}
+
+/*
+ * The theme select rests back like the collapse toggle. Its own hover already
+ * lifts the colour; this lifts the whole control with it.
+ *
+ * It rests at the rails' opacity rather than the toggle's, because it is the
+ * one header control carrying a visible label: at 50% over a white page no
+ * colour reaches the 4.5:1 that text owes, pure black included, so the
+ * threshold decides the resting opacity here rather than the shape of the
+ * control. Starlight colours it with gray-2, not the gray-3 the rails use.
+ */
+.right-group starlight-theme-select {
+  --sl-color-gray-2: var(--pnd-rail-text);
+
+  display: block;
+  opacity: var(--pnd-chrome-idle-opacity);
+  transition: opacity var(--pnd-chrome-fade) ease;
+}
+
+.right-group starlight-theme-select:hover,
+.right-group starlight-theme-select:focus-within {
+  opacity: 1;
+}
+
+/*
+ * The select carries no border of its own, so the browser's focus ring is the
+ * only thing marking it, and it arrives as a thick blue rectangle from outside
+ * the palette. Replaced rather than removed: keyboard focus still has to be
+ * visible, it just reads in the site's own greys.
+ */
+.right-group select {
+  border-radius: var(--pnd-radius-sm);
+  outline: none;
+}
+
+.right-group select:focus-visible {
+  outline: 2px solid var(--sl-color-gray-4);
+  outline-offset: 1px;
+}
+
+/* Search --------------------------------------------------------------- */
+
+/*
+ * Filled rather than outlined, at the same radius as the rest of the chrome.
+ * The fill is what marks it as a control, so hovering deepens the fill instead
+ * of drawing an edge.
+ */
+button[data-open-modal] {
+  border-radius: var(--pnd-radius);
+  transition:
+    background-color 140ms ease,
+    color 140ms ease;
+}
+
+@media (min-width: 50rem) {
+  button[data-open-modal] {
+    border-color: transparent;
+    background-color: var(--pnd-surface);
+    color: var(--sl-color-gray-3);
+  }
+
+  button[data-open-modal]:hover {
+    background-color: var(--sl-color-hairline-light);
+    color: var(--sl-color-white);
+  }
+}
+
+button[data-open-modal] > kbd {
+  border-radius: var(--pnd-radius-sm);
+  background-color: transparent;
+  color: var(--sl-color-gray-4);
+}
+
+dialog {
+  border-color: var(--sl-color-hairline-light);
+  border-radius: var(--pnd-radius-lg);
+  background-color: var(--sl-color-bg);
+}
+
+/* Sidebar nav ----------------------------------------------------------- */
+
+/*
+ * Rows are pills: one radius, one hover fill, and an active row that reads by
+ * weight and contrast rather than by a coloured block. Sizes are equal across
+ * levels, and a top-level entry is distinguished by weight.
+ */
+.sidebar-content a,
+.sidebar-content summary {
+  border-radius: var(--pnd-radius-sm);
+  padding-block: 0.3rem;
+  transition:
+    background-color 120ms ease,
+    color 120ms ease;
+}
+
+.sidebar-content a {
+  color: var(--sl-color-gray-3);
+}
+
+.sidebar-content a:hover,
+.sidebar-content a:focus-visible,
+.sidebar-content summary:hover {
+  background-color: var(--pnd-row-hover);
+  color: var(--sl-color-white);
+}
+
+.sidebar-content a[aria-current="page"],
+.sidebar-content a[aria-current="page"]:hover,
+.sidebar-content a[aria-current="page"]:focus {
+  background-color: var(--pnd-row-active);
+  color: var(--sl-color-white);
+  font-weight: 500;
+}
+
+/*
+ * Top-level rows, whether a link or a group's label. Equal in size to their
+ * children: the hierarchy is weight and colour. The colour is restated because
+ * `.sidebar-content a` above outranks Starlight's own `.large`, which would
+ * leave a top-level link muted beside a top-level group.
+ */
+.sidebar-content .large {
+  font-size: var(--sl-text-sm);
+  font-weight: 500;
+  color: var(--sl-color-gray-1);
+}
+
+/*
+ * The depth guides are the only rule left in the chrome, and the reason is that
+ * they carry information: how deep a row sits in the tree. They use the lighter
+ * hairline, since the flat one disappears against a pure-black pane.
+ */
+.sidebar-content ul ul li {
+  border-inline-start-color: var(--sl-color-hairline-light);
+}
+
+.sidebar-content .caret {
+  color: var(--sl-color-gray-4);
+}
+
+/* Thin and monochrome, and only on the pane that scrolls independently of the
+   page. Standard properties only: the `::-webkit-scrollbar` form would swap
+   WebKit's overlay scrollbar for a permanent gutter. */
+.sidebar-pane {
+  scrollbar-width: thin;
+  scrollbar-color: var(--sl-color-gray-5) transparent;
+}
+
+/*
+ * The title wrapper clips its overflow, so the collapse button can only reach
+ * as far left as the wrapper itself does. This extends the wrapper by the 4px
+ * the button moves and returns the same 4px as padding, so the clip boundary
+ * travels with the button and nothing else inside shifts.
+ */
+@media (min-width: 50rem) {
+  :root[data-has-sidebar] .title-wrapper {
+    margin-inline-start: -0.5rem;
+    padding-inline-start: 0.5rem;
+  }
+}
+
+/* Chrome at rest -------------------------------------------------------- */
+
+/*
+ * Both rails and both header controls dim as a whole, so the grey their
+ * contents resolve is restated for the subtree instead of element by element:
+ * the sidebar's links, the table of contents' heading and its rows all read
+ * `--sl-color-gray-3`, and all of them are behind the same opacity.
+ */
+.sidebar-content,
+.right-sidebar-panel {
+  --sl-color-gray-3: var(--pnd-rail-text);
+}
+
+:root[data-has-sidebar] .pnd-sidebar-toggle {
+  --sl-color-gray-3: var(--pnd-control-idle);
+}
+
+/*
+ * Both rails rest at `--pnd-chrome-idle-opacity` and come up to full strength
+ * when the pointer or keyboard focus reaches them. The opacity sits on the
+ * inner element of each rail rather than the scrolling pane, which already
+ * owns a transition for the collapse; two `transition` shorthands on one
+ * element would drop whichever lost the cascade.
+ *
+ * The hover target is the whole rail, so the reveal does not depend on landing
+ * on a row.
+ */
+@media (min-width: 50rem) {
+  .sidebar-content {
+    opacity: var(--pnd-rail-idle-opacity);
+    transition: opacity var(--pnd-chrome-fade) ease;
+  }
+
+  .sidebar-pane:hover .sidebar-content,
+  .sidebar-pane:focus-within .sidebar-content {
+    opacity: 1;
+  }
+}
+
+@media (min-width: 72rem) {
+  .right-sidebar-panel {
+    opacity: var(--pnd-chrome-idle-opacity);
+    transition: opacity var(--pnd-chrome-fade) ease;
+  }
+
+  .right-sidebar:hover .right-sidebar-panel,
+  .right-sidebar:focus-within .right-sidebar-panel {
+    opacity: 1;
+  }
+}
+
+/* On this page ---------------------------------------------------------- */
+
+/*
+ * Sized as a label. Starlight sizes it as a heading, at `--sl-text-h5` in the
+ * strongest foreground, which gave the right-hand column a title competing with
+ * the page's own.
+ */
+.right-sidebar-panel h2 {
+  margin-bottom: 0.75rem;
+  font-size: var(--sl-text-xs);
+  font-weight: 500;
+  color: var(--sl-color-gray-3);
+}
+
+.right-sidebar-panel a {
+  border-radius: var(--pnd-radius-sm);
+  padding-block: 0.3rem;
+  transition: color 120ms ease;
+}
+
+.right-sidebar-panel a[aria-current="true"] {
+  color: var(--sl-color-white);
+  font-weight: 500;
+}
+
+.right-sidebar {
+  border-inline-start: 0;
+}
+
+/* Content --------------------------------------------------------------- */
+
+/*
+ * Starlight rules a line between every pair of content panels, which on a
+ * generated page falls directly under the title and reads as a header border.
+ * The space alone separates them.
+ */
+.content-panel + .content-panel {
+  border-top: 0;
+}
+
+/*
+ * Links carry an underline rather than a colour, so they stay visible in a
+ * monochrome palette. The resting colour is one step down from the text, so the
+ * underline does not outweigh the word it marks.
+ */
+.sl-markdown-content a:not(:where(.not-content *)) {
+  text-decoration: underline;
+  text-decoration-color: var(--sl-color-gray-4);
+  text-decoration-thickness: 1px;
+  text-underline-offset: 0.2em;
+  transition: text-decoration-color 120ms ease;
+}
+
+.sl-markdown-content a:not(:where(.not-content *)):hover {
+  text-decoration-color: currentColor;
+}
+
+.sl-markdown-content :is(th, td):not(:where(.not-content *)) {
+  border-color: var(--sl-color-hairline);
+}
+
+.sl-markdown-content img {
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: var(--pnd-radius-lg);
+}
+
+/*
+ * The mobile table-of-contents opens downwards into the strip the content band
+ * covers. The band is rendered inside the header, which is its own stacking
+ * context at `--sl-z-index-navbar`, so everything in it paints at that level
+ * and the band landed on top of the open list. Nothing inside the header can
+ * be pushed below a sibling of the header, so the list is lifted above it
+ * instead. It hangs below the header and never overlaps it, so nothing of the
+ * header is covered in exchange.
+ */
+mobile-starlight-toc nav {
+  z-index: calc(var(--sl-z-index-navbar) + 1);
+  /* The rule above it duplicated the header's, which is already gone. */
+  border-top: 0;
+}
+
+/*
+ * No rule under the bar either. It was there to separate the bar from content
+ * scrolling beneath it, which the fade band now does: the band starts below
+ * this bar, so content dissolves before it reaches one.
+ */
+mobile-starlight-toc summary {
+  gap: 0.9rem;
+  border-bottom: 0;
+}
+
+/* Diagrams --------------------------------------------------------------- */
+
+/*
+ * Rendered diagrams are inlined into the page rather than left in an `<img>`
+ * (see `src/plugins/inline-diagrams.mjs`), which is what lets these properties
+ * reach them. The generator writes every colour in the SVG as
+ * `var(--pnd-diagram-*, <the colour d2 drew>)`, so light mode needs nothing
+ * here: the fallbacks are already the light palette.
+ *
+ * No border and no card: the background is the page's own now, so the drawing
+ * sits on the page instead of in a frame on it.
+ */
+.pnd-diagram {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin-inline: auto;
+}
+
+:root[data-theme="dark"] {
+  /*
+   * d2's neutral ramp runs dark-to-light, and inverting it is most of what
+   * makes a diagram legible here. n7 is the drawing's own background, which
+   * goes transparent so the page shows through.
+   */
+  --pnd-diagram-n1: var(--pnd-gray-75);
+  --pnd-diagram-n2: var(--pnd-gray-300);
+  --pnd-diagram-n3: var(--pnd-gray-400);
+  --pnd-diagram-n4: var(--pnd-gray-500);
+  --pnd-diagram-n5: var(--pnd-gray-600);
+  --pnd-diagram-n6: var(--pnd-gray-700);
+  /*
+   * The page's own background, not `transparent`. n7 is the drawing's paper:
+   * it fills the outer background rect, where either would do, but it also
+   * knocks the connection lines out from behind their labels. Transparent left
+   * every label with its own line struck through it.
+   */
+  --pnd-diagram-n7: var(--sl-color-bg);
+
+  /* The blues d2 draws connections and their labels with. */
+  --pnd-diagram-b1: #6c9cf0;
+  --pnd-diagram-b2: #6c9cf0;
+  --pnd-diagram-b3: #22304a;
+  --pnd-diagram-b4: #22304a;
+  --pnd-diagram-b5: #1b2436;
+  --pnd-diagram-b6: #161d2b;
+
+  /*
+   * One pair per layer family, holding each family's hue while swapping the
+   * pale fill for a dark one and lifting the stroke enough to read against it.
+   */
+  --pnd-diagram-core-fill: #16273a;
+  --pnd-diagram-core-stroke: #5b9bd8;
+  --pnd-diagram-react-fill: #251d38;
+  --pnd-diagram-react-stroke: #9b7fd4;
+  --pnd-diagram-ui-fill: #16281d;
+  --pnd-diagram-ui-stroke: #5fa87a;
+  --pnd-diagram-petrinaut-fill: #2e2314;
+  --pnd-diagram-petrinaut-stroke: #d3a05a;
+  --pnd-diagram-cli-fill: #2c1a20;
+  --pnd-diagram-cli-stroke: #d1697f;
+  --pnd-diagram-python-bindings-fill: #2b2510;
+  --pnd-diagram-python-bindings-stroke: #c9a83f;
+  --pnd-diagram-optimizer-fill: #132625;
+  --pnd-diagram-optimizer-stroke: #57a89f;
+  --pnd-diagram-website-fill: #222711;
+  --pnd-diagram-website-stroke: #9bb85a;
+  --pnd-diagram-other-fill: #1e1e1e;
+  --pnd-diagram-other-stroke: var(--pnd-gray-400);
+  --pnd-diagram-elided-fill: transparent;
+  --pnd-diagram-elided-stroke: var(--pnd-gray-500);
+
+  /* The two accents the authored diagrams use for something other than a
+     layer family: the device a batch runs on, and a case that falls back. */
+  --pnd-diagram-device-fill: #2e2510;
+  --pnd-diagram-device-stroke: #c9a03f;
+  --pnd-diagram-caution-fill: #2e1616;
+  --pnd-diagram-caution-stroke: #d16a6a;
+
+  /* The tooltip badge on a node, which d2 draws outside its palette. */
+  --pnd-diagram-badge-fill: var(--pnd-gray-800);
+  --pnd-diagram-badge-edge: var(--pnd-gray-600);
+  --pnd-diagram-badge-mark: var(--pnd-gray-300);
+}
+
+/*
+ * Expressive Code declares these on `:root` inside `@layer starlight.components`
+ * and again on the block itself for a code block whose theme differs from the
+ * page's, so both scopes are named here. Layer order settles the first. Only a
+ * rule on the element settles the second.
+ */
+:root,
+.expressive-code {
+  --ec-brdRad: var(--pnd-radius);
+  --ec-brdCol: var(--sl-color-hairline-light);
+  --ec-codeBg: var(--pnd-surface);
+  --ec-frm-edBg: var(--pnd-surface);
+  --ec-frm-trmBg: var(--pnd-surface);
+  --ec-frm-edTabBarBg: var(--pnd-surface-strong);
+  --ec-frm-frameBoxShdCssVal: none;
+  --ec-frm-shdCol: transparent;
+}
+
+/* Sidebar geometry ------------------------------------------------------ */
+
 :root {
   /*
    * Starlight derives both side panels from `--sl-sidebar-width`. The left nav
@@ -34,44 +722,41 @@
 /* 50rem is where Starlight turns the mobile drawer into a fixed rail. */
 @media (min-width: 50rem) {
   :root[data-has-sidebar] {
-    --sl-content-inline-start: var(--pnd-sidebar-width);
+    /*
+     * One expression covering both states, so collapsing moves the column
+     * between two ends of a single length. This used to be the pane's width
+     * with a separate 2rem rule for the collapsed state, which is the same
+     * thing to lay out but two unrelated values to animate between. 2rem is
+     * the floor because below 72rem nothing else insets the column from the
+     * edge.
+     */
+    --sl-content-inline-start: max(var(--pnd-sidebar-width), 2rem);
   }
 
   .sidebar-pane {
     width: var(--pnd-sidebar-width);
+    border-inline-end: 0;
+    /*
+     * A scroll container with `overflow-y: auto` computes `overflow-x` to
+     * `auto` as well, which flashes a horizontal scrollbar across the whole
+     * collapse as the rows outgrow the narrowing pane.
+     */
+    overflow-x: clip;
   }
 
+  /*
+   * Collapsed, the pane keeps its box so `width` has something to animate, and
+   * `visibility` is what takes it out of the tab order and the accessibility
+   * tree. Transitioning `visibility` holds `visible` for the whole collapse and
+   * flips it at the end, so the rows travel with the pane instead of being
+   * blanked on the first frame. This replaces a `display: none`, which no
+   * transition can survive.
+   */
   :root[data-pnd-sidebar="collapsed"] .sidebar-pane {
-    display: none;
-  }
-
-  /* Not zero: below 72rem nothing else insets the column from the edge. */
-  :root[data-has-sidebar][data-pnd-sidebar="collapsed"] {
-    --sl-content-inline-start: 2rem;
+    visibility: hidden;
   }
 }
 
-/* Code font -------------------------------------------------------------- */
-
-/* Starlight composes its own system stack after this, so it stays the fallback. */
-:root {
-  --sl-font-mono: var(--pnd-font-mono);
-}
-
-/* Header ---------------------------------------------------------------- */
-
-.site-title {
-  gap: 0.6rem;
-  font-size: var(--sl-text-sm);
-  font-weight: 500;
-  letter-spacing: 0.09em;
-  text-transform: uppercase;
-}
-
-.site-title img {
-  height: 1.5rem;
-}
-
 /* Sidebar controls ------------------------------------------------------ */
 
 /* Both controls belong to the desktop rail; the mobile drawer has its own. */
@@ -87,25 +772,57 @@
     align-items: center;
     justify-content: center;
     /* The wrapper has no gap, so the separation from the logo is set here.
-       The negative start pulls the button in from the header padding — only
-       as far as the title wrapper's own negative margin, since its
-       `overflow: clip` cuts anything past that. */
-    margin-inline: -0.25rem 0.85rem;
+       The start pulls the button out of the header's 24px padding to 16px, so
+       it sits as far from the left edge as it does from the top: the header is
+       64px and the button 32px, which leaves 16px above it. The end grows by
+       the same 4px, so the logo beside it does not move with the button. */
+    margin-inline: -0.5rem 1.1rem;
     width: var(--sl-menu-button-size);
     height: var(--sl-menu-button-size);
     padding: 0;
     border: 0;
-    border-radius: 0.25rem;
+    border-radius: var(--pnd-radius-sm);
     background: none;
     color: var(--sl-color-gray-3);
     cursor: pointer;
+    opacity: var(--pnd-toggle-idle-opacity);
+    transition:
+      background-color 120ms ease,
+      color 120ms ease,
+      opacity var(--pnd-chrome-fade) ease;
   }
 
-  .pnd-sidebar-toggle:hover {
-    /* One step lighter than the header's own background, which in dark mode
-       is `--sl-color-gray-6` itself — that value would make hover invisible. */
-    background: var(--sl-color-gray-5);
+  /*
+   * These carry the same `:root[data-has-sidebar]` prefix as the rule above,
+   * which is load-bearing rather than decoration: that prefix is three
+   * selectors' worth of specificity, and a bare `.pnd-sidebar-toggle:hover` is
+   * two, so it loses and the button never lights up.
+   */
+  :root[data-has-sidebar] .pnd-sidebar-toggle:hover,
+  :root[data-has-sidebar] .pnd-sidebar-toggle:focus-visible {
+    background: var(--pnd-row-active);
     color: var(--sl-color-white);
+    opacity: 1;
+  }
+
+  /*
+   * A press dips the button and springs back past its own size, which is the
+   * bounce. The dip is quick and the return is not, so the weight lands on the
+   * way back rather than on the way in.
+   */
+  @media (prefers-reduced-motion: no-preference) {
+    :root[data-has-sidebar] .pnd-sidebar-toggle {
+      transition:
+        background-color 120ms ease,
+        color 120ms ease,
+        opacity var(--pnd-chrome-fade) ease,
+        transform 260ms cubic-bezier(0.34, 1.56, 0.64, 1);
+    }
+
+    :root[data-has-sidebar] .pnd-sidebar-toggle:active {
+      transform: scale(0.88);
+      transition-duration: 120ms, 120ms, var(--pnd-chrome-fade), 90ms;
+    }
   }
 
   /*
@@ -123,14 +840,345 @@
     touch-action: none;
   }
 
-  .pnd-sidebar-resize:hover,
   .pnd-sidebar-resize:focus-visible {
-    background: var(--sl-color-accent);
     outline: none;
   }
 
+  /*
+   * The hit area stays 6px wide while the mark is 2px, centred on the pane's
+   * trailing edge, so the target is easy to hit and the mark stays thin. With
+   * no divider drawn between the panes, this is the only thing that marks that
+   * edge, and it appears under the pointer that is looking for it.
+   */
+  .pnd-sidebar-resize::after {
+    content: "";
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 2px;
+    width: 2px;
+    background: var(--sl-color-gray-4);
+    opacity: 0;
+    transition: opacity 140ms ease;
+  }
+
+  .pnd-sidebar-resize:hover::after,
+  .pnd-sidebar-resize:focus-visible::after,
+  :root[data-pnd-resizing] .pnd-sidebar-resize::after {
+    background: var(--sl-color-gray-3);
+    opacity: 1;
+  }
+
   :root[data-pnd-sidebar="collapsed"] .pnd-sidebar-resize {
-    display: none;
+    visibility: hidden;
+    pointer-events: none;
+  }
+}
+
+/*
+ * The pointer spends a drag outside the 6px strip. Pointer capture keeps the
+ * events coming, but without these the cursor flickers to whatever it is over
+ * and the drag selects the page text it crosses.
+ */
+:root[data-pnd-resizing] {
+  user-select: none;
+}
+
+:root[data-pnd-resizing] * {
+  cursor: col-resize;
+}
+
+/* Sidebar motion -------------------------------------------------------- */
+
+/*
+ * Toggling is a jump between two widths, so it is animated. A drag and a held
+ * arrow key already track their input frame by frame, and a transition on top
+ * of that makes the pane lag behind the pointer. The handle sets
+ * `data-pnd-resizing` for the length of the gesture, and these rules do not
+ * apply while it is set.
+ *
+ * Everything listed sizes off the sidebar width or `--sl-content-width`. They
+ * have to move on the same curve over the same duration, or the content column
+ * tears away from the pane it is following.
+ *
+ * Transitions do not run on an element's first style computation, so a sidebar
+ * restored as collapsed by the head script renders collapsed rather than
+ * animating open on load.
+ */
+@media (prefers-reduced-motion: no-preference) and (min-width: 50rem) {
+  :root:not([data-pnd-resizing]) .sidebar-pane {
+    transition:
+      width var(--pnd-motion-duration) var(--pnd-motion-ease),
+      visibility var(--pnd-motion-duration) linear;
+  }
+
+  :root:not([data-pnd-resizing]) .main-frame {
+    transition: padding-inline-start var(--pnd-motion-duration)
+      var(--pnd-motion-ease);
+  }
+
+  :root:not([data-pnd-resizing]) .content-panel > .sl-container {
+    transition: max-width var(--pnd-motion-duration) var(--pnd-motion-ease);
+  }
+
+  :root:not([data-pnd-resizing]) .pnd-content-fade {
+    transition:
+      inset-inline-start var(--pnd-motion-duration) var(--pnd-motion-ease),
+      inset-inline-end var(--pnd-motion-duration) var(--pnd-motion-ease);
+  }
+
+  :root:not([data-pnd-resizing]) .pnd-nav-fade,
+  :root:not([data-pnd-resizing]) .pnd-nav-fade-bottom {
+    transition: width var(--pnd-motion-duration) var(--pnd-motion-ease);
+  }
+
+  :root:not([data-pnd-resizing]) .pnd-sidebar-resize {
+    transition:
+      inset-inline-start var(--pnd-motion-duration) var(--pnd-motion-ease),
+      visibility var(--pnd-motion-duration) linear;
+  }
+}
+
+/* 72rem is where the on-this-page column appears and starts sharing the row's
+   width with the content, so both size off `--sl-content-width` from here up. */
+@media (prefers-reduced-motion: no-preference) and (min-width: 72rem) {
+  :root:not([data-pnd-resizing]) .main-pane,
+  :root:not([data-pnd-resizing]) .right-sidebar-container {
+    transition: width var(--pnd-motion-duration) var(--pnd-motion-ease);
+  }
+}
+
+/* Content fade ---------------------------------------------------------- */
+
+/*
+ * A band under the header where the content passing beneath it blurs out and
+ * takes on the page colour, so scrolled text does not meet the header on a
+ * hard edge.
+ *
+ * Only over the content: it starts where the content column starts and, once
+ * the on-this-page column exists, stops where that column starts. The right
+ * inset restates Starlight's own width for that column, since there is no
+ * variable holding it.
+ *
+ * `backdrop-filter` cannot ramp on its own, so the ramp is three stacked
+ * layers: each blurs the backdrop harder than the last and is masked to a
+ * shorter band below the header. Each layer filters what the layer beneath it
+ * produced, so the blur compounds towards the top rather than stepping.
+ */
+.pnd-fade {
+  position: fixed;
+  inset-block-start: var(--sl-nav-height);
+  /*
+   * Height, tint and opacity all come off one number, so a band grows out of
+   * its own scroll from nothing. At 0 there is no band at all: nothing under
+   * the header is touched until the reader has scrolled something under it.
+   */
+  height: calc(var(--pnd-fade-blur-height) * var(--pnd-fade-progress, 0));
+  opacity: var(--pnd-fade-progress, 0);
+  pointer-events: none;
+}
+
+/*
+ * Over the content column: from where the content starts to where the
+ * on-this-page column does, and below whatever chrome sits above the content.
+ * Between 50rem and 72rem that is the header plus Starlight's mobile
+ * table-of-contents bar, which the band would otherwise blur;
+ * `--sl-mobile-toc-height` is 0 once the column moves to the side.
+ */
+.pnd-content-fade {
+  --pnd-fade-progress: var(--pnd-content-progress, 0);
+
+  /*
+   * A pixel short of the two heights added up, because Starlight pulls the
+   * on-this-page bar up by one to sit on the header's border, so the bar ends a
+   * pixel above where those heights put it. `max()` keeps the subtraction from
+   * applying when there is no bar to sit under and the height is zero.
+   */
+  inset-block-start: calc(
+    var(--sl-nav-height) + max(var(--sl-mobile-toc-height) - 1px, 0px)
+  );
+  inset-inline-start: var(--sl-content-inline-start, 0px);
+  inset-inline-end: 0;
+}
+
+/*
+ * One layer, filling the band. `backdrop-filter` takes a single radius, so the
+ * ramp comes from the mask: full strength for the top half, then out to nothing
+ * by the bottom, which is what keeps the blur from ending on a line across the
+ * content.
+ */
+.pnd-fade > span {
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline: 0;
+  display: block;
+  height: 100%;
+  -webkit-backdrop-filter: blur(0.5px);
+  backdrop-filter: blur(0.5px);
+  -webkit-mask-image: linear-gradient(to bottom, #000 50%, transparent);
+  mask-image: linear-gradient(to bottom, #000 50%, transparent);
+}
+
+/*
+ * The colour half, painted over the blur and only over the top of it. Where it
+ * ends the blur carries on alone, which is the part a reader actually sees.
+ */
+.pnd-fade::after {
+  content: "";
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline: 0;
+  height: calc(var(--pnd-fade-tint-height) * var(--pnd-fade-progress, 0));
+  background: linear-gradient(to bottom, var(--sl-color-bg), transparent);
+}
+
+/*
+ * The same band hung off the bottom edge, for a scroll container with more
+ * below the fold. Everything mirrors: the box, the layer inside it, the mask
+ * and the tint all run upwards from the bottom instead of down from the top.
+ */
+.pnd-fade-up {
+  inset-block-start: auto;
+  inset-block-end: 0;
+}
+
+.pnd-fade-up > span {
+  inset-block-start: auto;
+  inset-block-end: 0;
+  -webkit-mask-image: linear-gradient(to top, #000 50%, transparent);
+  mask-image: linear-gradient(to top, #000 50%, transparent);
+}
+
+.pnd-fade-up::after {
+  inset-block-start: auto;
+  inset-block-end: 0;
+  background: linear-gradient(to top, var(--sl-color-bg), transparent);
+}
+
+/*
+ * The nav is its own scroll container, so its band reads that scroll rather
+ * than the window's. Otherwise it behaves exactly like the content band: the
+ * header script writes progress from 0 to 1, and at rest there is no band.
+ *
+ * No transition on either: the value already tracks the scroll frame by frame,
+ * and easing on top of that only makes a band lag the rows it covers.
+ */
+.pnd-nav-fade,
+.pnd-nav-fade-bottom {
+  display: none;
+}
+
+@media (min-width: 50rem) {
+  :root[data-has-sidebar] .pnd-nav-fade,
+  :root[data-has-sidebar] .pnd-nav-fade-bottom {
+    display: block;
+    inset-inline-start: 0;
+    width: var(--pnd-sidebar-width);
+  }
+
+  :root[data-has-sidebar] .pnd-nav-fade {
+    --pnd-fade-progress: var(--pnd-nav-progress, 0);
+  }
+
+  /*
+   * Driven by what is left below the fold rather than by what has gone above
+   * it, so a rail short enough to need no scrolling never shows one and the
+   * band closes as the last rows arrive.
+   */
+  :root[data-has-sidebar] .pnd-nav-fade-bottom {
+    --pnd-fade-progress: var(--pnd-nav-end-progress, 0);
+  }
+}
+
+/*
+ * The bands, without the script ---------------------------------------------
+ *
+ * `--pnd-fade-progress` is otherwise a number the header script writes on every
+ * scroll, which means a band cannot be correct until that script has run: a
+ * page restored to a scroll position paints once without its bands and then
+ * with them. A scroll-driven animation has no such gap, because the progress is
+ * resolved from layout at the same time as everything else on the first frame,
+ * and the scroll no longer runs script at all.
+ *
+ * Registering the property is what makes it animatable: an unregistered custom
+ * property is an unparsed token sequence, and interpolating one is undefined.
+ *
+ * Firefox has not shipped either half of this, so `@supports` keeps the script
+ * as the fallback there. `watchScrollFades` in `SiteTitle.astro` tests the same
+ * condition and does nothing when the browser can do it in CSS.
+ */
+@property --pnd-fade-progress {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
+
+@keyframes pnd-fade-grow {
+  from {
+    --pnd-fade-progress: 0;
+  }
+
+  to {
+    --pnd-fade-progress: 1;
+  }
+}
+
+@supports (animation-timeline: scroll()) and (timeline-scope: --pnd-nav-scroll) {
+  .pnd-content-fade {
+    animation: pnd-fade-grow linear both;
+    animation-timeline: scroll(root block);
+    animation-range: 0 var(--pnd-fade-ramp);
+  }
+
+  /*
+   * The rail's bands are drawn in the header, not inside the rail, so they
+   * cannot see its scroller by lookup. Naming the timeline and widening its
+   * scope to the document is what lets a sibling subtree read it.
+   */
+  .sidebar-pane {
+    scroll-timeline: --pnd-nav-scroll block;
+  }
+
+  :root {
+    timeline-scope: --pnd-nav-scroll;
+  }
+
+  @media (min-width: 50rem) {
+    :root[data-has-sidebar] .pnd-nav-fade {
+      animation: pnd-fade-grow linear both;
+      animation-timeline: --pnd-nav-scroll;
+      animation-range: 0 var(--pnd-fade-ramp);
+    }
+
+    /*
+     * Reversed over the last stretch of the scroll rather than the first, which
+     * is how "what is left below the fold" falls out of a timeline that only
+     * counts distance travelled. `both` holds 1 above the range and 0 past its
+     * end, so the band is open the whole way down and closes as the last rows
+     * arrive. A rail with nothing to scroll has an inactive timeline and no
+     * animation at all, which is the same 0 it rests at.
+     */
+    :root[data-has-sidebar] .pnd-nav-fade-bottom {
+      animation: pnd-fade-grow linear both reverse;
+      animation-timeline: --pnd-nav-scroll;
+      animation-range: calc(100% - var(--pnd-fade-ramp)) 100%;
+    }
+  }
+}
+
+/* 72rem is where the on-this-page column appears beside the content. */
+@media (min-width: 72rem) {
+  .pnd-content-fade {
+    inset-inline-end: max(
+      var(--sl-sidebar-width),
+      calc(
+        var(--sl-sidebar-width) +
+          (
+            100vw - var(--sl-content-inline-start) - var(--sl-content-width) -
+              var(--sl-sidebar-width)
+          ) /
+          2
+      )
+    );
   }
 }
 
@@ -188,8 +1236,8 @@
       block-size: 0;
       overflow: hidden;
       transition:
-        block-size 220ms ease,
-        content-visibility 220ms allow-discrete;
+        block-size var(--pnd-motion-duration) var(--pnd-motion-ease),
+        content-visibility var(--pnd-motion-duration) allow-discrete;
     }
 
     :root[data-pnd-ready] .sidebar-content details[open]::details-content {
@@ -198,19 +1246,6 @@
   }
 }
 
-/* Content --------------------------------------------------------------- */
-
-/*
- * Rendered diagrams arrive as plain markdown images with a white background
- * baked into the SVG, so they read as cards once their edge matches the layer
- * cards beside them. Radius and border are `.arch-card`'s own values, which is
- * why the border is a `color-mix` rather than a Starlight hairline token.
- */
-.sl-markdown-content img {
-  border: 1px solid color-mix(in srgb, currentColor 22%, transparent);
-  border-radius: 0.5rem;
-}
-
 /* Diff badges ------------------------------------------------------------ */
 
 /*
@@ -247,6 +1282,7 @@
 .sidebar-content .sl-badge {
   flex: none;
   padding: 0 0.3rem;
+  border-radius: var(--pnd-radius-sm);
   font-size: 0.6rem;
   line-height: 1.4;
 }
@@ -278,15 +1314,21 @@
   display: inline-flex;
   align-items: center;
   gap: 0.35rem;
-  padding: 0.05rem 0.55rem;
-  border: 1px solid var(--sl-color-gray-5);
+  padding: 0.15rem 0.6rem;
+  border: 0;
   border-radius: 999px;
+  /* One step off the page rather than an outline, so the chips separate from
+     the header without adding a line to it. */
+  background: var(--pnd-surface-strong);
   color: var(--sl-color-gray-2);
   text-decoration: none;
+  transition:
+    background-color 120ms ease,
+    color 120ms ease;
 }
 
 .pnd-diff-compare .pnd-diff-chip:hover {
-  border-color: var(--sl-color-gray-3);
+  background: var(--sl-color-hairline-light);
   color: var(--sl-color-white);
 }
 
diff --git a/libs/@local/petrinaut-arch-docs/README.md b/libs/@local/petrinaut-arch-docs/README.md
index 7442b196ed8..8c5f06a3f07 100644
--- a/libs/@local/petrinaut-arch-docs/README.md
+++ b/libs/@local/petrinaut-arch-docs/README.md
@@ -297,6 +297,43 @@ Names are namespaced by directory rather than by prefix: a layer id is unique
 only among layer ids, so a flat `around-<id>` would collide with a top-level
 layer actually called `around-something`.
 
+### How they are rendered
+
+`d2` runs with the Inter faces vendored in `fonts/`, and with padding well under
+its 100px default. The font is not decoration: `d2` measures every label with
+the face it renders with and sizes the boxes from that, so a diagram drawn in
+one face and shown in another has labels that no longer fit their boxes. The
+faces are Inter, under the SIL Open Font License 1.1, whose text sits beside
+them.
+
+Every colour in a rendered SVG is then restated as a custom property, so a host
+can retheme a diagram without this package knowing anything about that host's
+themes:
+
+```css
+:root[data-theme="dark"] {
+  --pnd-diagram-n1: #f3f3f3; /* d2's strongest foreground */
+  --pnd-diagram-n7: #0d0d0d; /* the drawing's paper: opaque, see below */
+  --pnd-diagram-core-fill: #16273a;
+}
+```
+
+Each property carries the colour `d2` drew as its fallback, so a host that
+defines none of them renders exactly what it always did. Give `n7` the host
+page's own background rather than `transparent`: it is the drawing's paper, and
+it also fills the rectangles that knock connection lines out from behind their
+labels, so a transparent one leaves every label with its line struck through
+it. The rules are appended
+as a stylesheet rather than written into the markup, because `var()` is not
+reliably honoured inside SVG presentation attributes but is honoured in a
+declaration that overrides them.
+
+Reaching those properties needs the SVG inlined into the page: behind an `<img>`
+it is a separate document and nothing on the page reaches it. The bundle still
+emits a plain markdown image, which is what keeps it portable; a host that wants
+themed diagrams inlines them itself. `apps/petrinaut-docs` does this in a rehype
+plugin, and is worth copying from.
+
 ## Hand-written pages (optional)
 
 `content/` is entirely optional. With no `content/` directory at all, the
diff --git a/libs/@local/petrinaut-arch-docs/content/diagrams/gpu-batch-lifecycle.d2 b/libs/@local/petrinaut-arch-docs/content/diagrams/gpu-batch-lifecycle.d2
index f9ccec27742..ebe6e796fc0 100644
--- a/libs/@local/petrinaut-arch-docs/content/diagrams/gpu-batch-lifecycle.d2
+++ b/libs/@local/petrinaut-arch-docs/content/diagrams/gpu-batch-lifecycle.d2
@@ -14,7 +14,7 @@ stores: "experiment handle stores\n→ sweep session" {style.fill: "#e8e0ff"; st
 backend -> handle: "assess(request).instantiate"
 handle -> cache: "acquire (lease)"
 cache -> build: "miss: build once" {style.stroke-dash: 4}
-cache -> handle: "cached backend + calibrations"
+cache -> handle: "backend + calibrations"
 handle -> calib: "no calibration for this marking" {style.stroke-dash: 4}
 calib -> runner: "probe run" {style.stroke-dash: 4}
 runner -> calib: "escape / overflow → replan" {style.stroke-dash: 4}
@@ -22,4 +22,4 @@ handle -> runner: "run tiles"
 runner -> device: "dispatch / readback"
 runner -> frames: "per tile, cumulative"
 frames -> stores: "onFrames"
-handle -> cache: "release"
+handle -> cache: "release (evict?)"
diff --git a/libs/@local/petrinaut-arch-docs/fonts/Inter-Bold.ttf b/libs/@local/petrinaut-arch-docs/fonts/Inter-Bold.ttf
new file mode 100644
index 00000000000..8e82c70d108
Binary files /dev/null and b/libs/@local/petrinaut-arch-docs/fonts/Inter-Bold.ttf differ
diff --git a/libs/@local/petrinaut-arch-docs/fonts/Inter-Regular.ttf b/libs/@local/petrinaut-arch-docs/fonts/Inter-Regular.ttf
new file mode 100644
index 00000000000..8d4eebf2066
Binary files /dev/null and b/libs/@local/petrinaut-arch-docs/fonts/Inter-Regular.ttf differ
diff --git a/libs/@local/petrinaut-arch-docs/fonts/OFL.txt b/libs/@local/petrinaut-arch-docs/fonts/OFL.txt
new file mode 100644
index 00000000000..40589daa9de
--- /dev/null
+++ b/libs/@local/petrinaut-arch-docs/fonts/OFL.txt
@@ -0,0 +1,93 @@
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter) Inter-Italic[opsz,wght].ttf: Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/libs/@local/petrinaut-arch-docs/src/cli.ts b/libs/@local/petrinaut-arch-docs/src/cli.ts
index a05a933a1b7..824590b6cca 100644
--- a/libs/@local/petrinaut-arch-docs/src/cli.ts
+++ b/libs/@local/petrinaut-arch-docs/src/cli.ts
@@ -18,6 +18,9 @@ import { applyBundleDiff } from "./diff/bundle-diff";
 import { canRenderDiagrams, renderD2 } from "./emit/d2";
 
 const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+
+/** This package's own root, which is where the render fonts are vendored. */
+const packageRoot = fileURLToPath(new URL("../", import.meta.url));
 const bundleRoot = join(repoRoot, config.outputDirectory);
 
 const supportsColour = process.stdout.isTTY === true;
@@ -177,7 +180,7 @@ const writeBundle = async (
   for (const name of bundle.diagramSources.keys()) {
     const source = join(bundleRoot, `diagrams/${name}.d2`);
     const output = join(bundleRoot, `diagrams/${name}.svg`);
-    const result = renderD2(repoRoot, source, output);
+    const result = renderD2(repoRoot, source, output, packageRoot);
 
     if (!result.ok) {
       // The pages were emitted expecting this SVG, because `d2` answered the
diff --git a/libs/@local/petrinaut-arch-docs/src/emit/d2.test.ts b/libs/@local/petrinaut-arch-docs/src/emit/d2.test.ts
index 98805347531..04635aff0da 100644
--- a/libs/@local/petrinaut-arch-docs/src/emit/d2.test.ts
+++ b/libs/@local/petrinaut-arch-docs/src/emit/d2.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { buildNeighbourhoodDiagram } from "./d2";
+import { buildNeighbourhoodDiagram, withThemeableColours } from "./d2";
 
 import type { Edge, Layer } from "../model";
 
@@ -151,3 +151,61 @@ describe("buildNeighbourhoodDiagram", () => {
     });
   });
 });
+
+/**
+ * The rendered markup is `d2`'s output, not ours, so the theming hook is a
+ * contract against a format we do not control: it finds the drawing's scope
+ * class and matches the colours `d2` wrote. A change to either on `d2`'s side
+ * would stop every host override silently, with the diagrams still rendering in
+ * the palette they were drawn in, which is why this is pinned rather than left
+ * to the build.
+ */
+describe("withThemeableColours", () => {
+  const drawn = (body: string): string =>
+    `<svg xmlns="http://www.w3.org/2000/svg"><svg class="d2-123456789 d2-svg">${body}</svg></svg>`;
+
+  it("scopes its rules to the class d2 put on the drawing", () => {
+    const themed = withThemeableColours(drawn(""));
+
+    expect(themed).toContain(".d2-123456789 .fill-N1{");
+    expect(themed).not.toMatch(/(?<!d2-123456789 )\.fill-N1\{/u);
+  });
+
+  it("writes the drawn colour as each fallback, so an unthemed host is unchanged", () => {
+    const themed = withThemeableColours(drawn(""));
+
+    expect(themed).toContain(
+      ".d2-123456789 .fill-N1{fill:var(--pnd-diagram-n1,#0A0F25);}",
+    );
+    expect(themed).toContain(
+      '.d2-123456789 [fill="#dcecff"]{fill:var(--pnd-diagram-core-fill,#dcecff);}',
+    );
+  });
+
+  it("puts the rules inside the drawing", () => {
+    const themed = withThemeableColours(drawn(""));
+
+    expect(themed.indexOf("<style")).toBeLessThan(themed.indexOf("</svg>"));
+  });
+
+  it("leaves markup carrying no d2 scope alone", () => {
+    const plain = '<svg xmlns="http://www.w3.org/2000/svg"><rect /></svg>';
+
+    expect(withThemeableColours(plain)).toBe(plain);
+  });
+
+  /*
+   * `d2` masks its connections out from behind their labels with a white rect
+   * that shows and black rects that hide, so `white` and `black` there are not
+   * colours. Theming them by fill alone inverts the mask and every masked
+   * connection disappears. The badge rule therefore names a `path` carrying
+   * both a fill and a stroke, which a mask's stroke-less rects cannot be.
+   */
+  it("does not theme the fills d2 uses as mask channels", () => {
+    const themed = withThemeableColours(drawn(""));
+
+    expect(themed).not.toContain('[fill="white"]{');
+    expect(themed).not.toContain('[fill="black"]{');
+    expect(themed).toContain('path[fill="white"][stroke="#DEE1EB"]{');
+  });
+});
diff --git a/libs/@local/petrinaut-arch-docs/src/emit/d2.ts b/libs/@local/petrinaut-arch-docs/src/emit/d2.ts
index 3e3986a9dcc..b496f4304f6 100644
--- a/libs/@local/petrinaut-arch-docs/src/emit/d2.ts
+++ b/libs/@local/petrinaut-arch-docs/src/emit/d2.ts
@@ -21,6 +21,7 @@
  */
 
 import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
 
 import {
   isDeclaredEdge,
@@ -35,21 +36,53 @@ const quote = (text: string): string => JSON.stringify(text);
 /** Top-level ancestor of a dotted id, used for colour classing. */
 const rootSegment = (id: string): string => id.split(".")[0] ?? id;
 
+/**
+ * Fill and stroke per layer family, in one place because two things read it:
+ * the `classes` block below, which is what `d2` renders with, and the
+ * stylesheet appended to every rendered SVG, which restates each colour as a
+ * custom property so a host can retheme the diagram. Split across two
+ * declarations they would drift, and the drift would only show in dark mode.
+ */
+const layerPalette: Record<string, { fill: string; stroke: string }> = {
+  core: { fill: "#dcecff", stroke: "#3676b8" },
+  react: { fill: "#e8e0ff", stroke: "#7051b5" },
+  ui: { fill: "#e2f4e8", stroke: "#3d8055" },
+  petrinaut: { fill: "#fdeedc", stroke: "#b5762f" },
+  cli: { fill: "#fbe3e8", stroke: "#ad3a5b" },
+  "python-bindings": { fill: "#fff4d6", stroke: "#a3801f" },
+  optimizer: { fill: "#e0f2f1", stroke: "#2b7a72" },
+  website: { fill: "#eef3d9", stroke: "#6f8f2f" },
+  other: { fill: "#f2f2f2", stroke: "#777777" },
+  elided: { fill: "#ffffff", stroke: "#aaaaaa" },
+};
+
+/*
+ * Colours the authored diagrams reach for that mean something other than a
+ * layer family: the device a batch runs on, a case that falls back. They are
+ * not classes, so they never reach the `classes` block, but they do have to be
+ * themeable, or a hand-written diagram renders a pale box with pale text on it
+ * the moment a host goes dark.
+ */
+const accentPalette: Record<string, { fill: string; stroke: string }> = {
+  device: { fill: "#fff3d6", stroke: "#b8862b" },
+  caution: { fill: "#fdeaea", stroke: "#b83636" },
+};
+
+/** Everything the appended stylesheet hands to a custom property. */
+const themeableColours = { ...layerPalette, ...accentPalette };
+
 const styleClasses = [
   `classes: {`,
-  `  core: {style.fill: "#dcecff"; style.stroke: "#3676b8"}`,
-  `  react: {style.fill: "#e8e0ff"; style.stroke: "#7051b5"}`,
-  `  ui: {style.fill: "#e2f4e8"; style.stroke: "#3d8055"}`,
-  `  petrinaut: {style.fill: "#fdeedc"; style.stroke: "#b5762f"}`,
-  `  cli: {style.fill: "#fbe3e8"; style.stroke: "#ad3a5b"}`,
-  `  python-bindings: {style.fill: "#fff4d6"; style.stroke: "#a3801f"}`,
-  `  optimizer: {style.fill: "#e0f2f1"; style.stroke: "#2b7a72"}`,
-  `  website: {style.fill: "#eef3d9"; style.stroke: "#6f8f2f"}`,
-  `  other: {style.fill: "#f2f2f2"; style.stroke: "#777777"}`,
+  ...Object.entries(layerPalette)
+    .filter(([name]) => name !== "elided")
+    .map(
+      ([name, { fill, stroke }]) =>
+        `  ${name}: {style.fill: "${fill}"; style.stroke: "${stroke}"}`,
+    ),
   `  boundary: {style.stroke-dash: 4}`,
   `  declared: {style.stroke-dash: 2}`,
   `  focus: {style.stroke-width: 3; style.bold: true}`,
-  `  elided: {style.fill: "#ffffff"; style.stroke: "#aaaaaa"; style.stroke-dash: 3; style.italic: true}`,
+  `  elided: {style.fill: "${layerPalette.elided!.fill}"; style.stroke: "${layerPalette.elided!.stroke}"; style.stroke-dash: 3; style.italic: true}`,
   `}`,
 ].join("\n");
 
@@ -477,10 +510,119 @@ export const canRenderDiagrams = (repoRoot: string): boolean => {
  * `.d2` sources are the diffable artefact, and a missing renderer should not
  * block regenerating the model and pages.
  */
+/**
+ * `d2`'s own palette, as it writes it into every SVG: seven neutrals and the
+ * blues it draws connections and links with. Restated here so the appended
+ * stylesheet can hand each one to a custom property.
+ *
+ * Taken from the rendered output rather than from a `d2` theme file, because
+ * these are the values it bakes in at the default theme.
+ */
+const rendererPalette: Record<string, string> = {
+  n1: "#0A0F25",
+  n2: "#676C7E",
+  n3: "#9499AB",
+  n4: "#CFD2DD",
+  n5: "#DEE1EB",
+  n6: "#EEF1F8",
+  n7: "#FFFFFF",
+  b1: "#0D32B2",
+  b2: "#0D32B2",
+  b3: "#E3E9FD",
+  b4: "#E3E9FD",
+  b5: "#EDF0FD",
+  b6: "#F7F8FE",
+};
+
+/**
+ * Restates every colour in a rendered SVG as a custom property, so a host can
+ * retheme the diagram without the generator knowing anything about that host's
+ * themes.
+ *
+ * Appended as a stylesheet rather than rewritten into the markup, for two
+ * reasons. `var()` is not reliably honoured inside SVG presentation attributes,
+ * where the layer colours land, but is honoured in a declaration that overrides
+ * them, because any rule beats a presentation attribute. And `d2`'s own colours
+ * arrive as classes under a per-diagram `.d2-<hash>` scope, so matching that
+ * scope and coming later in the document is what wins the cascade without
+ * inventing specificity.
+ *
+ * Every property carries the original colour as its fallback, so a host that
+ * defines nothing renders exactly what `d2` drew.
+ */
+/**
+ * Rewrites a rendered diagram so a host page can recolour it.
+ *
+ * `d2` writes its palette straight into the markup, so a drawing carries one
+ * theme and keeps it. Each colour it drew is restated here as a custom property
+ * holding that same colour as its fallback, scoped to the `d2-<hash>` class the
+ * renderer puts on the drawing: a host that defines none of them gets exactly
+ * what `d2` drew, and one that defines them can follow its own light and dark
+ * themes. Markup carrying no such class is returned untouched.
+ */
+export const withThemeableColours = (markup: string): string => {
+  const scope = /class="(d2-\d+)/u.exec(markup)?.[1];
+
+  if (scope === undefined) {
+    return markup;
+  }
+
+  const rules = [
+    ...Object.entries(rendererPalette).flatMap(([token, colour]) => [
+      `.${scope} .fill-${token.toUpperCase()}{fill:var(--pnd-diagram-${token},${colour});}`,
+      `.${scope} .stroke-${token.toUpperCase()}{stroke:var(--pnd-diagram-${token},${colour});}`,
+    ]),
+    ...Object.entries(themeableColours).flatMap(([name, { fill, stroke }]) => [
+      `.${scope} [fill="${fill}"]{fill:var(--pnd-diagram-${name}-fill,${fill});}`,
+      `.${scope} [stroke="${stroke}"]{stroke:var(--pnd-diagram-${name}-stroke,${stroke});}`,
+    ]),
+    /*
+     * The badge that marks a node as carrying a tooltip. `d2` draws it outside
+     * its palette, so without these it stays a white disc with a near-black
+     * glyph whatever the host does.
+     *
+     * Matched on the pair of attributes rather than on `white` alone, and that
+     * is the whole point. `d2` knocks its connections out from behind their
+     * labels with a mask built from a white rect that shows everything and
+     * black rects over each label, where white and black are not colours but
+     * show and hide; theming those inverts the mask and every masked
+     * connection vanishes apart from the stubs behind its own labels. A mask
+     * holds only `rect` elements and none of them carry a stroke, so a
+     * `path` carrying both a fill and this stroke cannot be one.
+     */
+    `.${scope} path[fill="white"][stroke="#DEE1EB"]{fill:var(--pnd-diagram-badge-fill,#FFFFFF);stroke:var(--pnd-diagram-badge-edge,#DEE1EB);}`,
+    `.${scope} [stroke="#2E3346"]{stroke:var(--pnd-diagram-badge-mark,#2E3346);}`,
+  ].join("\n");
+
+  return markup.replace(
+    "</svg>",
+    `<style type="text/css"><![CDATA[\n${rules}\n]]></style></svg>`,
+  );
+};
+
+/** Where the vendored render fonts live, relative to the package root. */
+const fontPath = (packageRoot: string, file: string): string =>
+  `${packageRoot}/fonts/${file}`;
+
+/**
+ * Renders a `.d2` file to SVG.
+ *
+ * `d2` is provided by mise, matching how the previous script invoked it. When it
+ * is unavailable the caller is told rather than the build failing outright: the
+ * `.d2` sources are the diffable artefact, and a missing renderer should not
+ * block regenerating the model and pages.
+ *
+ * Rendered with the same face the docs are set in. This is not decoration: `d2`
+ * measures every label with the font it renders with and sizes the boxes from
+ * that, so a diagram drawn in one face and displayed in another has labels that
+ * no longer fit. The padding is `d2`'s 100px default cut to something that
+ * leaves the drawing room without a frame of empty page around it.
+ */
 export const renderD2 = (
   repoRoot: string,
   sourcePath: string,
   outputPath: string,
+  packageRoot: string,
 ): { ok: true } | { ok: false; error: string } => {
   const result = spawnSync(
     "mise",
@@ -492,6 +634,12 @@ export const renderD2 = (
       "d2",
       "--layout",
       "elk",
+      "--pad",
+      "16",
+      "--font-regular",
+      fontPath(packageRoot, "Inter-Regular.ttf"),
+      "--font-bold",
+      fontPath(packageRoot, "Inter-Bold.ttf"),
       sourcePath,
       outputPath,
     ],
@@ -509,5 +657,14 @@ export const renderD2 = (
     };
   }
 
+  try {
+    writeFileSync(
+      outputPath,
+      withThemeableColours(readFileSync(outputPath, "utf8")),
+    );
+  } catch (error) {
+    return { ok: false, error: String(error) };
+  }
+
   return { ok: true };
 };
diff --git a/yarn.lock b/yarn.lock
index 44d722ef213..d91c1b22e57 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -891,6 +891,7 @@ __metadata:
   resolution: "@apps/petrinaut-docs@workspace:apps/petrinaut-docs"
   dependencies:
     "@astrojs/check": "npm:0.9.10"
+    "@astrojs/markdown-remark": "npm:7.2.4"
     "@astrojs/react": "npm:6.0.2"
     "@astrojs/starlight": "npm:0.41.5"
     "@local/petrinaut-arch-docs": "workspace:*"
@@ -898,10 +899,12 @@ __metadata:
     "@types/react": "npm:19.2.14"
     "@types/react-dom": "npm:19.2.3"
     astro: "npm:7.1.6"
+    hast-util-from-html: "npm:2.0.3"
     react: "npm:19.2.6"
     react-dom: "npm:19.2.6"
     sharp: "npm:0.35.3"
     typescript: "npm:5.9.3"
+    unist-util-visit: "npm:5.1.0"
   languageName: unknown
   linkType: soft
 
@@ -1274,6 +1277,22 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@astrojs/internal-helpers@npm:0.10.4":
+  version: 0.10.4
+  resolution: "@astrojs/internal-helpers@npm:0.10.4"
+  dependencies:
+    "@types/hast": "npm:^3.0.4"
+    "@types/mdast": "npm:^4.0.4"
+    js-yaml: "npm:^4.3.0"
+    picomatch: "npm:^4.0.4"
+    retext-smartypants: "npm:^6.2.0"
+    shiki: "npm:^4.0.2"
+    smol-toml: "npm:^1.6.0"
+    unified: "npm:^11.0.5"
+  checksum: 10c0/2e789920c52597cfde72cb46524be92331b3a9b1d97a03d01e6d714fbbc905202b6949cfd9e5a33d241bf0b3275f5cfe7ffcbf3dd8652b3bc9345a8631b5af3c
+  languageName: node
+  linkType: hard
+
 "@astrojs/language-server@npm:^2.16.7":
   version: 2.16.13
   resolution: "@astrojs/language-server@npm:2.16.13"
@@ -1335,6 +1354,31 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@astrojs/markdown-remark@npm:7.2.4":
+  version: 7.2.4
+  resolution: "@astrojs/markdown-remark@npm:7.2.4"
+  dependencies:
+    "@astrojs/internal-helpers": "npm:0.10.4"
+    "@astrojs/prism": "npm:4.0.2"
+    github-slugger: "npm:^2.0.0"
+    hast-util-from-html: "npm:^2.0.3"
+    hast-util-to-text: "npm:^4.0.2"
+    mdast-util-definitions: "npm:^6.0.0"
+    rehype-raw: "npm:^7.0.0"
+    rehype-stringify: "npm:^10.0.1"
+    remark-gfm: "npm:^4.0.1"
+    remark-parse: "npm:^11.0.0"
+    remark-rehype: "npm:^11.1.2"
+    remark-smartypants: "npm:^3.0.2"
+    unified: "npm:^11.0.5"
+    unist-util-remove-position: "npm:^5.0.0"
+    unist-util-visit: "npm:^5.1.0"
+    unist-util-visit-parents: "npm:^6.0.2"
+    vfile: "npm:^6.0.3"
+  checksum: 10c0/8e82a79f9e19b759a9287db6cc0d40cbfd28bf908b6712b322a0d7de201583481951215b4fbfd1ce7a1c4b8f7c16e95de84d834b49a360a75c175a3009b172ae
+  languageName: node
+  linkType: hard
+
 "@astrojs/markdown-satteri@npm:0.3.5, @astrojs/markdown-satteri@npm:^0.3.2":
   version: 0.3.5
   resolution: "@astrojs/markdown-satteri@npm:0.3.5"
@@ -30233,7 +30277,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"hast-util-from-html@npm:^2.0.0, hast-util-from-html@npm:^2.0.3":
+"hast-util-from-html@npm:2.0.3, hast-util-from-html@npm:^2.0.0, hast-util-from-html@npm:^2.0.3":
   version: 2.0.3
   resolution: "hast-util-from-html@npm:2.0.3"
   dependencies:
@@ -44953,7 +44997,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"unist-util-visit@npm:^5.0.0, unist-util-visit@npm:^5.1.0":
+"unist-util-visit@npm:5.1.0, unist-util-visit@npm:^5.0.0, unist-util-visit@npm:^5.1.0":
   version: 5.1.0
   resolution: "unist-util-visit@npm:5.1.0"
   dependencies: