@norskvideo/ctl-dev-kit 0.2.53 → 0.2.55

package/doc-guide/doc-guide.js

@@ -10,6 +10,37 @@ export function docsRoot() {
         return isAbsolute(override) ? override : resolve(process.cwd(), override);
     return resolve(process.cwd(), "docs/generated");
 }
+/** The spoken ceiling for one step. The video spikes measured a step narrating
+ *  at about 2.5 words/s: 35 words is 14 s on one still, 50 is 20 s, and the
+ *  renderer's own lint warns at 35. This is the hard stop. */
+export const DEFAULT_CAPTION_WORDS = 50;
+const SPOKEN_WORD = /[\p{L}\p{N}]/u;
+const RAW_URL = /https?:\/\/\S+/;
+const SLASH_BETWEEN_WORDS = /\S+\/\S+/;
+/** Why a step's text cannot be narrated as written, or null when it can. Pure,
+ *  so the wording is pinned without a browser. Checks the budget first: an
+ *  over-long caption gets rewritten anyway, and the rewrite is where the
+ *  phrasing gets fixed. */
+export function captionFault(text, budget) {
+    const count = text.split(/\s+/).filter((token) => SPOKEN_WORD.test(token)).length;
+    if (count > budget)
+        return `${count} words; the spoken budget is ${budget}`;
+    const url = RAW_URL.exec(text);
+    if (url)
+        return `contains a raw URL ("${url[0]}"); say "the address" and let the page carry the link`;
+    const slash = SLASH_BETWEEN_WORDS.exec(text);
+    if (slash)
+        return `contains a slash between words ("${slash[0]}"); write "or" or "and", or hyphenate`;
+    return null;
+}
+/** Device scale factor for a capture: 2 in a DOCS_GENERATE run, 1 otherwise.
+ *  The video spike found the manual's component crops 383 to 778 px wide; in
+ *  a 1080p frame they are soft, and no renderer recovers detail that was never
+ *  captured. A plain run writes no captures, so it keeps 1x and is unchanged.
+ *  One place for both tiers: guidesConfig and launchLiveBrowser read it. */
+export function captureScaleFactor() {
+    return process.env.DOCS_GENERATE === "1" ? 2 : 1;
+}
 /** The attributes Studio's shared MoQ player (norsk-studio-built-ins
  *  `lib/shared/moq-player`) stamps on the container it mounts into. `live`
  *  means the first video frame has decoded — not that the transport is up or
@@ -18,35 +49,161 @@ export function docsRoot() {
 export const MOQ_PHASE_ATTR = "data-moq-phase";
 export const MOQ_ERROR_ATTR = "data-moq-error";
 const LIVE_PICTURE_TIMEOUT_MS = 60_000;
+const LIVE_PICTURE_POLL_MS = 250;
+const LIVE_PICTURE_FRAME_GAP_MS = 500;
+/** Slates and modals a tile must not be showing. Products add their own via
+ *  `occluderSelectors`; the text pattern catches a slate rendered as DOM text. */
+export const DEFAULT_OCCLUDER_SELECTORS = ["[data-slate]", '[role="dialog"]', ".modal"];
+export const DEFAULT_OCCLUDER_TEXT = /temporarily unavailable|standby/i;
+export const FRAME_SAMPLE_W = 32;
+export const FRAME_SAMPLE_H = 18;
+const DEFAULT_PIXEL_DELTA = 6;
+const DEFAULT_MIN_CHANGED_FRACTION = 0.02;
+function changedFraction(a, b, pixelDelta) {
+    const n = Math.min(a.length, b.length);
+    if (n === 0)
+        return 0;
+    let changed = 0;
+    for (let i = 0; i < n; i++)
+        if (Math.abs(a[i] - b[i]) > pixelDelta)
+            changed++;
+    return changed / n;
+}
+function phaseReason(phase, error) {
+    if (phase === null)
+        return "not stamped — is a player mounted there?";
+    return phase === "error" && error ? `error: ${error}` : phase;
+}
+/** Rule on whether the tile is showing a live picture, naming the first
+ *  check that says it is not. */
+export function judgeLivePicture(evidence, motion = {}) {
+    if (evidence.phase !== "live")
+        return { live: false, check: "phase", reason: phaseReason(evidence.phase, evidence.error) };
+    if (evidence.coveredBy !== null)
+        return { live: false, check: "covered", reason: `the tile's centre is under "${evidence.coveredBy}"` };
+    if (evidence.occluders.length > 0)
+        return {
+            live: false,
+            check: "occluded",
+            reason: `a slate or modal is visible inside the tile: ${evidence.occluders.join(", ")}`,
+        };
+    if (evidence.frames === null)
+        return { live: false, check: "undrawable", reason: "no video or canvas inside the tile to sample" };
+    const need = motion.minChangedFraction ?? DEFAULT_MIN_CHANGED_FRACTION;
+    const moved = changedFraction(evidence.frames[0], evidence.frames[1], motion.pixelDelta ?? DEFAULT_PIXEL_DELTA);
+    if (moved < need)
+        return {
+            live: false,
+            check: "frozen",
+            reason: `the picture did not change across ${evidence.frameGapMs}ms (${(moved * 100).toFixed(1)}% of sampled pixels moved; need ${need * 100}%)`,
+        };
+    return { live: true };
+}
 /** The failure a guide sees when a tile never shows a picture: the tile, the
  *  phase it was stuck in and, for an error, the player's own reason — so a
  *  broken preview reads as what it is rather than as a timeout. Pure, so the
  *  wording is pinned without a browser. */
 export function livePictureFailure(selector, phase, error, timeoutMs) {
-    const state = phase === null
-        ? "not stamped — is a player mounted there?"
-        : phase === "error" && error
-            ? `error: ${error}`
-            : phase;
-    return `the MoQ preview at "${selector}" never decoded a frame in ${timeoutMs}ms (phase: ${state})`;
-}
-/** Block until the tile at `selector` reports a decoded frame, or fail saying
- *  why it did not. This is the wait a guide puts between "the source connected"
- *  and the capture: the player mounts at that moment, and a screenshot taken
- *  then is of a spinner. A wall-clock sleep would hide a broken preview; this
- *  turns it into a named failure. */
-export async function awaitLivePicture(page, selector, opts) {
-    const timeoutMs = opts?.timeoutMs ?? LIVE_PICTURE_TIMEOUT_MS;
-    try {
-        await page.waitForFunction(({ selector, attr }) => document.querySelector(selector)?.getAttribute(attr) === "live", { selector, attr: MOQ_PHASE_ATTR }, { timeout: timeoutMs });
+    return `the MoQ preview at "${selector}" never decoded a frame in ${timeoutMs}ms (phase: ${phaseReason(phase, error)})`;
+}
+/** The failure for whichever check the tile never passed. The phase check
+ *  keeps its original wording; the composite checks name themselves. */
+export function livePictureGateFailure(selector, verdict, timeoutMs) {
+    if (verdict.check === "phase") {
+        return `the MoQ preview at "${selector}" never decoded a frame in ${timeoutMs}ms (phase: ${verdict.reason})`;
     }
-    catch {
-        const [phase, error] = await page.evaluate(({ selector, phaseAttr, errorAttr }) => {
-            const el = document.querySelector(selector);
-            return [el?.getAttribute(phaseAttr) ?? null, el?.getAttribute(errorAttr) ?? null];
-        }, { selector, phaseAttr: MOQ_PHASE_ATTR, errorAttr: MOQ_ERROR_ATTR });
-        throw new Error(livePictureFailure(selector, phase, error, timeoutMs));
+    return `the MoQ preview at "${selector}" never showed a live picture in ${timeoutMs}ms (${verdict.check}: ${verdict.reason})`;
+}
+/** Gather, in the page, everything `judgeLivePicture` rules on. Stops at the
+ *  phase when the tile is not live: the frame samples cost `frameGapMs`. */
+async function collectLivePictureEvidence(page, selector, gate) {
+    return page.evaluate(async ({ selector, phaseAttr, errorAttr, occluderSelectors, occluderText, frameGapMs, w, h }) => {
+        const el = document.querySelector(selector);
+        const phase = el?.getAttribute(phaseAttr) ?? null;
+        const error = el?.getAttribute(errorAttr) ?? null;
+        const evidence = { phase, error, coveredBy: null, occluders: [], frames: null, frameGapMs };
+        if (!el || phase !== "live")
+            return evidence;
+        const describe = (n) => `${n.tagName.toLowerCase()}${n.id ? `#${n.id}` : ""}${Array.from(n.classList)
+            .map((c) => `.${c}`)
+            .join("")}`;
+        let r = el.getBoundingClientRect();
+        if (r.bottom < 0 || r.right < 0 || r.top > innerHeight || r.left > innerWidth) {
+            el.scrollIntoView({ block: "nearest", inline: "nearest" });
+            r = el.getBoundingClientRect();
+        }
+        const hit = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        if (hit === null)
+            evidence.coveredBy = "nothing (is the tile off-screen?)";
+        else if (!el.contains(hit))
+            evidence.coveredBy = describe(hit);
+        const visible = (n) => n.getClientRects().length > 0 && getComputedStyle(n).visibility !== "hidden";
+        for (const sel of occluderSelectors) {
+            if (Array.from(el.querySelectorAll(sel)).some(visible))
+                evidence.occluders.push(sel);
+        }
+        if (occluderText) {
+            const match = new RegExp(occluderText.source, occluderText.flags).exec(el.innerText ?? "");
+            if (match)
+                evidence.occluders.push(`text "${match[0]}"`);
+        }
+        const drawable = el.matches("video, canvas") ? el : el.querySelector("video, canvas");
+        if (!drawable)
+            return evidence;
+        const scratch = document.createElement("canvas");
+        scratch.width = w;
+        scratch.height = h;
+        const ctx = scratch.getContext("2d");
+        if (!ctx)
+            return evidence;
+        const sample = () => {
+            ctx.drawImage(drawable, 0, 0, w, h);
+            const d = ctx.getImageData(0, 0, w, h).data;
+            const luma = [];
+            for (let i = 0; i < d.length; i += 4)
+                luma.push(Math.round(0.299 * d[i] + 0.587 * d[i + 1] + 0.114 * d[i + 2]));
+            return luma;
+        };
+        const first = sample();
+        await new Promise((resolve) => setTimeout(resolve, frameGapMs));
+        evidence.frames = [first, sample()];
+        return evidence;
+    }, {
+        selector,
+        phaseAttr: MOQ_PHASE_ATTR,
+        errorAttr: MOQ_ERROR_ATTR,
+        occluderSelectors: [...gate.occluderSelectors],
+        occluderText: gate.occluderText ? { source: gate.occluderText.source, flags: gate.occluderText.flags } : null,
+        frameGapMs: gate.frameGapMs,
+        w: FRAME_SAMPLE_W,
+        h: FRAME_SAMPLE_H,
+    });
+}
+/** Block until the tile at `selector` shows a live picture, or fail saying
+ *  which check it never passed. This is the wait a guide puts between "the
+ *  source connected" and the capture: the player mounts at that moment, and a
+ *  screenshot taken then is of a spinner. A wall-clock sleep would hide a
+ *  broken preview; this turns it into a named failure.
+ *
+ *  Live means: the player stamped `live`, nothing else sits at the tile's
+ *  centre, no slate or modal is visible inside it, and its picture moved
+ *  between two samples. The last two are what let a standby slate and a
+ *  modal over the hero through the phase check alone (2026-10-07). */
+export async function awaitLivePicture(page, selector, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? LIVE_PICTURE_TIMEOUT_MS;
+    const gate = {
+        occluderSelectors: opts.occluderSelectors ?? DEFAULT_OCCLUDER_SELECTORS,
+        occluderText: opts.occluderText === undefined ? DEFAULT_OCCLUDER_TEXT : opts.occluderText,
+        frameGapMs: opts.frameGapMs ?? LIVE_PICTURE_FRAME_GAP_MS,
+    };
+    const deadline = Date.now() + timeoutMs;
+    let verdict = judgeLivePicture(await collectLivePictureEvidence(page, selector, gate), opts);
+    while (!verdict.live && Date.now() < deadline) {
+        await page.waitForTimeout(LIVE_PICTURE_POLL_MS);
+        verdict = judgeLivePicture(await collectLivePictureEvidence(page, selector, gate), opts);
     }
+    if (!verdict.live)
+        throw new Error(livePictureGateFailure(selector, verdict, timeoutMs));
 }
 const SPOTLIGHT_ID = "docguide-spotlight";
 /** Dim the page except the target region, drawn as one fixed box whose oversized
@@ -113,8 +270,12 @@ export async function awaitFontsReady(page, timeoutMs = FONTS_READY_TIMEOUT_MS)
  *  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, treat) {
-    if (treat?.livePicture)
-        await awaitLivePicture(page, treat.livePicture, { timeoutMs: treat.livePictureTimeoutMs });
+    if (treat?.livePicture) {
+        await awaitLivePicture(page, treat.livePicture, {
+            timeoutMs: treat.livePictureTimeoutMs,
+            ...treat.livePictureGate,
+        });
+    }
     // Wait for web fonts, else the snapshot catches a fallback font mid-swap --
     // but not forever (see awaitFontsReady).
     if (!(await awaitFontsReady(page))) {
@@ -157,24 +318,48 @@ export function renderUiMarkdown(title, entries) {
     }
     return lines.join("\n");
 }
+/** The budget a guide is held to: an explicit option, else the env var the
+ *  config factory exports, else the default. Read at call time, like docsRoot. */
+export function captionBudget(option) {
+    if (option !== undefined)
+        return option;
+    const fromEnv = Number(process.env.NORSK_DOCS_CAPTION_WORDS);
+    return Number.isInteger(fromEnv) && fromEnv > 0 ? fromEnv : DEFAULT_CAPTION_WORDS;
+}
+const TEXT_LABEL_WORDS = 6;
 export class DocGuide {
     slug;
     title;
+    options;
     entries = [];
     captureIndex = 0;
-    constructor(slug, title) {
+    constructor(slug, title, options = {}) {
         this.slug = slug;
         this.title = title;
+        this.options = options;
     }
     section(heading) {
         this.entries.push({ kind: "section", heading });
     }
     step(heading, description) {
+        this.lintCaption(`step "${heading}"`, description ? `${heading} ${description}` : heading);
         this.entries.push({ kind: "step", heading, description });
     }
     text(prose) {
+        const label = prose.split(/\s+/).slice(0, TEXT_LABEL_WORDS).join(" ");
+        this.lintCaption(`text "${label} ..."`, prose);
         this.entries.push({ kind: "text", prose });
     }
+    /** Only the DOCS_GENERATE run is published and narrated, so only it is held
+     *  to the spoken budget; a plain run of the guide asserts the UI and says
+     *  nothing about the prose. */
+    lintCaption(what, narrated) {
+        if (process.env.DOCS_GENERATE !== "1")
+            return;
+        const fault = captionFault(narrated, captionBudget(this.options.captionWords));
+        if (fault)
+            throw new Error(`doc-guide "${this.slug}": ${what} cannot be narrated: ${fault}`);
+    }
     /** 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, caption, treat) {

package/doc-guide/guides-config.d.ts

@@ -9,11 +9,17 @@ export interface GuidesConfigOptions {
         width: number;
         height: number;
     };
+    /** Pixel density of the captures. Default 2 in a DOCS_GENERATE run, 1
+     *  otherwise (see captureScaleFactor): crops shot at 1x are soft in a video frame. */
+    deviceScaleFactor?: 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;
+    /** Spoken-word budget for one step's text in a DOCS_GENERATE run (see
+     *  DocGuide). Exported as NORSK_DOCS_CAPTION_WORDS. Default: the dev-kit's 50. */
+    captionWords?: number;
 }
 export declare function guidesConfig(opts: GuidesConfigOptions): PlaywrightTestConfig;

package/doc-guide/guides-config.js

@@ -1,8 +1,11 @@
 import { defineConfig } from "@playwright/test";
+import { captureScaleFactor } from "./doc-guide.js";
 export function guidesConfig(opts) {
     // 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;
+    if (opts.captionWords !== undefined)
+        process.env.NORSK_DOCS_CAPTION_WORDS = String(opts.captionWords);
     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({
@@ -14,6 +17,7 @@ export function guidesConfig(opts) {
             browserName: "chromium",
             headless: true,
             viewport: opts.viewport ?? { width: 1440, height: 960 },
+            deviceScaleFactor: opts.deviceScaleFactor ?? captureScaleFactor(),
             ...(process.env.BROWSER_FOR_TESTING && { launchOptions: { executablePath: process.env.BROWSER_FOR_TESTING } }),
         },
         webServer: {

package/doc-guide/live-browser.d.ts

@@ -12,4 +12,6 @@ export declare function launchLiveBrowser(opts?: {
         width: number;
         height: number;
     };
+    /** Default: captureScaleFactor() -- 2 in a DOCS_GENERATE run, 1 otherwise. */
+    deviceScaleFactor?: number;
 }): Promise<LiveBrowser>;

package/doc-guide/live-browser.js

@@ -5,6 +5,7 @@
 // chromium the fixture tier uses, via BROWSER_FOR_TESTING) rather than go through
 // the test-runner's webServer model.
 import { chromium } from "@playwright/test";
+import { captureScaleFactor } from "./doc-guide.js";
 /** 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. */
@@ -15,7 +16,10 @@ export async function launchLiveBrowser(opts) {
     }
     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 context = await browser.newContext({
+        viewport,
+        deviceScaleFactor: opts?.deviceScaleFactor ?? captureScaleFactor(),
+    });
     const page = await context.newPage();
     return { browser, context, page };
 }

package/docs/guide-stubs.ts

@@ -0,0 +1,304 @@
+#!/usr/bin/env bun
+// Recorded guides: the placeholder a docs site builds against when a guide's
+// capture has not run, and the gate that refuses to publish one.
+//
+// A site's recorded guides (the Playwright doc-guide output under a gitignored
+// `docs/generated/`) reach the site as SYMLINKS under its content dir --
+// `website/src/content/docs/guides/<slug> -> ../../../../../docs/generated/<slug>`
+// -- and adding a guide means adding one. The symlinks are the one declaration
+// of which guides exist: there is no list restated here and no name glob (the
+// `zero-to-hero-*` glob this once carried skipped a Manager slug, and the site
+// failed to build for a guide the gate was never even asked about). Each
+// symlink also names the tree it stubs into, so one module serves every site:
+// norsk-ctl's, the Manager's, and each product's.
+//
+//   stub <content-dir>...       write a placeholder index.md for every declared
+//                               guide whose target is missing, creating the
+//                               tree, never touching a file that exists -- so
+//                               `docs:site` builds on a checkout with no captures.
+//   list <content-dir>...       the stub file each declared guide would get
+//                               (absolute, each once), writing nothing; a
+//                               Makefile takes its prerequisites from this.
+//   check [--allow-stub <name>[,<name>]] [--allow-missing <dir>[,<dir>]]
+//         [--content <content-dir>]... <generated-dir>...
+//                               exit 1 naming each placeholder it would publish.
+//                               A generated dir given directly must be populated
+//                               (an unpopulated tree is not a passing one; the
+//                               release run's captures were not restored).
+//                               --content names a site's content dir instead:
+//                               its symlink targets are the guides, and a site
+//                               that declares none has nothing to refuse -- a
+//                               product site publishes from committed prose and
+//                               must stay green with no captures anywhere.
+//                               --allow-stub names guides whose stub is a
+//                               `::warning::` rather than a refusal (the cloud
+//                               guides, captured weekly while the site publishes
+//                               nightly); --allow-missing names generated dirs
+//                               that may not exist yet.
+//   summary [--content <dir>]... <generated-dir>...
+//                               a Markdown table for the job summary: each
+//                               guide, live capture or stub, and what it was
+//                               captured against (the page's front matter).
+//
+// Why the gate: a placeholder is right for a local build and wrong for a
+// deploy. A publish that runs without the captures restored would REPLACE the
+// live guides with placeholders, and nothing else would notice -- the build is
+// green, the links resolve, the pages are just empty. The sentence `stub`
+// writes is what `check` refuses, and both live here so they cannot drift.
+import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+/** The sentence a placeholder carries, and the one `check` refuses. */
+export const GUIDE_STUB_MARKER = "Content for this guide is recorded by the doc-guide run";
+
+/** Generated directories that are not recorded guides: `cli docgen` writes
+ *  cli-reference as help-all.md, so it has no index.md to stub or to be a
+ *  stub of. */
+export const NOT_A_GUIDE = new Set(["cli-reference"]);
+
+/** A guide a site declares: the symlink's name, and the index.md its target
+ *  implies. */
+export interface DeclaredGuide {
+  name: string;
+  /** Absolute path of the symlink. */
+  link: string;
+  /** Absolute path of the target's index.md -- which may not exist. */
+  stub: string;
+}
+
+export interface GuideFile {
+  path: string;
+  /** The guide directory's name -- what `--allow-stub` matches. */
+  name: string;
+  text: string;
+}
+
+function isGeneratedTarget(target: string): boolean {
+  return target.split("/").includes("generated");
+}
+
+/** The guides a site declares: every symlink under each content dir that
+ *  points into a `generated` tree. A content dir that does not exist yet is
+ *  skipped. Resolved as path arithmetic, not realpath: on a fresh checkout the
+ *  target's parents do not exist. */
+export function declaredGuides(contentDirs: readonly string[]): DeclaredGuide[] {
+  const out: DeclaredGuide[] = [];
+  for (const contentDir of contentDirs) {
+    const dir = resolve(contentDir);
+    if (!existsSync(dir)) continue;
+    const entries = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isSymbolicLink() && !NOT_A_GUIDE.has(e.name))
+      .map((e) => e.name)
+      .sort();
+    for (const name of entries) {
+      const link = join(dir, name);
+      const target = readlinkSync(link);
+      if (!isGeneratedTarget(target)) continue;
+      out.push({ name, link, stub: resolve(dirname(link), target, "index.md") });
+    }
+  }
+  return out;
+}
+
+/** The same stub reached through two sites' symlinks is one file. */
+function uniqueByStub(guides: DeclaredGuide[]): DeclaredGuide[] {
+  const seen = new Set<string>();
+  return guides.filter((g) => !seen.has(g.stub) && seen.add(g.stub));
+}
+
+export function listGuideStubs(contentDirs: readonly string[]): string[] {
+  return uniqueByStub(declaredGuides(contentDirs)).map((g) => g.stub);
+}
+
+export function stubText(name: string): string {
+  return `---\ntitle: ${name}\n---\n\n${GUIDE_STUB_MARKER}. Run \`bun run docs:guides\` locally to populate it.\n`;
+}
+
+/** Write a placeholder for every declared guide whose index.md is missing.
+ *  A file that exists -- a real capture, or an earlier placeholder -- is never
+ *  rewritten. */
+export function stubGuides(contentDirs: readonly string[]): { written: string[]; existing: string[] } {
+  const written: string[] = [];
+  const existing: string[] = [];
+  for (const guide of uniqueByStub(declaredGuides(contentDirs))) {
+    if (existsSync(guide.stub)) {
+      existing.push(guide.stub);
+      continue;
+    }
+    mkdirSync(dirname(guide.stub), { recursive: true });
+    writeFileSync(guide.stub, stubText(guide.name));
+    written.push(guide.stub);
+  }
+  return { written, existing };
+}
+
+export function stubbedGuides(files: readonly { path: string; text: string }[]): string[] {
+  if (files.length === 0) throw new Error("no guides found -- docs/generated was never populated");
+  return files.filter((f) => f.text.includes(GUIDE_STUB_MARKER)).map((f) => f.path);
+}
+
+/** What a rendered page says it was captured against (the doc-guide renderer
+ *  writes the block; the values are quoted strings). */
+export function capturedAgainst(text: string): { norsk?: string; norskMgr?: string; when?: string } {
+  const head = text.split(/^---$/m)[1] ?? "";
+  const block = /^capturedAgainst:\n((?:[ ]{2}\w+: "[^"\n]*"\n)+)/m.exec(head)?.[1] ?? "";
+  const out: Record<string, string> = {};
+  for (const m of block.matchAll(/^[ ]{2}(\w+): "([^"\n]*)"$/gm)) out[m[1]] = m[2];
+  return out;
+}
+
+/** The job-summary table: one row per guide. */
+export function summaryTable(files: readonly GuideFile[]): string {
+  const rows = files.map((f) => {
+    if (f.text.includes(GUIDE_STUB_MARKER)) return `| \`${f.path}\` | **stub** | — |`;
+    const a = capturedAgainst(f.text);
+    const against = [a.norskMgr && `norsk-mgr ${a.norskMgr}`, a.norsk && `Norsk Manager ${a.norsk}`]
+      .filter(Boolean)
+      .join(", ");
+    return `| \`${f.path}\` | live capture | ${a.when ? `${a.when}${against ? ` — ${against}` : ""}` : "(no capturedAgainst)"} |`;
+  });
+  return ["| guide | content | captured |", "| --- | --- | --- |", ...rows].join("\n");
+}
+
+/** A guide directory without its index.md is as unpublishable as a stub. */
+function readGuide(path: string, name: string, file: string): GuideFile {
+  try {
+    return { path, name, text: readFileSync(file, "utf8") };
+  } catch {
+    return { path, name, text: GUIDE_STUB_MARKER };
+  }
+}
+
+export class GuideTreeMissing extends Error {}
+
+export interface ReadGuidesOptions {
+  /** Generated dirs that may not exist yet: a warning, not a refusal. */
+  allowMissing?: ReadonlySet<string>;
+  warn?: (message: string) => void;
+}
+
+/** Every guide under each generated dir. A dir that does not exist is a
+ *  restore failure (GuideTreeMissing) unless it is allowed missing: for a
+ *  section whose captures come from a run that may not have happened yet,
+ *  refusing would take the whole site down with it. */
+export function readGuides(dirs: readonly string[], opts: ReadGuidesOptions = {}): GuideFile[] {
+  const allowMissing = opts.allowMissing ?? new Set();
+  const warn = opts.warn ?? ((m) => console.error(m));
+  const files: GuideFile[] = [];
+  for (const dir of dirs) {
+    let names: string[] = [];
+    try {
+      names = readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !NOT_A_GUIDE.has(e.name))
+        .map((e) => e.name)
+        .sort();
+    } catch {
+      if (allowMissing.has(resolve(dir))) {
+        warn(`::warning::guide check: ${dir} has never been captured -- its pages will be stubs`);
+        continue;
+      }
+      throw new GuideTreeMissing(`${dir} does not exist -- the release run's captures were not restored`);
+    }
+    // Paths are reported under the package's name so two roots' guides cannot
+    // be confused (norsk-ctl's and norsk-mgr's roots are both called
+    // docs/generated; the package dir two levels up tells them apart).
+    const label = dirs.length > 1 ? `${basename(resolve(dir, "../.."))}/${basename(dir)}/` : "";
+    for (const name of names) files.push(readGuide(`${label}${name}/index.md`, name, join(dir, name, "index.md")));
+  }
+  return files;
+}
+
+/** The guides a site declares, read from their symlink targets. Reported
+ *  relative to the working directory, which is where the workflow runs. */
+export function readDeclaredGuides(contentDirs: readonly string[], cwd = process.cwd()): GuideFile[] {
+  return uniqueByStub(declaredGuides(contentDirs)).map((g) => readGuide(relative(cwd, g.stub), g.name, g.stub));
+}
+
+function usage(): never {
+  console.error(
+    [
+      "usage: guide-stubs.ts stub <content-dir>...",
+      "       guide-stubs.ts list <content-dir>...",
+      "       guide-stubs.ts check [--allow-stub <name>[,<name>]] [--allow-missing <dir>[,<dir>]] [--content <dir>]... <generated-dir>...",
+      "       guide-stubs.ts summary [--content <dir>]... <generated-dir>...",
+    ].join("\n"),
+  );
+  process.exit(2);
+}
+
+if (import.meta.main) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const allowStub = new Set<string>();
+  const allowMissing = new Set<string>();
+  const contentDirs: string[] = [];
+  const dirs: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i] as string;
+    if (arg === "--allow-stub") {
+      for (const n of (rest[++i] ?? "").split(",")) if (n) allowStub.add(n);
+    } else if (arg === "--allow-missing") {
+      for (const d of (rest[++i] ?? "").split(",")) if (d) allowMissing.add(resolve(d));
+    } else if (arg === "--content") {
+      contentDirs.push(rest[++i] ?? usage());
+    } else if (arg.startsWith("-")) usage();
+    else dirs.push(arg);
+  }
+
+  if (cmd === "stub" || cmd === "list") {
+    if (contentDirs.length > 0 || dirs.length === 0) usage();
+    if (cmd === "list") {
+      for (const f of listGuideStubs(dirs)) console.log(f);
+    } else {
+      for (const f of stubGuides(dirs).written) console.log(`stubbed ${f}`);
+    }
+    process.exit(0);
+  }
+  if ((cmd !== "check" && cmd !== "summary") || (dirs.length === 0 && contentDirs.length === 0)) usage();
+
+  let files: GuideFile[];
+  try {
+    files = [...readGuides(dirs, { allowMissing }), ...readDeclaredGuides(contentDirs)];
+  } catch (e) {
+    if (!(e instanceof GuideTreeMissing)) throw e;
+    console.error(`::error::guide check: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (cmd === "summary") {
+    console.log(summaryTable(files));
+    process.exit(0);
+  }
+
+  if (files.length === 0 && dirs.length === 0) {
+    console.log(`guide check: no recorded guides are declared by ${contentDirs.join(", ")}; nothing to refuse.`);
+    process.exit(0);
+  }
+
+  let stubs: string[];
+  try {
+    stubs = stubbedGuides(files);
+  } catch (e) {
+    console.error(`::error::guide check: ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  // A tolerated stub is a warning; a tree of nothing but tolerated stubs is
+  // still an unpopulated tree.
+  const tolerated = files.filter((f) => stubs.includes(f.path) && allowStub.has(f.name)).map((f) => f.path);
+  const refused = stubs.filter((s) => !tolerated.includes(s));
+  for (const s of tolerated) {
+    console.error(
+      `::warning::guide check: ${s} is a placeholder -- publishing without it (no capture yet, or none saved)`,
+    );
+  }
+  if (refused.length > 0) {
+    console.error(`::error::guide check: ${refused.length} guide(s) are placeholders, refusing to publish:`);
+    for (const s of refused) console.error(`  ${s}`);
+    process.exit(1);
+  }
+  if (tolerated.length === files.length) {
+    console.error("::error::guide check: every guide is a placeholder -- docs/generated was never populated");
+    process.exit(1);
+  }
+  console.log(`guide check: ${files.length} guide(s), ${tolerated.length} tolerated stub(s), the rest real.`);
+}