@norskvideo/ctl-dev-kit 0.2.53 → 0.2.55

package/conventions/sync-drift.ts

@@ -11,6 +11,8 @@
 //   - nix/ctl-shell.nix                              -> overwrite with canonical (created if absent)
 //   - flake.nix (legacy verbatim copy only)          -> the starter, repo's floating ctl pin kept
 //   - marker-block (CLAUDE core, dprint, .gitignore) -> replace the shared block, keep the rest
+//   - publish-docs-site.yml                          -> verbatim; CREATED where the repo has a
+//                                                       docs site and is not a turnkey
 // Structural per-repo files (root tsconfig.json, deployment/build-image.sh,
 // manifest.seed.json) have NO canonical bytes to apply — the gate checks their
 // shape, not their content — so they are left untouched.
@@ -30,6 +32,7 @@ import {
   CTL_VERSION_LINE,
   carriesIntegrationMarker,
   DOCS_SITE_DIR,
+  DOCS_SITE_WORKFLOW,
   END,
   GITIGNORE_BEGIN,
   GITIGNORE_END,
@@ -40,6 +43,7 @@ import {
   type ProductShape,
   PUBLISH_IMAGE_LINE,
   RUNNER_LINE,
+  resolveRepoName,
   resolveShape,
   splitAtMarkers,
 } from "./check-drift.ts";
@@ -49,6 +53,13 @@ export interface SyncReport {
   skipped: string[];
 }
 
+export interface SyncDriftOptions {
+  /** The GitHub repo name (`norsk-ctl-product-probe`), which decides whether the
+   *  docs site's publish may be CREATED here (never in a turnkey). The CLI
+   *  resolves it; a fixture passes it. Unknown ⇒ nothing is created. */
+  repoName?: string;
+}
+
 function writeIfChanged(path: string, content: string, rel: string, written: string[]): void {
   const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
   if (current !== content) {
@@ -267,6 +278,39 @@ function syncWithDisplay(repoRoot: string, canonical: string, r: SyncReport): vo
   chmodSync(path, 0o755);
 }
 
+// publish-docs-site.yml: the docs SITE's publish. Verbatim (the project name is
+// a repo variable, the credentials are secrets), so an existing copy is always
+// re-derived whole -- the gate, not this writer, judges whether the repo may
+// carry one. It is CREATED only where the gate would accept it: a repo with a
+// site (there is something to publish), named, and not a turnkey (a turnkey has
+// no public site, ADR-0012). That is how a product that grows a site acquires
+// its publish: the next sync-dev-kit run installs it, green until the Pages
+// project exists. A name this writer cannot determine creates nothing, since
+// the gate could only refuse the result.
+const TURNKEY_REPO = /^norsk-ctl-turnkey-/;
+
+function syncPublishDocsSite(repoRoot: string, canonical: string, repoName: string | undefined, r: SyncReport): void {
+  const path = join(repoRoot, DOCS_SITE_WORKFLOW);
+  if (existsSync(path)) {
+    writeIfChanged(path, canonical, DOCS_SITE_WORKFLOW, r.written);
+    return;
+  }
+  if (!hasDocsSite(repoRoot)) {
+    r.skipped.push(`${DOCS_SITE_WORKFLOW} (no docs site to publish)`);
+    return;
+  }
+  if (repoName === undefined) {
+    r.skipped.push(`${DOCS_SITE_WORKFLOW} (cannot tell which repo this is; a turnkey may not carry it)`);
+    return;
+  }
+  if (TURNKEY_REPO.test(repoName)) {
+    r.skipped.push(`${DOCS_SITE_WORKFLOW} (${repoName} is a turnkey: no public site)`);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeIfChanged(path, canonical, DOCS_SITE_WORKFLOW, r.written);
+}
+
 // The docs site's theme copies — the writer behind check-drift's docsThemeProblems.
 // Only for a repo that HAS a site: sync never creates one (a site is a nested
 // standalone package with its own install, not a file this writer can conjure),
@@ -286,7 +330,12 @@ function syncDocsTheme(repoRoot: string, r: SyncReport): void {
   for (const rel of adrift) r.written.push(`${DOCS_SITE_DIR}/${rel}`);
 }
 
-export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: ProductShape = "studio"): SyncReport {
+export function syncDrift(
+  repoRoot: string,
+  canonical: CanonicalBytes,
+  shape: ProductShape = "studio",
+  opts: SyncDriftOptions = {},
+): SyncReport {
   const r: SyncReport = { written: [], skipped: [] };
   // Shape-selected canonicals: an sdk-app's flake + checks are its own variants
   // (the gate holds it to those). Everything else is shared across shapes.
@@ -349,6 +398,7 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: Pr
   syncDemoShim(repoRoot, canonical.demoShim, r);
   syncWithDisplay(repoRoot, canonical.withDisplay, r);
   syncDocsTheme(repoRoot, r);
+  syncPublishDocsSite(repoRoot, canonical.publishDocsSite, opts.repoName, r);
 
   return r;
 }
@@ -366,6 +416,7 @@ if (import.meta.main) {
     botPrs: readFileSync(join(dir, "bot-prs.yml"), "utf8"),
     publishDocs: readFileSync(join(dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(dir, "build-docs.yml"), "utf8"),
+    publishDocsSite: readFileSync(join(dir, "publish-docs-site.yml"), "utf8"),
     withDisplay: readFileSync(join(dir, "..", "doc-guide", "with-display.sh"), "utf8"),
     checks: readFileSync(join(dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(dir, "biome.base.json"), "utf8"),
@@ -381,7 +432,7 @@ if (import.meta.main) {
     checksSdkApp: readFileSync(join(dir, "checks.sdk-app.yml"), "utf8"),
     upgradeLatestSdkApp: readFileSync(join(dir, "upgrade-latest.sdk-app.yml"), "utf8"),
   };
-  const report = syncDrift(repoRoot, canonical, resolveShape(repoRoot));
+  const report = syncDrift(repoRoot, canonical, resolveShape(repoRoot), { repoName: resolveRepoName(repoRoot) });
   if (report.written.length === 0) {
     console.log("sync-drift: all shared-convention copies already match @norskvideo/ctl-dev-kit.");
   } else {

package/create-product/docs-site.ts

@@ -307,10 +307,17 @@ ${SITE_DIR}/dist-public/
 ${SITE_DIR}/.astro/
 `;
 
+/** Before either build: a placeholder page for every recorded guide the
+ *  site symlinks from docs/generated whose capture has not run (dev-kit
+ *  docs/guide-stubs.ts), so the site builds on a checkout with no captures --
+ *  as ctl's and the Manager's do. A site that declares no recorded guides is
+ *  a no-op. The publish workflow refuses to deploy a placeholder. */
+const STUB_GUIDES = `bun run node_modules/@norskvideo/ctl-dev-kit/docs/guide-stubs.ts stub ${SITE_DIR}/src/content/docs/guides`;
+
 /** The root package.json scripts that drive it. Named the same in every repo
  *  that has a site, including the two in the norsk-ctl monorepo. */
 export const DOCS_SITE_SCRIPTS: Record<string, string> = {
   "docs:dev": `bun run --cwd ${SITE_DIR} dev`,
-  "docs:site": `bun run --cwd ${SITE_DIR} build`,
-  "docs:site:public": `ASTRO_BUILD=public bun run --cwd ${SITE_DIR} build`,
+  "docs:site": `${STUB_GUIDES} && bun run --cwd ${SITE_DIR} build`,
+  "docs:site:public": `${STUB_GUIDES} && ASTRO_BUILD=public bun run --cwd ${SITE_DIR} build`,
 };

package/create-product/turnkey.ts

@@ -302,8 +302,9 @@ function rootPackageJson(ctx: ShapeContext): string {
         "test:unit": `bun test shared/src/ backend/src/ ${hasComponents ? "components/src/ " : ""}tests/unit/`,
         "test:image": "bun test tests/image/",
         "check:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/check-drift.ts",
-        "docs:check": "bun run node_modules/@norskvideo/ctl-dev-kit/docs/path-existence.ts",
-        "docs:manual": `bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js --brand "${ctx.name}" --title "${ctx.name} — Documentation" --link "norsk.video=https://norsk.video/" --out docs/generated/bundle docs/handover.md docs/known-limitations.md`,
+        "docs:check":
+          "bun run node_modules/@norskvideo/ctl-dev-kit/docs/path-existence.ts && bun run node_modules/@norskvideo/ctl-dev-kit/docs/light-pages.ts && bun run node_modules/@norskvideo/ctl-dev-kit/docs/journeys.ts",
+        "docs:manual": `bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js --brand "${ctx.name}" --title "${ctx.name} — Documentation" --link "norsk.video=https://norsk.video/" --out docs/generated/bundle docs/handover.md docs/operating.md docs/known-limitations.md`,
         "docs:handover": "bash scripts/docs-handover.sh",
         "docs:handover:check": "bash scripts/docs-handover.sh --check",
         // The docs SITE (website/) — a standalone package, so its install is its
@@ -1896,8 +1897,8 @@ function exampleInputJson(_ctx: ShapeContext): string {
 
 // ---- The canonical doc set (fleet review 02 s9, backend-only turnkey) ------
 // README (developer), docs/README (the index), docs/handover (the customer's
-// deployment document: prose around a block norsk-ctl generates), docs/known-
-// limitations (operator). Prose only: a turnkey's bundle is built from these
+// deployment document: prose around a block norsk-ctl generates), docs/operating
+// and docs/known-limitations (operator). Prose only: a turnkey's bundle is built from these
 // files by docs:manual, which the image build runs, so the image serves them.
 // Bundle-internal file names are written without backticks on purpose: the
 // path-existence lint would look for them in the repo.
@@ -1961,7 +1962,8 @@ norsk-ctl and the pinned Norsk SDK:
 Two channels, deliberately:
 
 - **The bundle the image serves.** \`bun run docs:manual\` builds it from
-  \`docs/handover.md\` and \`docs/known-limitations.md\`; the image build runs
+  \`docs/handover.md\`, \`docs/operating.md\` and \`docs/known-limitations.md\`;
+  the image build runs
   it, so every image serves them at /docs at the version that is running
   (linked from the product's page in norsk-ctl). \`bun run docs:handover\`
   regenerates the handover's generated block from a daemon that has this
@@ -1985,7 +1987,8 @@ served at /docs at the version that is running.
 
 | Document                     | Audience                                  | What it is                                                                                          |
 | ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| \`docs/handover.md\`          | the platform team deploying this product  | Deploying from the exported bundle without norsk-ctl: every mount, environment and injected setting |
+| \`docs/handover.md\`          | whoever gets this product running         | How norsk-ctl arrives, the one command that adds this product, and the bundle route for platform teams |
+| \`docs/operating.md\`         | operators                                 | What a running deployment looks like from the operator's chair: the controls, the checks, the signs |
 | \`docs/known-limitations.md\` | operators                                 | What the product does not do yet, with the consequence and the workaround                          |
 
 The **docs site** is a separate channel and lives in \`website/\`: the public
@@ -1995,18 +1998,84 @@ manual, on the shared Norsk theme, not built from these files. See
 \`bun run docs:manual\` builds the bundle from these files. The tables in the
 handover are generated by norsk-ctl (\`bun run docs:handover\`) — regenerate
 them, never edit them.
+
+\`docs/personas.md\` is for writers, not readers, and is not in the bundle: it
+maps this product's audiences onto the four shared personas and carries the
+journey table \`bun run docs:check\` verifies.
+`;
+}
+
+// The per-product persona mapping and the journey table the journeys lint
+// reads (conventions/personas.md). The routes name the pages the skeleton
+// ships; a product rewrites them as its pages arrive, and docs:check keeps
+// every named page real.
+function personasMd(ctx: ShapeContext): string {
+  return `# Who ${ctx.name}'s documentation is for
+
+The four personas are shared across every Norsk product and described in
+\`node_modules/@norskvideo/ctl-dev-kit/conventions/personas.md\`. This page maps
+${ctx.name}'s own audiences onto them and says where each reader goes.
+
+## The mapping
+
+<!-- ctl-docs-template: fill me -->
+_Name this product's audiences (the people who set it up, run it, and are
+invited into it) and say which of the four personas each one is. Runtime
+actors are not personas: an operator at the console is the Builder wearing
+the Administrator's hat._
+
+## The journey table
+
+| Persona       | Starts at           | Then, in order                          | Hands off to                                                            |
+| ------------- | ------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
+| Evaluator     | \`/docs/\`           | \`/docs/guides/\`                        | [norsk-ctl's manual](https://ctl.norsk.video/), to run it for real      |
+| Builder       | \`/docs/guides/\`    | \`/docs/how-to/\`                        | \`/docs/reference/\`, for the settings they just used                    |
+| Integrator    | \`/docs/reference/\` | \`/docs/concepts/\`                      | [norsk-ctl's CLI and API reference](https://ctl.norsk.video/)           |
+| Administrator | \`handover.md\`      | \`operating.md\`, \`known-limitations.md\` | [norsk-ctl's manual](https://ctl.norsk.video/), for everything about the machine |
+
+Site paths resolve under website/src/content/docs; a bare name resolves under
+docs/. Each route is at most five pages and ends in a hand-off, which is the
+one place "see norsk-ctl for details" lives.
 `;
 }
 
 function handoverMd(ctx: ShapeContext): string {
-  return `# Deploying ${ctx.name} without norsk-ctl
+  return `# Deploying ${ctx.name}
+
+How ${ctx.name} reaches you and how to get it running. Nearly every deployment
+goes through norsk-ctl, and that is the first two sections. The rest of this
+page is for a platform team running the exported bundle in its own
+orchestration instead.
+
+## How norsk-ctl arrives
+
+\`\`\`sh
+curl -fsSL https://norsk.video/install/ctl | bash
+\`\`\`
+
+When it finishes, norsk-ctl is running on the machine and its web page is where
+products are added, launched and watched. Everything about the machine itself
+is in [norsk-ctl's manual](https://ctl.norsk.video/): ports, TLS, cloud hosts,
+a box behind another proxy.
+
+## Add this product
+
+\`\`\`sh
+norsk-ctl product add --image <the image you were given> --license-file <file>
+\`\`\`
+
+One command. ${ctx.name} then appears on norsk-ctl's page, ready to launch;
+operating.md says what to do with it once it is running.
+
+## Deploying without norsk-ctl
 
-What the platform team receives, and how to run it. The tables in the
-generated block below come from norsk-ctl's own rendering of this product's
-default template (\`bun run docs:handover\`), so they are the launch truth of
-the version this document ships with. Regenerate them; never edit them.
+Some platform teams run the product from a bundle norsk-ctl exports, inside
+their own orchestration. The tables in the generated block below come from
+norsk-ctl's own rendering of this product's default template
+(\`bun run docs:handover\`), so they are the launch truth of the version this
+document ships with. Regenerate them; never edit them.
 
-## What you receive
+### What you receive
 
 A portable bundle exported by norsk-ctl: compose.yml (the flat compose, every
 path relative), HANDOVER.md (the same tables as below), the working-directory
@@ -2017,13 +2086,13 @@ placeholder to replace with a production licence before the first start.
 _Not generated yet. Run \`bun run docs:handover\` against a daemon that has this product added._
 <!-- END generated -->
 
-## Verifying a deployment
+### Verifying a deployment
 
 - The control plane answers on its port: GET /healthz returns ok.
 - The media engine is licensed: its log names the licence's product entry, not a placeholder.
 - The default template's outputs are reachable from where the audience is.
 
-## Not in this artefact
+### Not in this artefact
 
 Anything norsk-ctl-specific: the daemon, product registration, the instance
 proxy and its authentication, templates-as-storage. The bundle is the launch
@@ -2031,6 +2100,42 @@ truth of one product template and needs none of them.
 `;
 }
 
+// The operator's page, in the shape of the plan's exemplar (reuters'
+// operating.md). Each section opens with a marker so a half-filled page is
+// grep-able, and the fill-me lines say what the exemplar put there.
+function operatingMd(ctx: ShapeContext): string {
+  return `# Operating ${ctx.name}
+
+What an operator does with a running ${ctx.name}, and where. For getting one
+running, see handover.md; this page assumes it is up.
+
+## What it is
+
+<!-- ctl-docs-template: fill me -->
+_One paragraph: what the deployment takes in, what it puts out, and the one
+thing an operator adjusts while it runs._
+
+## Where the controls are
+
+<!-- ctl-docs-template: fill me -->
+_Which screen the operator works in, and what the product's own page at /docs
+and its health check at /healthz are for._
+
+## Checking it is doing its job
+
+<!-- ctl-docs-template: fill me -->
+1. _The health check answers._
+2. _Each input is arriving. A listening input with nothing connected is idle, not failed; the sender is the thing to check._
+3. _Each output is connected to its destination._
+
+## When something looks wrong
+
+<!-- ctl-docs-template: fill me -->
+- _The picture is absent: which input or output to look at first._
+- _The picture is wrong rather than absent: what is a runtime control and what needs a rebuilt template._
+`;
+}
+
 const KNOWN_LIMITATIONS_MD = `# Known limitations
 
 What this product does not do yet, or does with a caveat an operator must know
@@ -2105,7 +2210,9 @@ export const turnkey: ShapeModule = {
       ...docsSiteFiles(ctx),
       { path: "docs/README.md", content: docsReadmeMd(ctx) },
       { path: "docs/handover.md", content: handoverMd(ctx) },
+      { path: "docs/operating.md", content: operatingMd(ctx) },
       { path: "docs/known-limitations.md", content: KNOWN_LIMITATIONS_MD },
+      { path: "docs/personas.md", content: personasMd(ctx) },
       { path: ".github/workflows/build-docs.yml", content: ctx.canon.buildDocs },
       { path: "scripts/doc-guide/regen-manual.sh", content: REGEN_MANUAL_SH, executable: true },
       { path: "scripts/with-display.sh", content: ctx.canon.withDisplay, executable: true },

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

@@ -24,6 +24,21 @@ export interface UiFixture {
  *  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 declare function docsRoot(): string;
+/** 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 declare const DEFAULT_CAPTION_WORDS = 50;
+/** 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 declare function captionFault(text: string, budget: number): string | 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 declare function captureScaleFactor(): number;
 /** 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.
@@ -40,6 +55,9 @@ export interface CaptureTreatment {
     /** How long `livePicture` may take to arrive. Default 60s: a WebTransport
      *  session plus a catalog plus a keyframe, on a cold encoder. */
     livePictureTimeoutMs?: number;
+    /** The rest of the live-picture gate: the product's own slate markers, the
+     *  motion thresholds. `livePictureTimeoutMs` is the shorthand for its timeout. */
+    livePictureGate?: LivePictureGate;
 }
 /** The attributes Studio's shared MoQ player (norsk-studio-built-ins
  *  `lib/shared/moq-player`) stamps on the container it mounts into. `live`
@@ -49,19 +67,83 @@ export interface CaptureTreatment {
 export declare const MOQ_PHASE_ATTR = "data-moq-phase";
 export declare const MOQ_ERROR_ATTR = "data-moq-error";
 export type MoqPhase = "connecting" | "live" | "error";
+/** 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 declare const DEFAULT_OCCLUDER_SELECTORS: readonly string[];
+export declare const DEFAULT_OCCLUDER_TEXT: RegExp;
+export interface LivePictureGate extends LivePictureMotion {
+    /** Default 60s: a WebTransport session plus a catalog plus a keyframe, on a cold encoder. */
+    timeoutMs?: number;
+    /** Selectors that mark a slate or modal when visible inside the tile. Default DEFAULT_OCCLUDER_SELECTORS. */
+    occluderSelectors?: readonly string[];
+    /** Visible text inside the tile that marks a slate; null disables. Default DEFAULT_OCCLUDER_TEXT. */
+    occluderText?: RegExp | null;
+    /** Gap between the two frame samples the motion check compares. Default 500ms. */
+    frameGapMs?: number;
+}
+/** What the browser reports about a tile, for `judgeLivePicture` to rule on.
+ *  Gathering is a browser matter; the ruling is pure, so each check and its
+ *  wording are pinned without a launch. */
+export interface LivePictureEvidence {
+    /** `data-moq-phase` on the tile; null when nothing stamped it. */
+    phase: string | null;
+    /** `data-moq-error`, when the player reported one. */
+    error: string | null;
+    /** What `elementFromPoint` found at the tile's centre when it was neither
+     *  the tile nor inside it (as `tag#id.class`); null when the tile is on top. */
+    coveredBy: string | null;
+    /** Slate or modal matches visible inside the tile: the selector that hit,
+     *  or `text "..."` for the text pattern. Empty when none. */
+    occluders: string[];
+    /** Two luma samples of the tile's drawable (video or canvas), downsampled to
+     *  FRAME_SAMPLE_W x FRAME_SAMPLE_H and taken `frameGapMs` apart; null when
+     *  the tile has nothing to draw. */
+    frames: [number[], number[]] | null;
+    frameGapMs: number;
+}
+export type LivePictureCheck = "phase" | "covered" | "occluded" | "frozen" | "undrawable";
+/** What counts as motion between the two samples. A slate is still; a live
+ *  picture moves somewhere. Per-pixel on 0..255 luma, after the downsample
+ *  has averaged out decoder noise. */
+export interface LivePictureMotion {
+    /** A sampled pixel has moved when its luma changed by more than this. Default 6. */
+    pixelDelta?: number;
+    /** The fraction of sampled pixels that must have moved. Default 0.02. */
+    minChangedFraction?: number;
+}
+export declare const FRAME_SAMPLE_W = 32;
+export declare const FRAME_SAMPLE_H = 18;
+export type LivePictureVerdict = {
+    live: true;
+} | {
+    live: false;
+    check: LivePictureCheck;
+    reason: string;
+};
+/** Rule on whether the tile is showing a live picture, naming the first
+ *  check that says it is not. */
+export declare function judgeLivePicture(evidence: LivePictureEvidence, motion?: LivePictureMotion): LivePictureVerdict;
 /** 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 declare function livePictureFailure(selector: string, phase: string | null, error: string | null, timeoutMs: number): string;
-/** 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 declare function awaitLivePicture(page: Page, selector: string, opts?: {
-    timeoutMs?: number;
-}): Promise<void>;
+/** The failure for whichever check the tile never passed. The phase check
+ *  keeps its original wording; the composite checks name themselves. */
+export declare function livePictureGateFailure(selector: string, verdict: Exclude<LivePictureVerdict, {
+    live: true;
+}>, timeoutMs: number): string;
+/** 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 declare function awaitLivePicture(page: Page, selector: string, opts?: LivePictureGate): Promise<void>;
 /** How long a capture waits for web fonts before shooting anyway. */
 export declare const FONTS_READY_TIMEOUT_MS = 10000;
 /** `document.fonts.ready`, bounded. True when the fonts settled in time.
@@ -82,15 +164,28 @@ export declare function screenshotFor(page: Page, treat?: CaptureTreatment): Pro
 /** Pure markdown assembly — exposed so a render step can re-emit markdown from a
  * stored entries.json without re-running the browser. */
 export declare function renderUiMarkdown(title: string, entries: UiEntry[]): string;
+export interface DocGuideOptions {
+    /** Spoken-word budget for one step (heading + description) or text() block.
+     *  Default: NORSK_DOCS_CAPTION_WORDS (which guidesConfig exports), else 50. */
+    captionWords?: number;
+}
+/** 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 declare function captionBudget(option?: number): number;
 export declare class DocGuide {
     private slug;
     private title;
+    private options;
     private entries;
     private captureIndex;
-    constructor(slug: string, title: string);
+    constructor(slug: string, title: string, options?: DocGuideOptions);
     section(heading: string): void;
     step(heading: string, description?: string): void;
     text(prose: string): void;
+    /** 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. */
+    private lintCaption;
     /** 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. */
     capture(page: Page, caption: string, treat?: CaptureTreatment): Promise<void>;