@norskvideo/ctl-dev-kit 0.2.54 → 0.2.55

package/conventions/check-drift.ts

@@ -3,7 +3,8 @@
 // gated file uses the loosest mechanism that still pins what is shared:
 //   - byte-verbatim: CLAUDE.md fenced core, nix/ctl-shell.nix, biome.json,
 //     tsconfig.base.json, the .gitignore core block, scripts/demo (only a
-//     product with tests/demo.spec.ts is asked for it)
+//     product with tests/demo.spec.ts is asked for it), publish-docs-site.yml
+//     (only a repo with a docs site may carry it, and never a turnkey)
 //   - masked per-repo line: checks.yml + upgrade-latest.yml (`product:` key)
 //   - base + sanctioned extension block: dprint.json (repo-specific excludes)
 //   - must import the shared module: flake.nix (otherwise the product's own)
@@ -272,6 +273,10 @@ export interface CanonicalBytes {
   publishDocs: string;
   /** conventions/build-docs.yml — the embedded docs variant (bundle -> image, no upload). */
   buildDocs: string;
+  /** conventions/publish-docs-site.yml — the docs SITE's publish (website/ ->
+   *  Cloudflare Pages on every push to main). Verbatim; allowed only where
+   *  there is a site to publish and never in a turnkey. */
+  publishDocsSite: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -506,6 +511,10 @@ export function resolveRepoName(repoRoot: string, env: NodeJS.ProcessEnv = proce
 }
 
 const PUBLIC_DOCS_REPO = /^norsk-ctl-product-/;
+const TURNKEY_REPO = /^norsk-ctl-turnkey-/;
+
+/** The docs site's publish workflow, where a repo carries one. */
+export const DOCS_SITE_WORKFLOW = ".github/workflows/publish-docs-site.yml";
 
 /** ADR-0012: exposure is declared by which docs workflow a repo carries, so the
  *  gate is what makes that declaration safe — exactly one variant; the public
@@ -530,6 +539,37 @@ export function docsExposureProblems(hasPublish: boolean, hasBuild: boolean, rep
   return problems;
 }
 
+/** Where a PUBLIC docs site may exist. The rule is negative on the repo name
+ *  where publish-docs.yml's is positive, because sites live outside
+ *  norsk-ctl-product-* (norsk-relay has one, and so do norsk-ctl and the
+ *  Manager); what is certain is that a turnkey has none -- its documentation
+ *  reaches one customer, inside the image they run (ADR-0012). And a site has
+ *  to exist to be published: a repo without website/astro.config.mjs carrying
+ *  the workflow would deploy nothing, or whatever a stale dist held. */
+export function docsSiteExposureProblems(
+  hasWorkflow: boolean,
+  hasSite: boolean,
+  repoName: string | undefined,
+): string[] {
+  if (!hasWorkflow) return [];
+  const problems: string[] = [];
+  if (!hasSite) {
+    problems.push(
+      `${DOCS_SITE_WORKFLOW} publishes a docs site, but this repo has none (no ${DOCS_SITE_DIR}/astro.config.mjs). Add the site (conventions/docs-site.md) or delete the workflow.`,
+    );
+  }
+  if (repoName === undefined) {
+    problems.push(
+      `${DOCS_SITE_WORKFLOW} publishes this repo's docs site publicly, and the gate cannot tell which repo this is (no GITHUB_REPOSITORY, no origin remote). A turnkey (norsk-ctl-turnkey-*) may not carry it.`,
+    );
+  } else if (TURNKEY_REPO.test(repoName)) {
+    problems.push(
+      `${DOCS_SITE_WORKFLOW} publishes a public docs site, but this repo is ${repoName}, a turnkey. A turnkey has no public site: its documentation reaches one customer, inside the image they run (ADR-0012). Delete the workflow.`,
+    );
+  }
+  return problems;
+}
+
 export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: CheckDriftOptions = {}): DriftReport {
   const problems: string[] = [];
   const push = (problem: string | undefined) => {
@@ -808,6 +848,20 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   // checked, and one clause covers both.
   for (const p of docsThemeProblems(repoRoot, opts.themeCanonical)) push(p);
 
+  // publish-docs-site.yml: the site's publish, verbatim (no per-repo line: the
+  // project name is a repo variable, the credentials are secrets), and only
+  // where docsSiteExposureProblems allows a public site at all.
+  const siteWorkflowPath = join(repoRoot, DOCS_SITE_WORKFLOW);
+  if (existsSync(siteWorkflowPath)) {
+    const actual = readFileSync(siteWorkflowPath, "utf8");
+    if (actual !== canonical.publishDocsSite) {
+      push(
+        `${DOCS_SITE_WORKFLOW} has drifted from @norskvideo/ctl-dev-kit conventions/publish-docs-site.yml (${firstDiffLine(actual, canonical.publishDocsSite)}). ${RESYNC}`,
+      );
+    }
+  }
+  for (const p of docsSiteExposureProblems(existsSync(siteWorkflowPath), hasDocsSite(repoRoot), opts.repoName)) push(p);
+
   for (const p of demoProblems(repoRoot, canonical.demoShim)) push(p);
   for (const p of productLogsProblems(repoRoot)) push(p);
   for (const p of ctlPinProblems(repoRoot)) push(p);
@@ -827,6 +881,7 @@ if (import.meta.main) {
     botPrs: readFileSync(join(import.meta.dir, "bot-prs.yml"), "utf8"),
     publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
     buildDocs: readFileSync(join(import.meta.dir, "build-docs.yml"), "utf8"),
+    publishDocsSite: readFileSync(join(import.meta.dir, "publish-docs-site.yml"), "utf8"),
     withDisplay: readFileSync(join(import.meta.dir, "..", "doc-guide", "with-display.sh"), "utf8"),
     checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(import.meta.dir, "biome.base.json"), "utf8"),

package/conventions/docs-site.md

@@ -8,7 +8,7 @@ Like [`docs.md`](./docs.md) and [`personas.md`](./personas.md) this is a **shipp
 reference**, not a drift-gated copy: read it from
 `node_modules/@norskvideo/ctl-dev-kit/conventions/docs-site.md`. What IS gated is
 the theme itself — see "The theme is a copy, and the gate is what makes that
-safe" below.
+safe" below — and the publish workflow, see "Publishing".
 
 **`create-product` renders all of it.** A repo generated by
 `bunx @norskvideo/ctl-dev-kit create-product` comes out with a `website/` that
@@ -78,10 +78,24 @@ each section serves, in the vocabulary of [`personas.md`](./personas.md):
 
 - **Start here** — the Evaluator. What this does, and where to go next.
 - **Guides** — the Builder. One task, start to finish, in the order it is done.
-  These are the pages worth **capturing** rather than illustrating; see
-  [`docs.md`](./docs.md) for the toolchain and the `capturedAgainst` front matter
-  the theme renders at the foot of such a page.
+  **A Guides page is the recorded chapter where one exists**: a symlink from
+  `website/src/content/docs/guides/<slug>` into the `docs/generated/<slug>`
+  tree a doc-guide writes, with at most a prose introduction above it. That
+  is what the Manager's site does for every guide and what makes the page
+  unable to describe a screen that does not exist; see [`docs.md`](./docs.md)
+  for the toolchain, the `capturedAgainst` front matter the theme renders at
+  the foot of such a page, and the placeholder the dev-kit writes so the site
+  builds on a checkout with no captures. **When a product has more than one
+  surface** (a console and an API, or a CLI as well), show the same task on
+  each: `<task>`, `<task>-ui`, `<task>-api`, grouped under the task in the
+  sidebar, as the Manager does for launching a show format, draining a node
+  and API tokens. Not every task needs every surface; the first task on the
+  Builder's route should have them all.
 - **How-to** — the Administrator. Looked up, repeatedly, while running it.
+  Its first page, **"What this product adds to the host"** (images, ports,
+  volumes, GPU, state), is generated from the manifest and the product
+  template, where those facts already live, and never hand-written; the
+  rest of the section ends with a link into norsk-ctl's manual.
 - **Concepts** — the vocabulary the rest of the manual uses. Not architecture.
 - **Reference** — the Integrator. Exhaustive and generated from the source of
   truth where possible.
@@ -89,6 +103,16 @@ each section serves, in the vocabulary of [`personas.md`](./personas.md):
 Add sections below these if a product genuinely needs them. Do not rename or
 reorder these five: the shape is the shared part.
 
+**Start here and Guides are the light half**, written for readers who do not
+know our engineering vocabulary: one command per step, no flags, the result
+before the prerequisites, a single "Next" link at the foot of each page, and a
+word budget. `docs/light-pages.ts` lints those pages (see `docs.md`, "Voice").
+How-to and Reference may be as exhaustive as the Administrator and the
+Integrator want. The install section of Start here is the theme's
+`components/InstallProduct.astro`: the product's one-line install, one sentence
+on what it leaves behind, and one link into norsk-ctl's manual. It is repeated
+on every product site on purpose and generated so the wording cannot drift.
+
 ## The theme is a copy, and the gate is what makes that safe
 
 The theme reaches a site as **files copied into it**, not as an import, and
@@ -138,6 +162,27 @@ Astro derives a component's scoped-style class from its path, so moving
 Then `bun install --cwd website` (the repo-root install does NOT cover a
 standalone package) and `bun run docs:site`.
 
+### Adding a recorded guide
+
+Two lines. A symlink from the site's Guides into the tree the doc-guide
+writes, and a sidebar entry:
+
+```sh
+ln -s ../../../../../docs/generated/<slug> website/src/content/docs/guides/<slug>
+```
+
+```js
+{ label: "<Title>", slug: "guides/<slug>" }
+```
+
+`docs:site` runs the dev-kit's `docs/guide-stubs.ts stub` first, so the site
+builds on a checkout that has never captured; `publish-docs-site.yml` runs
+`guide-stubs.ts check` after the build and refuses to deploy while any guide
+is still a placeholder. That refusal is deliberate: a product that declares
+recorded guides must also restore (or regenerate) its captures in that
+workflow before the build, and until it does, the publish stops rather than
+shipping an empty page.
+
 ## The two builds
 
 One content collection, two outputs, selected by `ASTRO_BUILD`:
@@ -159,22 +204,56 @@ of compressed docs on a ~68 MB binary.
 
 ## Publishing
 
-Per site, and none of it is needed to build or review one locally:
+The site publishes from **`.github/workflows/publish-docs-site.yml`**,
+single-sourced in this package (`conventions/publish-docs-site.yml`) and
+**drift-gated** the way the bundle's `publish-docs.yml` is: `bun run check:drift`
+holds the copy byte-identical, and `bun run sync:drift` writes it — creating it
+where the repo has a site and is not a turnkey. On every push to `main` (and on
+demand) it installs `website/`, builds the public variant and deploys
+`website/dist-public` to Cloudflare Pages with `wrangler`. It never cancels a
+run in flight, because a cancelled deploy is a half-published site. It restores
+no capture cache: a product site builds from the committed prose, so there is
+nothing a nightly run would have that a push does not.
+
+Where it may exist is the gate's business (ADR-0012, and the documentation
+plan): a repo with `website/astro.config.mjs` may carry it; a repo without a
+site may not, since there is nothing to publish; a turnkey
+(`norsk-ctl-turnkey-*`) may not, since a turnkey has no public site. The rule
+is negative on the repo name where `publish-docs.yml`'s is positive, because
+sites exist outside `norsk-ctl-product-*` — Relay has one.
+
+What the repo needs, per site, and none of it to build or review one locally:
 
 1. **A Cloudflare Pages project**, e.g. `norsk-acme-docs`.
 2. **A custom domain** on it — `<product>.norsk.video` — and the DNS record.
-3. **API token scope.** The existing `CLOUDFLARE_API_TOKEN` is deliberately narrow
-   (Pages:Edit). It must cover the new project: widen it to all Pages projects in
-   the account, or issue a second token.
-4. **A publish step** that runs the public build and `wrangler pages deploy`. Take
-   the project name from a repo variable rather than a literal, and skip the
-   deploy with a message when it is unset — so main is green before Cloudflare
-   exists and publishes the day the variable is set.
-
-There is no shared `publish-docs-site.yml` in this package yet: the two existing
-sites publish from norsk-ctl's own monorepo workflow. The first product repo to
-publish one should bring the workflow back here and drift-gate it, the way
-`publish-docs.yml` (the bundle's) already is.
+3. **Two repo secrets.** `CLOUDFLARE_API_TOKEN`, a Pages:Edit token — the
+   existing one is deliberately narrow and must cover the new project: widen it
+   to all Pages projects in the account, or issue a second token — and
+   `CLOUDFLARE_ACCOUNT_ID`. The workflow verifies the token at the API (both the
+   user-owned and the account-owned endpoint), never with `wrangler whoami`,
+   which a Pages:Edit token cannot answer.
+4. **One repo variable.** `NORSK_DOCS_SITE_PROJECT`, the project name from
+   step 1. It has **no default**: unset, the workflow still builds the site,
+   prints exactly these steps and exits 0 — so `main` is green before
+   Cloudflare exists and publishes the day the variable is set, with no change
+   to the workflow.
+
+A `workflow_dispatch` from a branch other than `main` deploys a **preview** of
+that branch (`--branch` is the ref that ran), never over production.
+
+### Wiring it into a repo that has a site
+
+Two steps, once a dev-kit carrying the workflow is published:
+
+```
+bun update @norskvideo/ctl-dev-kit   # bump the pin (or let sync-dev-kit.yml do it)
+bun run sync:drift                   # writes .github/workflows/publish-docs-site.yml
+```
+
+Commit the result; `bun run check:drift` passes. The nightly `sync-dev-kit.yml`
+does both hands-free, so a product with a site acquires the workflow on its
+next sync without anyone touching the repo. Then create the Pages project, set
+the two secrets and the variable, and the next push to `main` publishes.
 
 ## Search does not cross products
 

package/conventions/docs.md

@@ -52,6 +52,14 @@ 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.
+  **Scoped and checked (October 2026):** the rule applies to the light half of
+  a manual, which is a site's Start here pages (`index`, `quickstart`) and its
+  `guides/`, plus a repo's `docs/quickstart.md`. `docs/light-pages.ts` in this
+  package lints exactly those pages for the deny list and a word budget, skipping
+  code, comments and imports, and runs from `bun run docs:check`. A repo whose
+  own vocabulary is on the list allows the word (`--allow`); `instance` is not
+  on it, because it is the label on norsk-ctl's own screens. How-to and
+  Reference may use any of it.
 - **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."
@@ -89,11 +97,44 @@ Per-step treatments (`CaptureTreatment`, from the doc-guide library):
   `live` on the first decoded frame, or `error` with the reason in
   `data-moq-error`. The player mounts at the moment the source connects, which
   is also when a guide's "it's running" assertion passes — so a capture taken
-  then is of a spinner, and a sleep only hides a preview that is broken. Name
-  the tile here, or call `awaitLivePicture(page, selector)` before the capture
-  (the verify run skips captures, so an explicit wait is also the assertion);
-  either way a tile that never shows a picture fails the guide, naming the
-  phase it was stuck in and the player's own error.
+  then is of a spinner, and a sleep only hides a preview that is broken. The
+  phase alone is not enough, though: Commentary's standby slate and its "Enter
+  the booth" modal both passed it (2026-10-07), because the player underneath
+  was live. So the gate judges the visible composite as well: the element at
+  the tile's centre (`document.elementFromPoint`) must be the tile or inside
+  it, nothing matching the slate/modal selectors (`[data-slate]`,
+  `[role="dialog"]`, `.modal`, or visible text matching
+  `/temporarily unavailable|standby/i`) may be visible inside it, and two
+  32x18 luma samples of its video or canvas taken 500 ms apart must differ —
+  a slate, however bright, is still. Name the tile here, or call
+  `awaitLivePicture(page, selector, gate?)` before the capture (the verify run
+  skips captures, so an explicit wait is also the assertion); either way a
+  tile that never shows a picture fails the guide, naming the check it never
+  passed. Add a product's own slate markers with `livePictureGate.
+  occluderSelectors`. A tile with no video or canvas in it (an audio-only
+  player) cannot pass, so do not name one.
+
+**Captures are shot at 2x in a `DOCS_GENERATE` run.** `guidesConfig` defaults
+`deviceScaleFactor` from `captureScaleFactor()`: 2 when `DOCS_GENERATE=1`, 1
+otherwise, and `launchLiveBrowser` (the engine tier) reads the same default.
+The video spike measured the manual's component crops at 383 to 778 px wide;
+blown up to sit in a 1080p frame they were legible but soft, and no renderer
+step recovers detail that was never captured. A plain run of a guide writes no
+captures, so it stays at 1x and nothing else about it changes; pass
+`deviceScaleFactor` explicitly to pin either. Expect the PNGs to grow with the
+pixel count.
+
+### When a guide runs
+
+A fixture-tier guide costs seconds and needs no licence, so it runs in the
+**PR check** (`checks.yml`), where a broken capture is found by its author;
+the engine tier runs **nightly** in the docs workflow, where a licence and a
+real launch are affordable. A site is never hostage to a capture: on a
+checkout with no `docs/generated`, the dev-kit's `docs/guide-stubs.ts stub`
+writes a placeholder page for every guide the site's symlinks name, so
+`docs:site` builds, and `docs/guide-stubs.ts check` **refuses to publish** a
+placeholder, in every publish workflow the dev-kit ships. The placeholder
+sentence is the marker the gate matches on; do not write it by hand.
 
 ## The toolchain
 
@@ -103,6 +144,12 @@ 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.
+  Step text is also the video narration, so in a `DOCS_GENERATE` run `step()`
+  (heading plus description) and `text()` fail the guide over 50 spoken words,
+  on a raw URL (say "the address"), or on a slash between words (write "or" or
+  "and"); the failure names the guide, the step and the count. `captionWords`
+  on `guidesConfig` or on the `DocGuide` options tightens the budget. A plain
+  run is unchanged.
 - `@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).

package/conventions/personas.md

@@ -131,3 +131,28 @@ Reconcile them like this:
 Map each product's named audiences (from its `PRODUCT.md`) onto the four
 personas above; don't invent a parallel scheme. Keep the per-product mapping in
 the product's `docs/personas.md`.
+
+## The journey table
+
+A persona is who you write for; a journey is where they go. Each product's
+`docs/personas.md` carries one table, in this shape, and `docs/journeys.ts` in
+this package checks it from `bun run docs:check`: every persona has one row,
+every page it names exists, no route is longer than five pages, and every route
+ends in a hand-off.
+
+| Persona       | Starts at               | Then, in order                                        | Hands off to                                         |
+| ------------- | ----------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
+| Evaluator     | `/docs/`                | `/docs/quickstart/`, `/docs/guides/gallery/`          | Guides (build with it) or ctl (run it for real)      |
+| Builder       | `/docs/guides/first-…/` | the task pages, `/docs/guides/troubleshooting/`       | Reference, for the settings they just used           |
+| Integrator    | `/docs/reference/`      | config, CLI subtree, API, recipes                     | norsk-ctl's CLI and API reference                    |
+| Administrator | `/docs/how-to/`         | what this product adds to the host, known limitations | norsk-ctl's manual, for everything about the machine |
+
+The Integrator's route may start at a recorded API walkthrough (the `-api`
+variant of the Builder's first task) rather than at Reference; the Manager's
+"API tokens, HTTP API" is the pattern. Reference stays where it ends.
+
+Site paths are `/docs/...` (the embedded base; the public build strips it) and
+resolve to `website/src/content/docs`; a bare `name.md` resolves under `docs/`.
+The hand-off is where "see norsk-ctl for details" lives, once per route, so no
+page needs the caveat sprinkled through it. A repo with no site and no
+`docs/quickstart.md` (a backend-only turnkey) is not asked for the table.

package/conventions/publish-docs-site.yml

@@ -0,0 +1,247 @@
+# Publish this product's DOCS SITE -- the public manual at <product>.norsk.video
+# (website/, an Astro + Starlight site on the shared Norsk theme) -- to
+# Cloudflare Pages on every push to main.
+#
+# This is the SITE channel, not the bundle: publish-docs.yml / build-docs.yml
+# regenerate the illustrated manual the product image serves at /docs, nightly,
+# from a licensed Docker run. The site builds from the committed prose alone,
+# needs no licence and no Docker, and so rides every push (conventions/
+# docs-site.md, "Two documentation channels"). A site that also symlinks
+# RECORDED guides (website/src/content/docs/guides/<slug> -> docs/generated/<slug>)
+# builds against a placeholder when the capture is absent, and the gate below
+# refuses to deploy one.
+#
+# This workflow is SINGLE-SOURCED in @norskvideo/ctl-dev-kit
+# (conventions/publish-docs-site.yml) and copied verbatim: there is no per-repo
+# line. Everything per-site lives in the repo -- website/astro.config.mjs, the
+# root `docs:site:public` script -- or in the repo's settings:
+#
+#   variable NORSK_DOCS_SITE_PROJECT   the Cloudflare Pages project name.
+#                                      NO DEFAULT: unset means the project does
+#                                      not exist yet, and the deploy step says
+#                                      what to create and exits 0. So main is
+#                                      green before Cloudflare exists, and the
+#                                      site publishes the day the variable is
+#                                      set, with no change here.
+#   secret   CLOUDFLARE_API_TOKEN      a Pages:Edit token covering that project
+#   secret   CLOUDFLARE_ACCOUNT_ID     the account the project lives in
+#
+# The site is BUILT whether or not it will be deployed: if the build is only
+# exercised on the day the Pages project appears, that day is when we find out
+# it was broken.
+#
+# The drift gate (check-drift.ts) holds the copy byte-identical, allows it only
+# in a repo that has a site (website/astro.config.mjs), and refuses it in a
+# turnkey (norsk-ctl-turnkey-*): a turnkey has no public site, its documentation
+# reaches one customer inside the image they run (ADR-0012).
+name: publish-docs-site
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Never cancel in flight: a cancelled `wrangler pages deploy` is a half-published
+# site, and the next push rebuilds from the same inputs anyway. Queue instead.
+concurrency:
+  group: publish-docs-site
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: x64
+    steps:
+      # Runs BEFORE checkout, and does two things: points the harness's temp base
+      # out of the workspace for every later step in this job, and clears whatever
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          clean: true
+
+      # website/ is a STANDALONE package -- its own bun.lock, outside the root
+      # workspaces -- so the repo-root install never covers it, and the build
+      # needs both: the root for @norskvideo/ctl-dev-kit (docs:site:public stubs
+      # the recorded guides through its docs/guide-stubs.ts, and the gate below
+      # reads them the same way), website/ for Astro. Frozen, as every CI
+      # install is: a lockfile the build rewrites is drift nobody sees. The
+      # public variant (ASTRO_BUILD=public) is base /; the embedded one is base
+      # /docs, and every link in it is wrong on the public domain -- which is
+      # what the grep at the end catches.
+      - name: Build the public docs site
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun install --frozen-lockfile
+            bun install --frozen-lockfile --cwd website
+            bun run docs:site:public
+            dist="website/dist-public"
+            [ -s "$dist/index.html" ] || { echo "::error::$dist/index.html was not built"; exit 1; }
+            if grep -q "href=./docs/" "$dist/index.html"; then
+              echo "::error::$dist is the EMBEDDED variant (links are /docs-prefixed); docs:site:public must set ASTRO_BUILD=public"
+              exit 1
+            fi
+            echo "built $dist ($(find "$dist" -name "*.html" | wc -l) pages)"
+          '
+
+      # A recorded guide whose capture is not on this runner is a placeholder
+      # page after the build above (docs:site:public stubs it so the build
+      # works). Right for a local build, wrong for a deploy: the live page would
+      # be replaced with "run the doc-guide locally", and nothing else would
+      # notice -- the build is green, the links resolve. --content reads the
+      # guides the site declares by symlink, so a site that declares none has
+      # nothing to refuse; one that does needs its captures on the runner, and
+      # until the repo restores them this step says which pages are missing.
+      - name: Refuse to publish placeholder guides
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bun run node_modules/@norskvideo/ctl-dev-kit/docs/guide-stubs.ts check --content website/src/content/docs/guides
+          '
+
+      # Skipped -- loudly, and successfully -- while NORSK_DOCS_SITE_PROJECT is
+      # unset: the Pages project and the DNS record are the account owner's to
+      # create, and main must not go red waiting for them. Setting the variable
+      # is the whole switch-on.
+      #
+      # The token is verified at the API, not with `wrangler whoami`: whoami
+      # needs User Details:Read, which a Pages:Edit token deliberately lacks. Two
+      # kinds of token verify at two endpoints: a USER-owned token (My Profile ->
+      # API Tokens) answers /user/tokens/verify; an ACCOUNT-owned one (Manage
+      # Account -> API Tokens) returns 1000 "Invalid API Token" there however
+      # valid it is, and answers /accounts/<id>/tokens/verify. Checking only the
+      # first once made a valid team-owned token read like a bad secret. curl is
+      # on the host PATH; wrangler is not in the shared dev shell, so bunx fetches
+      # it inside `nix develop`, where bun is.
+      #
+      # --branch is the ref that pushed: main is the production branch of the
+      # Pages project, so a push to main publishes; a workflow_dispatch from any
+      # other branch publishes a PREVIEW deployment of that branch, never over
+      # production.
+      - name: Deploy to Cloudflare Pages
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          NORSK_DOCS_SITE_PROJECT: ${{ vars.NORSK_DOCS_SITE_PROJECT }}
+          PAGES_BRANCH: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [ -z "${NORSK_DOCS_SITE_PROJECT:-}" ]; then
+            origin="$(sed -nE 's/.*PUBLIC_SITE_ORIGIN = "([^"]+)".*/\1/p' website/src/lib/site.ts | head -1)"
+            echo "── Docs site → SKIPPED (no Pages project configured) ──"
+            echo "   The site built (website/dist-public) but NORSK_DOCS_SITE_PROJECT is unset, so"
+            echo "   nothing is deployed. To turn publishing on:"
+            echo "     1. Create a Cloudflare Pages project for this site (e.g. $(basename "$GITHUB_REPOSITORY")-docs)."
+            echo "     2. Add its custom domain${origin:+ (${origin#https://})} and the DNS record."
+            echo "     3. Make sure CLOUDFLARE_API_TOKEN (Pages:Edit) covers that project, and that"
+            echo "        CLOUDFLARE_ACCOUNT_ID is set as a repo secret."
+            echo "     4. Set the repo variable NORSK_DOCS_SITE_PROJECT to the project name."
+            echo "   Nothing in this workflow changes. See @norskvideo/ctl-dev-kit conventions/docs-site.md, Publishing."
+            exit 0
+          fi
+          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
+            echo "::error::NORSK_DOCS_SITE_PROJECT=$NORSK_DOCS_SITE_PROJECT is set, but CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID must both be repo secrets"
+            exit 1
+          fi
+          cf_verify() {
+            curl -fsS --retry 3 --retry-all-errors --retry-delay 2 \
+              -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+              "https://api.cloudflare.com/client/v4/$1" 2>&1
+          }
+          if verify_body=$(cf_verify "user/tokens/verify"); then
+            token_kind="user-owned"
+          elif verify_body=$(cf_verify "accounts/$CLOUDFLARE_ACCOUNT_ID/tokens/verify"); then
+            token_kind="account-owned"
+          else
+            echo "::error::Cloudflare token verification failed at both /user/tokens/verify and /accounts/<id>/tokens/verify. Last reply: $verify_body"
+            exit 1
+          fi
+          if ! echo "$verify_body" | grep -q '"status":"active"'; then
+            echo "::error::Cloudflare token not active ($token_kind): $verify_body"
+            exit 1
+          fi
+          # The token id is an identifier, not a credential: it answers "which of
+          # our tokens is CI using?", which a write-only secret otherwise cannot.
+          token_id=$(echo "$verify_body" | sed -n 's/.*"id":"\([a-f0-9]*\)".*/\1/p' | head -1)
+          echo "Cloudflare token: active ($token_kind${token_id:+, id ${token_id}})"
+          echo "── Docs site → Cloudflare Pages ($NORSK_DOCS_SITE_PROJECT, branch $PAGES_BRANCH) ──"
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            bunx wrangler@4 pages deploy website/dist-public \
+              --project-name "$NORSK_DOCS_SITE_PROJECT" \
+              --branch "$PAGES_BRANCH" \
+              --commit-dirty=true
+          '
+      - name: Reap the containers this job launched
+        # Whatever the tests did. A teardown cut short by a test timeout leaves
+        # its instance running on the shared Docker daemon (see JOB_REAP_STEP in
+        # conventions/workflow-shell.ts); everything this job launched mounts its
+        # own test-temp, so that is what goes.
+        if: always()
+        run: |
+          base="${NORSK_CTL_TEST_TMP:-}"
+          tt="$GITHUB_WORKSPACE/test-temp"
+          s=""
+          for c in $(docker ps -aq); do
+            src="$(docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null)" || continue
+            if { [ -n "$base" ] && grep -q "^$base/" <<<"$src"; } || grep -q "^$tt/" <<<"$src"; then s="$s $c"; fi
+          done
+          if [ -n "$s" ]; then
+            echo "::warning::removing containers this job left running:$s"
+            docker rm -f $s
+          fi