@norskvideo/ctl-dev-kit 0.1.22 → 0.1.24

package/conventions/check-drift.ts

@@ -218,6 +218,7 @@ export interface CanonicalBytes {
   flake: string;
   upgradeLatest: string;
   syncDevKit: string;
+  publishDocs: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -359,6 +360,21 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftRe
     );
   }
 
+  // publish-docs.yml is OPTIONAL — a product carries it once it has an
+  // illustrated manual to publish nightly. Unlike the workflows above it has NO
+  // per-repo line: it is deliberately product-agnostic (per-repo bits live in
+  // scripts/doc-guide/regen-manual.sh + an optional prepull-extra.sh), so it is a
+  // verbatim byte-for-byte copy of the canonical.
+  const publishDocsPath = join(repoRoot, ".github", "workflows", "publish-docs.yml");
+  if (existsSync(publishDocsPath)) {
+    const actual = readFileSync(publishDocsPath, "utf8");
+    if (actual !== canonical.publishDocs) {
+      push(
+        `.github/workflows/publish-docs.yml has drifted from @norskvideo/ctl-dev-kit conventions/publish-docs.yml (${firstDiffLine(actual, canonical.publishDocs)}). ${RESYNC}`,
+      );
+    }
+  }
+
   return { ok: problems.length === 0, problems };
 }
 
@@ -369,6 +385,7 @@ if (import.meta.main) {
     flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
     upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "utf8"),
+    publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
     checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(import.meta.dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(import.meta.dir, "tsconfig.base.json"), "utf8"),

package/conventions/docs.md

@@ -0,0 +1,133 @@
+# The illustrated product manual (shared across all Norsk ctl product repos)
+
+How a Norsk ctl product builds, writes, and publishes its **illustrated manual** —
+the self-contained HTML page a prospect or operator reads to understand what the
+product does. This is the shared half; the per-product half is the manual's
+actual page content, which lives in the product repo.
+
+Like [`personas.md`](./personas.md) this is a **shipped reference**, not a
+drift-gated copy: consume it from
+`node_modules/@norskvideo/ctl-dev-kit/conventions/docs.md`. The two things that
+ARE single-sourced and gated are the workflow (`publish-docs.yml`) and the
+toolchain library (`@norskvideo/ctl-dev-kit/doc-guide`); this file is the
+convention that ties them together.
+
+## What the manual is (and is not)
+
+The manual is one hash-routed HTML page assembled from **two cross-linked
+collections**, plus an overview:
+
+- **Functionality pages** — one capability per page (remote talent, live mixing,
+  output shapes, …). "What the product does."
+- **Example-deployment pages** — worked shows, each a concrete shape a reader can
+  recognise as close to their own. "What a real deployment looks like." Named as
+  starting points, never as a fixed menu or a tier ladder.
+- **Overview** — a hero capture and two ways in: by function, or by example.
+
+It is NOT the reference (`CommentaryConfig` / CI author material — that stays in
+`docs/reference.md` + `examples/`), NOT the operator runbook (host footprint,
+limitations — mostly ctl's), and NOT a feature checklist. It is the
+capability-first, illustrated front door.
+
+### Who reads it
+
+Name the reader before writing a page (see `personas.md` and the product's own
+`docs/personas.md`):
+
+- **Evaluator** — the overview, the example gallery, first light. Wants "does
+  this do what I need?" in minutes.
+- **Builder** — the illustrated task pages. The domain-fluent operator who stands
+  the show up and runs it.
+
+Integrator and Operator are served elsewhere (reference / ctl). Runtime actors
+(a commentator, a contributor, a producer) are NOT readers of the manual — the
+operator is the Builder; the others receive join links and onboarding kit.
+
+## Voice
+
+Customer- and Builder-facing, plain, capability-led. The rules that keep every
+product's manual in one voice:
+
+- **No internal/test vocabulary.** Never `engine`, `fixture`, `Playwright`,
+  `assertion`, `harness`, `instance`, `SSR`, a slug, or a DOM id in reader-facing
+  copy. The reader does not know or care how the shot was produced.
+- **Lead with the capability, not the UI state.** "A commentator joins from a
+  browser with a link" — not "the connections page shows a slot in the pending
+  state."
+- **Plain, not markety.** Describe what it does; skip the superlatives.
+- **No floor / ceiling / max / tier framing.** A deployment is described by its
+  shape ("compose and two delivery groups"), never as "the maximal build" or "the
+  ceiling" — the ceiling is wherever the customer needs it to be. Internal example
+  slugs (e.g. `commentary-max`) may keep the word; the copy a reader sees must not.
+- **Examples are starting points.** "Worked deployments — the pieces combine
+  freely; any show is described in config," not a menu the reader must pick from.
+
+## Captures
+
+Every screenshot is a REAL capture written by a doc-guide driving a real surface
+that the guide also asserts — so a shot can never depict a UI that does not
+exist. A guide runs at one of three tiers:
+
+- **Fixture** — the product's Vite app booted alone, fed representative state (no
+  daemon, no license). Proves the UI renders correctly. Fast; runs in CI.
+- **Frontend** — the standalone configure form, same model.
+- **Engine** — a REAL launched instance, driven live (On Air actually lighting
+  up, a real feed composited). Slow, licensed, nightly.
+
+Per-step treatments (`CaptureTreatment`, from the doc-guide library):
+
+- **full page** (default) — the whole surface, for orientation shots.
+- **`crop`** — a tight element screenshot of one component, by CSS selector, for
+  a close-up. Anchor crops on a stable `data-region` / `data-*` attribute the
+  component renders, not on incidental structure.
+- **`spotlight`** — the whole screen with one region lit and everything else
+  dimmed, for "look here, in context."
+
+## The toolchain
+
+All single-sourced in `@norskvideo/ctl-dev-kit/doc-guide` — products import it,
+they do not copy it:
+
+- `@norskvideo/ctl-dev-kit/doc-guide` — `DocGuide` (a guide narrates itself into
+  `docs/generated/<slug>/`), `screenshotFor`, `CaptureTreatment`. Writes under
+  `NORSK_DOCS_ROOT` (the repo-level `docs/generated`); the config factory sets it.
+- `@norskvideo/ctl-dev-kit/doc-guide/guides-config` — `guidesConfig({ port,
+  docsRoot, … })`, the Playwright config for the fixture/frontend tiers, carrying
+  the CI defaults (bind+probe `127.0.0.1`, 120s webServer timeout, piped output).
+- `@norskvideo/ctl-dev-kit/doc-guide/build-manual` — `buildManual(spec, {
+  docsRoot })`, the generic assembler. The product supplies ONLY the page content
+  (`ManualSpec`: brand, overview, functionality[], examples[]); layout, CSS and
+  routing live in the assembler so every product's manual looks the same.
+- `@norskvideo/ctl-dev-kit/doc-guide/{instance-proxy,live-browser}` — engine-tier
+  support (serve the baked dashboard under its advertised instance prefix; launch
+  the nix chromium for a live capture).
+- `doc-guide/with-display.sh` — wrap the run in an X display for headless chromium
+  on a true-headless Linux box. Copy it to the repo's `scripts/` (it must be a
+  repo-local executable the package.json guide scripts invoke).
+
+Per-repo, the product provides: its guide suites, a thin `build-manual.ts` that
+supplies the `ManualSpec` and does the file IO, and
+`scripts/doc-guide/regen-manual.sh` — the one command a release runs to drive
+every tier with capture-writing on, then assemble. `regen-manual.sh` owns the
+slug list and which tiers run (set `SKIP_ENGINE=1` to regenerate only the fast
+tiers). An engine tier needing images beyond the universal media+studio pair
+pulls them in an optional `scripts/doc-guide/prepull-extra.sh`.
+
+## The publish contract
+
+Latest-only, republished by ctl:
+
+- Each product's nightly (`publish-docs.yml`, single-sourced + drift-gated)
+  rebuilds the manual to ONE self-contained `manual.html` and publishes it as the
+  asset of a **moving `docs-latest` GitHub Release** — never versioned, its single
+  asset clobbered each night. Stable URL:
+  `https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html`.
+- **norsk-ctl's docs build fetches each registered product's `docs-latest` asset
+  and mounts it at `/products/<slug>/`**, deploying the one Cloudflare Pages
+  project — so ctl republishes every product's manual whenever it builds its docs.
+  A true per-product subdir on ctl's site only works by ctl aggregating, because a
+  Pages deploy is whole-site.
+
+Two files back the contract: `manual.html` (the standalone document — publish
+THIS, not the Artifact fragment `index.html`) and, on the ctl side, the product
+registry the aggregator reads.

package/conventions/publish-docs.yml

@@ -0,0 +1,141 @@
+# Nightly: regenerate this product's illustrated manual and publish it as the
+# product's "latest docs" artifact, for the norsk-ctl docs site to republish.
+#
+# THE CROSS-PRODUCT PATTERN (each product does this; norsk-ctl aggregates):
+#   - Every product's nightly rebuilds its manual to ONE self-contained
+#     `manual.html` and publishes it as the asset of a MOVING `docs-latest`
+#     GitHub Release. Latest-only: the release is never versioned, its single
+#     asset is clobbered each night. Stable URL:
+#       https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html
+#   - norsk-ctl's docs build fetches each registered product's `docs-latest`
+#     asset and mounts it under `/products/<slug>/`, deploying the one
+#     Cloudflare Pages project — so ctl republishes every product's manual
+#     whenever it builds its docs.
+#
+# This workflow is SINGLE-SOURCED in @norskvideo/ctl-dev-kit
+# (conventions/publish-docs.yml) and copied verbatim, same as checks.yml. It is
+# deliberately product-agnostic: everything per-repo lives in repo-local scripts
+# it calls —
+#   - scripts/doc-guide/regen-manual.sh   : the guide tiers + slug list + assemble
+#   - scripts/doc-guide/prepull-extra.sh  : OPTIONAL, any images beyond media+studio
+# so the drift gate can keep every product's copy byte-identical.
+#
+# Nightly-only by design: a guide's engine tier stands up real instances (slow,
+# and subject to teardown flakes), so it does not ride every push. The
+# licensed-runner setup mirrors integration.yml — ctl comes from the released
+# binary via NORSK_CTL_BINARY, Docker is used directly on the x64 pool.
+name: publish-docs
+
+on:
+  schedule:
+    - cron: "30 1 * * *" # 01:30 UTC — ahead of ctl's nightly docs build
+  workflow_dispatch:
+
+permissions:
+  contents: write # move the docs-latest release + clobber its asset
+
+concurrency:
+  group: publish-docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: x64
+    steps:
+      # A guide's engine tier launches the same docker instances the integration
+      # suite does, leaving root-owned bind-mount target dirs under test-temp/
+      # that the non-root runner can't remove — which fails actions/checkout's
+      # own cleanup before anything runs. Nuke them from a throwaway root
+      # container first. Best-effort. (Mirrors integration.yml.)
+      - name: Clear stale root-owned test-temp (pre-checkout)
+        run: |
+          set -uo pipefail
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          docker run --rm --user 0:0 -v "$tt":/t alpine sh \
+            -c 'rm -rf /t/* /t/.[!.]* 2>/dev/null || true' || rm -rf "$tt"/* 2>/dev/null || true
+
+      - uses: actions/checkout@v5
+        with:
+          clean: false
+
+      - name: Write the Norsk license (from the org secret)
+        env:
+          NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
+        run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
+
+      - name: Download the released norsk-ctl binary (latest channel)
+        run: |
+          set -euo pipefail
+          S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
+          ver="$(curl -fsSL "$S3/latest")"
+          echo "norsk-ctl latest channel -> $ver"
+          curl -fsSL "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
+          chmod +x "$RUNNER_TEMP/norsk-ctl"
+          "$RUNNER_TEMP/norsk-ctl" --version || true
+
+      # Cold-runner first pulls overrun the harness's per-test launch timeouts;
+      # pre-pull the universal media + studio images (every product pins them in
+      # manifest.seed.json) so compose/run hit local images. A product needing
+      # more (e.g. a WHIP driver) pulls them in scripts/doc-guide/prepull-extra.sh.
+      - name: Pre-pull the media + studio images
+        run: |
+          set -euo pipefail
+          for img in "$(jq -r '.latest.media' manifest.seed.json)" "$(jq -r '.latest.studio' manifest.seed.json)"; do
+            echo "pre-pulling $img"
+            docker pull "$img"
+          done
+          if [ -x scripts/doc-guide/prepull-extra.sh ]; then
+            echo "running scripts/doc-guide/prepull-extra.sh"
+            ./scripts/doc-guide/prepull-extra.sh
+          fi
+
+      # Rebuild every workspace the manual depends on (a guide's engine tier packs
+      # the freshly-built dashboard + frontend dist into the launched template),
+      # then run the product's doc-guide tiers and assemble the manual.
+      # regen-manual.sh owns the slug list and which tiers run; with-display.sh
+      # wraps the whole run in an X display for headless chromium (the engine tier
+      # drives a raw chromium that needs one).
+      - name: Regenerate the illustrated manual (all tiers)
+        env:
+          NORSK_CTL_BINARY: ${{ runner.temp }}/norsk-ctl
+          NORSK_LICENSE_FILE: ${{ runner.temp }}/norsk-license.json
+          # This runner launches Studio as a HOST sibling (DooD), so the harness
+          # reaches host-published ports via the host-gateway alias, not
+          # localhost — same as the integration suite.
+          NORSK_TEST_HOST: host.docker.internal
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # clean:false persists node_modules between runs for speed, but a
+            # workspace dep whose version moved leaves stale copies that
+            # --frozen-lockfile does not reliably relink, so a new export is "not
+            # found". Nuke EVERY node_modules — including nested per-workspace ones
+            # — for a deterministic install. A nightly can afford it.
+            find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
+            bun install --frozen-lockfile
+            bun run build:no-lint
+            bash scripts/with-display.sh scripts/doc-guide/regen-manual.sh
+          '
+
+      # Publish the assembled manual as the moving docs-latest release asset.
+      # gh is on PATH inside the nix shell; `upload --clobber` replaces the
+      # same-named asset in place, so the release stays latest-only.
+      - name: Publish manual.html to the moving docs-latest release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # Publish the STANDALONE document (complete <!doctype>…</html>), not
+            # the Artifact fragment index.html — ctl hosts it directly as a page.
+            man="docs/generated/manual/manual.html"
+            [ -s "$man" ] || { echo "::error::manual was not generated at $man"; exit 1; }
+            cp "$man" "$RUNNER_TEMP/manual.html"
+            if ! gh release view docs-latest >/dev/null 2>&1; then
+              gh release create docs-latest --title "Docs (latest)" --prerelease \
+                --notes "Latest product manual, rebuilt nightly and republished by the norsk-ctl docs site. Not a versioned release — the manual.html asset is clobbered each night."
+            fi
+            gh release upload docs-latest "$RUNNER_TEMP/manual.html" --clobber
+            echo "published -> docs-latest/manual.html"
+          '

package/conventions/sync-dev-kit.yml

@@ -138,7 +138,7 @@ jobs:
       - name: Open a reconciliation PR (gate red)
         if: steps.sync.outputs.changed == '1' && steps.gate.outcome == 'failure'
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          API_TOKEN: ${{ secrets.CI_DISPATCH_TOKEN }}
         run: |
           set -euo pipefail
           branch="sync-dev-kit/${{ steps.sync.outputs.new }}"
@@ -162,10 +162,22 @@ jobs:
             "    bun run lint && bun run typecheck && bun run test:unit   # a convention that breaks real code" \
             "" \
             "Resolve whichever is failing, pushing to this branch until green -- then merge.")"
-          if existing="$(gh pr list --head "$branch" --state open --json number -q '.[0].number')" && [ -n "$existing" ]; then
-            gh pr edit "$existing" --title "$title" --body "$body"
+          # gh is not on the self-hosted runner PATH (it lives only inside
+          # `nix develop`, and this step runs outside it), so create/update the PR
+          # straight against the REST API with the same PAT that pushed the branch.
+          # Using the PAT (not GITHUB_TOKEN) lets the PR's own checks run so a human
+          # sees the red/green. curl+jq are on the host PATH (the pin-resolve step
+          # above already uses them).
+          repo="${{ github.repository }}"; owner="${repo%%/*}"
+          api="https://api.github.com/repos/$repo/pulls"
+          curl_api=(--fail-with-body -sS -H "Authorization: Bearer $API_TOKEN" -H "Accept: application/vnd.github+json")
+          existing="$(curl "${curl_api[@]}" "$api?head=$owner:$branch&state=open" | jq -r '.[0].number // empty')"
+          if [ -n "$existing" ]; then
+            curl "${curl_api[@]}" -X PATCH "$api/$existing" \
+              --data "$(jq -nc --arg t "$title" --arg b "$body" '{title:$t, body:$b}')" >/dev/null
           else
-            gh pr create --base main --head "$branch" --title "$title" --body "$body"
+            curl "${curl_api[@]}" -X POST "$api" \
+              --data "$(jq -nc --arg t "$title" --arg b "$body" --arg h "$branch" '{title:$t, body:$b, head:$h, base:"main"}')" >/dev/null
           fi
 
       - name: Report "already fresh"

package/conventions/sync-drift.ts

@@ -153,6 +153,13 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
   syncWorkflow(repoRoot, ".github/workflows/upgrade-latest.yml", canonical.upgradeLatest, r);
   syncWorkflow(repoRoot, ".github/workflows/sync-dev-kit.yml", canonical.syncDevKit, r);
 
+  // publish-docs.yml is optional and verbatim (no per-repo line) — only re-sync a
+  // repo that already carries it, unlike biome/tsconfig which every repo must have.
+  const publishDocsRel = ".github/workflows/publish-docs.yml";
+  if (existsSync(join(repoRoot, publishDocsRel))) {
+    writeIfChanged(join(repoRoot, publishDocsRel), canonical.publishDocs, publishDocsRel, r.written);
+  }
+
   syncFlake(repoRoot, canonical.flake, r);
   syncClaude(repoRoot, canonical.core, r);
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
@@ -169,6 +176,7 @@ if (import.meta.main) {
     flake: readFileSync(join(dir, "..", "build", "flake.nix"), "utf8"),
     upgradeLatest: readFileSync(join(dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(dir, "sync-dev-kit.yml"), "utf8"),
+    publishDocs: readFileSync(join(dir, "publish-docs.yml"), "utf8"),
     checks: readFileSync(join(dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(dir, "tsconfig.base.json"), "utf8"),

package/doc-guide/build-manual.ts

@@ -0,0 +1,244 @@
+// Generic assembler for a ctl product's illustrated manual: two cross-linked
+// collections (functionality pages + example-deployment pages), each a step
+// walkthrough, rendered into one self-contained, hash-routed HTML page.
+//
+// Every screenshot is a real capture a doc-guide wrote under
+// <docsRoot>/<slug>/<slug>-00N.png. This assembler reads those PNGs, resizes each
+// with ImageMagick, inlines it as a data URI, and returns both the Artifact
+// FRAGMENT (index.html — the Artifact tool supplies the doctype/head/body) and a
+// complete STANDALONE document (manual.html — for hosting the manual directly as
+// a page). A referenced shot that hasn't been generated yet renders as a labelled
+// gap rather than crashing the build; every gap is reported in `missing`.
+//
+// Product-specific content — the page arrays, the overview copy, the brand — is
+// supplied by the caller in `ManualSpec`; everything structural (layout, CSS,
+// routing) lives here so every product's manual looks and behaves the same.
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export type Step = { slug: string; file: string; head: string; desc: string };
+
+export type ManualPage = {
+  id: string;
+  nav: string;
+  title: string;
+  kind: "fn" | "ex";
+  tag?: string;
+  intro: string;
+  steps: Step[];
+  links: string[];
+  thin?: boolean;
+};
+
+export interface ManualOverview {
+  /** The overview <h1>. */
+  headline: string;
+  /** The lead paragraph under it. */
+  lead: string;
+  /** The hero capture (a representative shot) and its caption. */
+  hero: { slug: string; file: string; alt: string; caption: string };
+  /** Left column heading of the two-up index. Default "By function". */
+  byFunctionHeading?: string;
+  /** Right column heading. Default "By example". */
+  byExampleHeading?: string;
+  /** The small print under the right column heading. */
+  byExampleIntro: string;
+}
+
+export interface ManualSpec {
+  /** Sidebar wordmark + document brand. */
+  brand: string;
+  /** The full <title> for both the fragment and the standalone document. */
+  title: string;
+  overview: ManualOverview;
+  functionality: ManualPage[];
+  examples: ManualPage[];
+}
+
+export interface BuildManualResult {
+  /** Artifact-ready fragment (no doctype/head/body). */
+  indexHtml: string;
+  /** Complete standalone document wrapping the fragment. */
+  standaloneHtml: string;
+  /** `<slug>/<file>` of every referenced capture not found on disk. */
+  missing: string[];
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** Resize a captured PNG to <=1100px wide JPEG and return a data URI. Missing
+ *  captures become a labelled placeholder so the manual still builds. */
+function makeUri(docsRoot: string, slug: string, file: string, missing: string[]): string {
+  const path = join(docsRoot, slug, file);
+  if (!existsSync(path)) {
+    missing.push(`${slug}/${file}`);
+    const label = esc(`missing: ${slug}/${file}`);
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="880" height="200"><rect width="100%" height="100%" fill="#1a2230"/><text x="50%" y="50%" fill="#6b7787" font-family="monospace" font-size="15" text-anchor="middle" dominant-baseline="middle">${label}</text></svg>`;
+    return `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+  }
+  const r = spawnSync("magick", [path, "-resize", "1100x>", "-quality", "82", "jpg:-"], {
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (r.status !== 0 || !r.stdout?.length) {
+    throw new Error(`magick failed for ${path}: ${r.stderr?.toString() ?? "no output"}`);
+  }
+  return `data:image/jpeg;base64,${r.stdout.toString("base64")}`;
+}
+
+export function buildManual(spec: ManualSpec, opts: { docsRoot: string }): BuildManualResult {
+  const { docsRoot } = opts;
+  const missing: string[] = [];
+  const uri = (slug: string, file: string) => makeUri(docsRoot, slug, file, missing);
+
+  const FN = spec.functionality;
+  const EX = spec.examples;
+  const ALL = [...FN, ...EX];
+  const byId = new Map(ALL.map((p) => [p.id, p]));
+
+  function pageHtml(p: ManualPage): string {
+    const steps = p.steps
+      .map(
+        (s, i) => `<li class="step">
+      <div class="stinfo"><span class="stnum">${String(i + 1).padStart(2, "0")}</span><div><h3>${esc(s.head)}</h3><p>${esc(s.desc)}</p></div></div>
+      <div class="shot"><img loading="lazy" src="${uri(s.slug, s.file)}" alt="${esc(s.head)}"></div>
+    </li>`,
+      )
+      .join("\n");
+    const links = p.links.length
+      ? `<div class="xlinks"><span class="xlab">${p.kind === "fn" ? "Seen in" : "Uses"}</span>${p.links
+          .map((id) => {
+            const t = byId.get(id);
+            return t ? `<a href="#${id}" class="chip">${esc(t.nav)}</a>` : "";
+          })
+          .join("")}</div>`
+      : "";
+    const thin = p.thin
+      ? `<p class="thin">More of this walkthrough is coming — this deployment shape has one screen captured so far.</p>`
+      : "";
+    return `<article class="page" id="${p.id}">
+    <div class="phead"><span class="kind ${p.kind}">${p.kind === "fn" ? "Functionality" : "Example deployment"}</span><h1>${esc(p.title)}</h1>${p.tag ? `<div class="ptag mono">${esc(p.tag)}</div>` : ""}</div>
+    <p class="lead">${esc(p.intro)}</p>
+    <ol class="steps">${steps}</ol>
+    ${thin}${links}
+  </article>`;
+  }
+
+  const ov = spec.overview;
+  const overview = `<article class="page" id="overview">
+  <div class="phead"><span class="kind ov">Overview</span><h1>${esc(ov.headline)}</h1></div>
+  <p class="lead">${esc(ov.lead)}</p>
+  <div class="heroshot"><div class="shot"><img src="${uri(ov.hero.slug, ov.hero.file)}" alt="${esc(ov.hero.alt)}"></div><p class="hcap">${esc(ov.hero.caption)}</p></div>
+  <div class="twocol">
+    <div><h2>${esc(ov.byFunctionHeading ?? "By function")}</h2><div class="linklist">${FN.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div></div>
+    <div><h2>${esc(ov.byExampleHeading ?? "By example")}</h2><p class="mini">${esc(ov.byExampleIntro)}</p><div class="linklist">${EX.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div></div>
+  </div>
+</article>`;
+
+  const nav = `
+  <a href="#overview" data-nav class="ovlink">Overview</a>
+  <div class="ngroup"><div class="ghead">Functionality</div>${FN.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>
+  <div class="ngroup"><div class="ghead">Examples <span class="ct">${EX.length}</span></div>${EX.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>`;
+
+  const html = `<title>${esc(spec.title)}</title>
+<style>
+:root{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;--faint:#5f6a79;
+  --line:#212a36;--accent:#54d6cf;--measure:64ch}
+@media (prefers-color-scheme:light){:root{--bg:#f5f7f9;--bg2:#eef1f4;--surf:#fff;--ink:#0f1620;
+  --dim:#54606e;--faint:#8c96a3;--line:#e2e7ec;--accent:#0c8f86}}
+:root[data-theme="dark"]{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;
+  --faint:#5f6a79;--line:#212a36;--accent:#54d6cf}
+:root[data-theme="light"]{--bg:#f5f7f9;--bg2:#eef1f4;--surf:#fff;--ink:#0f1620;--dim:#54606e;
+  --faint:#8c96a3;--line:#e2e7ec;--accent:#0c8f86}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);line-height:1.6;
+  font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;-webkit-font-smoothing:antialiased}
+.mono{font-family:ui-monospace,"SF Mono",Menlo,monospace}
+.wrap{display:grid;grid-template-columns:264px minmax(0,1fr);max-width:1400px;margin:0 auto}
+aside{position:sticky;top:0;align-self:start;height:100vh;overflow-y:auto;padding:26px 18px 48px;
+  border-right:1px solid var(--line);background:var(--bg2)}
+.brand{font-family:ui-monospace,Menlo,monospace;font-size:11px;letter-spacing:.2em;text-transform:uppercase;color:var(--accent);margin-bottom:22px}
+aside a{display:block;text-decoration:none;color:var(--dim);padding:6px 10px;border-radius:7px;font-size:13px;line-height:1.35}
+aside a:hover{background:var(--surf);color:var(--ink)}
+aside a.active{background:var(--surf);color:var(--ink);box-shadow:inset 2px 0 0 var(--accent)}
+.ovlink{margin-bottom:16px;font-weight:600;color:var(--ink)}
+.ngroup{margin-bottom:20px}
+.ghead{font-family:ui-monospace,Menlo,monospace;font-size:10.5px;letter-spacing:.16em;text-transform:uppercase;color:var(--faint);margin:0 10px 6px;display:flex;gap:8px;align-items:center}
+.ct{background:var(--surf);border:1px solid var(--line);border-radius:20px;padding:0 6px;font-size:9.5px;color:var(--dim)}
+main{min-width:0;padding:0 clamp(20px,5vw,72px)}
+.page{display:none;max-width:840px;padding:52px 0 88px;animation:fade .18s ease}
+.page.on{display:block}
+@keyframes fade{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:none}}
+@media (prefers-reduced-motion:reduce){.page{animation:none}}
+.phead{margin-bottom:20px}
+.kind{display:inline-block;font-family:ui-monospace,Menlo,monospace;font-size:10px;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);margin-bottom:12px}
+.kind.ex{color:var(--dim)}.kind.ov{color:var(--faint)}
+.phead h1{font-size:clamp(26px,4vw,42px);line-height:1.05;letter-spacing:-.028em;margin:0;font-weight:730;text-wrap:balance}
+.ptag{margin-top:12px;font-size:12px;color:var(--faint)}
+.lead{font-size:clamp(15px,1.9vw,18px);color:var(--dim);max-width:var(--measure);margin:0 0 8px}
+
+.steps{list-style:none;margin:34px 0 0;padding:0}
+.step{padding:28px 0;border-top:1px solid var(--line)}
+.stinfo{display:flex;gap:16px;align-items:baseline;margin-bottom:16px;max-width:var(--measure)}
+.stnum{font-family:ui-monospace,Menlo,monospace;font-size:13px;color:var(--accent);flex:none;padding-top:2px}
+.stinfo h3{font-size:17px;margin:0 0 4px;letter-spacing:-.01em}
+.stinfo p{margin:0;color:var(--dim);font-size:14.5px}
+.shot{border:1px solid var(--line);border-radius:12px;overflow:hidden;background:#000;box-shadow:0 22px 46px -32px rgba(0,0,0,.8)}
+.shot img{display:block;max-width:100%;height:auto;margin:0 auto}
+.heroshot{margin-bottom:36px}
+.heroshot .shot{border-color:color-mix(in srgb,var(--accent) 24%,var(--line))}
+.hcap{margin:12px 0 0;color:var(--dim);font-size:13px;max-width:56ch}
+
+.thin{margin-top:26px;font-family:ui-monospace,Menlo,monospace;font-size:12px;color:var(--faint);
+  background:var(--surf);border:1px dashed var(--line);border-radius:9px;padding:11px 14px;max-width:var(--measure)}
+.xlinks{margin-top:36px;padding-top:22px;border-top:1px solid var(--line);display:flex;flex-wrap:wrap;gap:10px;align-items:center}
+.xlab{font-family:ui-monospace,Menlo,monospace;font-size:10.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--faint);margin-right:4px}
+.chip{text-decoration:none;font-size:13px;color:var(--ink);background:var(--surf);border:1px solid var(--line);border-radius:20px;padding:6px 13px}
+.chip:hover{border-color:var(--accent);color:var(--accent)}
+.twocol{display:grid;grid-template-columns:1fr 1fr;gap:32px;margin-top:40px;padding-top:30px;border-top:1px solid var(--line)}
+.twocol h2{font-size:15px;margin:0 0 12px}
+.mini{font-size:12.5px;color:var(--faint);margin:0 0 12px;max-width:40ch}
+.linklist{display:flex;flex-direction:column;gap:2px}
+.linklist a{text-decoration:none;color:var(--dim);font-size:14px;padding:5px 0}
+.linklist a:hover{color:var(--accent)}
+@media (max-width:880px){.wrap{grid-template-columns:1fr}
+  aside{position:static;height:auto;border-right:none;border-bottom:1px solid var(--line)}
+  .twocol{grid-template-columns:1fr}}
+</style>
+
+<div class="wrap">
+<aside><div class="brand">${esc(spec.brand)}</div>${nav}</aside>
+<main>
+${overview}
+${ALL.map(pageHtml).join("\n")}
+</main>
+</div>
+
+<script>
+(function(){
+  var pages=[].slice.call(document.querySelectorAll('.page'));
+  var links=[].slice.call(document.querySelectorAll('[data-nav]'));
+  function show(){var id=(location.hash||'#overview').slice(1);
+    if(!document.getElementById(id))id='overview';
+    pages.forEach(function(p){p.classList.toggle('on',p.id===id)});
+    links.forEach(function(a){a.classList.toggle('active',a.getAttribute('href')==='#'+id)});
+    window.scrollTo(0,0);}
+  window.addEventListener('hashchange',show);show();
+})();
+</script>`;
+
+  const standaloneHtml = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${esc(spec.title)}</title>
+</head>
+<body>
+${html}
+</body>
+</html>`;
+
+  return { indexHtml: html, standaloneHtml, missing };
+}

package/doc-guide/doc-guide.ts

@@ -0,0 +1,174 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import type { Page } from "@playwright/test";
+
+// Shared support for a product repo's Playwright/engine doc-guides. A guide drives
+// a real surface (a configure SPA, an operator dashboard, a launched instance) and
+// narrates itself; entries render to an illustrated markdown manual under
+// <repo>/docs/generated/<slug>/. Screenshots can never depict a UI that doesn't
+// exist, because they come from a real, asserted run.
+//
+// Extracted from norsk-commentary (which took it from norsk-ctl) into the dev kit
+// so every ctl product shoots its manual the same way. The one thing that had to
+// change on the way in: the old copy resolved docs/generated RELATIVE TO ITS OWN
+// FILE, which worked only while it lived in the repo. Living in node_modules it
+// cannot, so the docs root is now explicit — NORSK_DOCS_ROOT if set, else
+// <cwd>/docs/generated. A fixture runner whose cwd is a package subdir (e.g.
+// dashboards/<slug>) MUST export NORSK_DOCS_ROOT to the repo-level dir; the
+// guidesConfig() factory does this for you. Resolution is deferred to call time
+// so the env var need only be set before the first capture, not before import.
+
+export type UiEntry =
+  | { kind: "section"; heading: string }
+  | { kind: "step"; heading: string; description?: string }
+  | { kind: "text"; prose: string }
+  | { kind: "capture"; caption: string; filename: string };
+
+export interface UiFixture {
+  type: "ui";
+  title: string;
+  entries: UiEntry[];
+}
+
+/** Resolve the repo-level docs/generated root. NORSK_DOCS_ROOT wins (absolute or
+ *  relative to cwd); otherwise <cwd>/docs/generated, which is correct for runners
+ *  whose cwd is the repo root (the engine tier). Deferred, not module-level, so a
+ *  config that sets the env var at eval time is honoured. */
+export function docsRoot(): string {
+  const override = process.env.NORSK_DOCS_ROOT;
+  if (override) return isAbsolute(override) ? override : resolve(process.cwd(), override);
+  return resolve(process.cwd(), "docs/generated");
+}
+
+/** Per-step screenshot treatment. `crop` shoots one component at its own bounds;
+ *  `spotlight` keeps the whole screen for context but dims everything except the
+ *  named region and outlines it. Omit both for a plain full-page capture. */
+export interface CaptureTreatment {
+  crop?: string;
+  spotlight?: string;
+  /** Slack in px around a spotlight region before the dimming starts. */
+  pad?: number;
+}
+
+const SPOTLIGHT_ID = "docguide-spotlight";
+
+/** Dim the page except the target region, drawn as one fixed box whose oversized
+ *  box-shadow does the dimming — appended to <body> so no ancestor `overflow`
+ *  clips it. Scrolls the target into view first so the lit region is on-screen. */
+async function spotlightOn(page: Page, selector: string, pad: number): Promise<void> {
+  await page.locator(selector).first().scrollIntoViewIfNeeded();
+  await page.evaluate(
+    ({ selector, pad, id }) => {
+      const el = document.querySelector(selector);
+      if (!el) throw new Error(`spotlight target not found: ${selector}`);
+      const r = el.getBoundingClientRect();
+      const box = document.createElement("div");
+      box.id = id;
+      Object.assign(box.style, {
+        position: "fixed",
+        left: `${Math.max(0, r.left - pad)}px`,
+        top: `${Math.max(0, r.top - pad)}px`,
+        width: `${r.width + pad * 2}px`,
+        height: `${r.height + pad * 2}px`,
+        border: "2px solid #54d6cf",
+        borderRadius: "10px",
+        boxShadow: "0 0 0 4000px rgba(6,9,13,0.62)",
+        zIndex: "2147483647",
+        pointerEvents: "none",
+      } satisfies Partial<CSSStyleDeclaration>);
+      document.body.appendChild(box);
+    },
+    { selector, pad, id: SPOTLIGHT_ID },
+  );
+}
+
+async function spotlightOff(page: Page): Promise<void> {
+  await page.evaluate((id) => document.getElementById(id)?.remove(), SPOTLIGHT_ID);
+}
+
+/** Produce the screenshot bytes for a capture, applying its treatment. Split out
+ *  from `DocGuide.capture` (which also gates on DOCS_GENERATE and writes the file)
+ *  so the treatment geometry is testable on its own. */
+export async function screenshotFor(page: Page, treat?: CaptureTreatment): Promise<Buffer> {
+  // Wait for web fonts, else the snapshot catches a fallback font mid-swap.
+  await page.evaluate(() => document.fonts.ready);
+  if (treat?.crop) return page.locator(treat.crop).first().screenshot();
+  if (treat?.spotlight) {
+    await spotlightOn(page, treat.spotlight, treat.pad ?? 8);
+    try {
+      return await page.screenshot();
+    } finally {
+      await spotlightOff(page);
+    }
+  }
+  return page.screenshot({ fullPage: true });
+}
+
+/** Pure markdown assembly — exposed so a render step can re-emit markdown from a
+ * stored entries.json without re-running the browser. */
+export function renderUiMarkdown(title: string, entries: UiEntry[]): string {
+  const lines: string[] = ["---", `title: ${title}`, "---", "", `# ${title}`, ""];
+  for (const entry of entries) {
+    switch (entry.kind) {
+      case "section":
+        lines.push(`## ${entry.heading}`, "");
+        break;
+      case "step":
+        lines.push(`### ${entry.heading}`, "");
+        if (entry.description) lines.push(entry.description, "");
+        break;
+      case "text":
+        lines.push(entry.prose, "");
+        break;
+      case "capture":
+        lines.push(`![${entry.caption}](./${entry.filename})`, "");
+        break;
+    }
+  }
+  return lines.join("\n");
+}
+
+export class DocGuide {
+  private entries: UiEntry[] = [];
+  private captureIndex = 0;
+
+  constructor(
+    private slug: string,
+    private title: string,
+  ) {}
+
+  section(heading: string): void {
+    this.entries.push({ kind: "section", heading });
+  }
+
+  step(heading: string, description?: string): void {
+    this.entries.push({ kind: "step", heading, description });
+  }
+
+  text(prose: string): void {
+    this.entries.push({ kind: "text", prose });
+  }
+
+  /** Screenshot the page and write it immediately under the slug's docs dir. Pass
+   *  a treatment to crop to one component or spotlight a region in context. */
+  async capture(page: Page, caption: string, treat?: CaptureTreatment): Promise<void> {
+    if (process.env.DOCS_GENERATE !== "1") return;
+    this.captureIndex++;
+    const filename = `${this.slug}-${String(this.captureIndex).padStart(3, "0")}.png`;
+    const buffer = await screenshotFor(page, treat);
+    const outDir = join(docsRoot(), this.slug);
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, filename), buffer);
+    this.entries.push({ kind: "capture", caption, filename });
+  }
+
+  /** Write entries.json + the rendered index.md under docs/generated/<slug>/. */
+  async flush(): Promise<void> {
+    if (process.env.DOCS_GENERATE !== "1") return;
+    const outDir = join(docsRoot(), this.slug);
+    mkdirSync(outDir, { recursive: true });
+    const fixture: UiFixture = { type: "ui", title: this.title, entries: this.entries };
+    writeFileSync(join(outDir, "entries.json"), `${JSON.stringify(fixture, null, 2)}\n`);
+    writeFileSync(join(outDir, "index.md"), renderUiMarkdown(this.title, this.entries));
+  }
+}

package/doc-guide/guides-config.ts

@@ -0,0 +1,63 @@
+import { defineConfig, type PlaywrightTestConfig } from "@playwright/test";
+
+// Playwright config factory for a product's FIXTURE-tier doc-guides: boot the
+// product's Vite app alone (no daemon, no license, no Docker) and drive it to
+// produce illustrated manual captures under <repo>/docs/generated/<slug>/.
+//
+// Carries the hard-won CI defaults so every product's runner behaves the same:
+//   - bind + probe 127.0.0.1 explicitly. On CI runners `localhost` can resolve to
+//     IPv6 ::1 first while Vite listens on IPv4, so the readiness probe never gets
+//     200 and the webServer "times out" though the server is up.
+//   - a 120s webServer timeout (cold CI runners are slow to first-serve) and piped
+//     stdout/stderr so a stuck boot shows in the log.
+//   - export NORSK_DOCS_ROOT so the dev-kit DocGuide writes to the REPO-level
+//     docs/generated even though the runner's cwd is a package subdir. Set here at
+//     config-eval time, before any guide imports doc-guide.ts.
+//
+// Chromium comes from the nix flake via BROWSER_FOR_TESTING; the guide script
+// wraps the whole run in with-display.sh to supply an X display.
+
+export interface GuidesConfigOptions {
+  /** Vite port. Pick one clear of the product's dev servers and sibling sessions. */
+  port: number;
+  /** Absolute path to the repo-level docs/generated dir. Exported as NORSK_DOCS_ROOT. */
+  docsRoot: string;
+  /** Capture viewport. Default 1440x960. */
+  viewport?: { width: number; height: number };
+  /** webServer command. Default `bunx vite --port <port> --strictPort --host 127.0.0.1`. */
+  command?: string;
+  /** Playwright testDir. Default "./tests/guides". */
+  testDir?: string;
+  /** Per-test timeout in ms. Default 60_000. */
+  timeout?: number;
+}
+
+export function guidesConfig(opts: GuidesConfigOptions): PlaywrightTestConfig {
+  // Exported before the test files import the dev-kit DocGuide, so its deferred
+  // docsRoot() resolves to the repo-level dir rather than <package>/docs/generated.
+  process.env.NORSK_DOCS_ROOT = opts.docsRoot;
+
+  const baseURL = `http://127.0.0.1:${opts.port}`;
+  const command = opts.command ?? `bunx vite --port ${opts.port} --strictPort --host 127.0.0.1`;
+
+  return defineConfig({
+    testDir: opts.testDir ?? "./tests/guides",
+    workers: 1,
+    timeout: opts.timeout ?? 60_000,
+    use: {
+      baseURL,
+      browserName: "chromium",
+      headless: true,
+      viewport: opts.viewport ?? { width: 1440, height: 960 },
+      ...(process.env.BROWSER_FOR_TESTING && { launchOptions: { executablePath: process.env.BROWSER_FOR_TESTING } }),
+    },
+    webServer: {
+      command,
+      url: baseURL,
+      reuseExistingServer: !process.env.CI,
+      timeout: 120_000, // cold CI runners are slow to first-serve
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+  });
+}

package/doc-guide/instance-proxy.ts

@@ -0,0 +1,111 @@
+// A tiny per-instance reverse proxy for the engine-tier doc-guides.
+//
+// A product's baked operator dashboard is built to run behind the runner's oauth2
+// proxy: its `env` endpoint advertises instance-scoped paths
+// (`apiBasePath: /instance/<id>/live/api`, `wsBasePath: /instance/<id>/live`).
+// The harness, though, publishes Studio DIRECTLY on studioHostPort with no
+// `/instance/<id>` prefix — so those advertised paths 404 and the console never
+// leaves its "workflow starting up" splash.
+//
+// Rather than drag the whole oauth2 proxy + TLS + port 443 into a doc run, this
+// serves the dashboard under exactly the prefix `env` advertises and strips it
+// before forwarding to studioHostPort — for both HTTP and the live-state
+// WebSocket (`useLiveComponent`), which is what carries programReceiving / audio
+// levels and therefore the ON AIR badge. Plain HTTP, ephemeral port, self-owned.
+
+import type { ServerWebSocket } from "bun";
+
+interface WsBridge {
+  upstreamUrl: string;
+  upstream: WebSocket | null;
+  queue: (string | ArrayBufferLike | Uint8Array)[];
+}
+
+export interface InstanceProxy {
+  /** Origin of the proxy, e.g. http://localhost:53421 */
+  origin: string;
+  /** Full dashboard URL for a hash-routed page, under the advertised prefix. */
+  dashboardUrl: (page?: string) => string;
+  stop: () => void;
+}
+
+// Response headers that describe the upstream transfer encoding; fetch() has
+// already decoded the body, so forwarding these would misdescribe what we send.
+const STRIP_RESPONSE_HEADERS = ["content-encoding", "content-length", "transfer-encoding"];
+
+/** Start a reverse proxy that serves `${prefix}/…` by forwarding `/…` to
+ *  studioHostPort. `prefix` equals the instance's advertised `studioUrlPrefix`
+ *  (`/instance/<instanceId>`); `dashboardKey` is the product's baked dashboard
+ *  path segment (the dashboard is served at `/dashboard/<dashboardKey>/`). */
+export function startInstanceProxy(opts: {
+  studioHostPort: number;
+  instanceId: string;
+  dashboardKey: string;
+}): InstanceProxy {
+  const prefix = `/instance/${opts.instanceId}`;
+  const httpUpstream = `http://localhost:${opts.studioHostPort}`;
+  const strip = (pathname: string): string =>
+    pathname === prefix ? "/" : pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length) : pathname;
+
+  const server = Bun.serve<WsBridge>({
+    port: 0,
+    async fetch(req, srv) {
+      const u = new URL(req.url);
+      const path = strip(u.pathname);
+
+      if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+        const upstreamUrl = `ws://localhost:${opts.studioHostPort}${path}${u.search}`;
+        const ok = srv.upgrade(req, { data: { upstreamUrl, upstream: null, queue: [] } });
+        return ok ? undefined : new Response("ws upgrade failed", { status: 400 });
+      }
+
+      const headers = new Headers(req.headers);
+      headers.delete("host");
+      const body = req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer();
+      const upstream = await fetch(`${httpUpstream}${path}${u.search}`, {
+        method: req.method,
+        headers,
+        body,
+        redirect: "manual",
+      });
+      const outHeaders = new Headers(upstream.headers);
+      for (const h of STRIP_RESPONSE_HEADERS) outHeaders.delete(h);
+      return new Response(upstream.body, { status: upstream.status, headers: outHeaders });
+    },
+    websocket: {
+      open(ws: ServerWebSocket<WsBridge>) {
+        const up = new WebSocket(ws.data.upstreamUrl);
+        up.binaryType = "arraybuffer";
+        ws.data.upstream = up;
+        up.onopen = () => {
+          for (const m of ws.data.queue) up.send(m as string | ArrayBufferLike);
+          ws.data.queue = [];
+        };
+        up.onmessage = (e: MessageEvent) => ws.send(e.data);
+        up.onclose = (e: CloseEvent) => ws.close(e.code || 1000, e.reason);
+        up.onerror = () => {
+          try {
+            ws.close();
+          } catch {}
+        };
+      },
+      message(ws: ServerWebSocket<WsBridge>, message: string | Buffer) {
+        const up = ws.data.upstream;
+        if (up && up.readyState === WebSocket.OPEN) up.send(message);
+        else ws.data.queue.push(message);
+      },
+      close(ws: ServerWebSocket<WsBridge>) {
+        try {
+          ws.data.upstream?.close();
+        } catch {}
+      },
+    },
+  });
+
+  const origin = `http://localhost:${server.port}`;
+  return {
+    origin,
+    dashboardUrl: (page = "onair") => `${origin}${prefix}/dashboard/${opts.dashboardKey}/#/${page}`,
+    stop: () => server.stop(true),
+  };
+}

package/doc-guide/live-browser.ts

@@ -0,0 +1,29 @@
+// Engine-tier doc-guide browser support. The fixture-tier guides run under the
+// @playwright/test runner against a Vite dev server; the engine tier instead
+// drives a REAL launched instance from inside a bun:test that already owns the
+// product harness lifecycle. So we launch a raw chromium here (the same nixpkgs
+// chromium the fixture tier uses, via BROWSER_FOR_TESTING) rather than go through
+// the test-runner's webServer model.
+
+import { type Browser, type BrowserContext, chromium, type Page } from "@playwright/test";
+
+export interface LiveBrowser {
+  browser: Browser;
+  context: BrowserContext;
+  page: Page;
+}
+
+/** Launch headless chromium for a live-dashboard capture. Uses the nix-provided
+ *  chromium (BROWSER_FOR_TESTING) so no Playwright browser download is needed;
+ *  --no-sandbox because the nix chromium has no setuid sandbox helper. */
+export async function launchLiveBrowser(opts?: { viewport?: { width: number; height: number } }): Promise<LiveBrowser> {
+  const executablePath = process.env.BROWSER_FOR_TESTING;
+  if (!executablePath) {
+    throw new Error("BROWSER_FOR_TESTING is unset — run inside `nix develop` so chromium is on offer");
+  }
+  const browser = await chromium.launch({ executablePath, args: ["--no-sandbox"] });
+  const viewport = opts?.viewport ?? { width: 1440, height: 960 };
+  const context = await browser.newContext({ viewport, deviceScaleFactor: 1 });
+  const page = await context.newPage();
+  return { browser, context, page };
+}

package/doc-guide/with-display.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Run "$@" with an X DISPLAY available — passes through if one is already set,
+# otherwise wraps in xvfb-run. Needed because nix-pinned headless chromium on
+# a true-headless Linux box silently no-ops page.fill on plain HTML inputs and
+# crashes the renderer on some pages; giving it a real X display avoids both.
+# On Mac this is a no-op (xvfb-run isn't on PATH and Apple's chromium doesn't
+# need it).
+#
+# Part of the @norskvideo/ctl-dev-kit doc-guide toolchain. A product copies this
+# to its own scripts/ (it must be a repo-local executable the package.json guide
+# scripts can invoke); the dev-kit is the canonical source.
+
+set -euo pipefail
+
+if [ -n "${DISPLAY:-}" ] || ! command -v xvfb-run >/dev/null 2>&1; then
+  exec "$@"
+fi
+
+exec xvfb-run -a --server-args="-screen 0 1280x720x24" "$@"

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     "./testing/invariants": "./testing/invariants.ts",
     "./testing/byte-snapshot": "./testing/byte-snapshot.ts",
-    "./create-product": "./create-product/create-product.ts"
+    "./create-product": "./create-product/create-product.ts",
+    "./doc-guide": "./doc-guide/doc-guide.ts",
+    "./doc-guide/build-manual": "./doc-guide/build-manual.ts",
+    "./doc-guide/guides-config": "./doc-guide/guides-config.ts",
+    "./doc-guide/instance-proxy": "./doc-guide/instance-proxy.ts",
+    "./doc-guide/live-browser": "./doc-guide/live-browser.ts"
   },
   "bin": {
     "ctl-dev-kit": "./create-product/cli.ts"
@@ -14,6 +19,14 @@
   "dependencies": {
     "@norskvideo/ctl-sdk": "^0.1.0"
   },
+  "peerDependencies": {
+    "@playwright/test": "*"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }