@norskvideo/ctl-dev-kit 0.2.54 → 0.2.56

package/conventions/bot-prs.yml

@@ -13,12 +13,27 @@
 # So, for every open PR whose branch a bot owns:
 #   - every check on its head has passed and it merges cleanly -> squash-merge it
 #     (the PR's checks + smoke ARE the verdict; integration then runs on main);
-#   - a check failed, it conflicts with main, or it is a draft (the bot's own
-#     gate was red) -> list it, and report this repo's `bot-prs` cell RED on the
-#     product dashboard, which is the Discord message people actually read;
+#   - it conflicts with main -> re-run the bot that owns the branch, ONCE per
+#     head, so it rebuilds the branch from today's main (see below);
+#   - a check failed, it still conflicts after that rebuild, or it is a draft
+#     (the bot's own gate was red) -> list it, and report this repo's `bot-prs`
+#     cell RED on the product dashboard, which is the Discord message people
+#     actually read;
 #   - checks still running -> leave it for the next trigger.
 # The cell goes green again once nothing is red.
 #
+# Why the conflict rebuild: the three bots fire within minutes of each other
+# each morning and all write package.json and bun.lock, each from main as it
+# stood. Whichever lands first leaves the other's open PR conflicting, and the
+# bot only rebuilds its branch on its next DAILY run -- so on 2026-10-09
+# commentary, probe and reuters each had a sync-ctl-packages PR "needing a
+# human" that a re-run of sync-ctl-packages fixed outright. Every bot rebuilds
+# from main when run: sync-ctl-packages force-pushes a fresh branch, and
+# upgrade-latest / sync-dev-kit either land on main and close the PR they
+# superseded, or force-push their branch. The marker comment caps it at one
+# rebuild per head, so a rebuild that still conflicts goes to a human instead
+# of looping every hour.
+#
 # Runs when a PR's checks or smoke finish (the prompt path), hourly as a sweep,
 # and on demand. No checkout: it only talks to the GitHub API, so it needs none
 # of the runner-workspace steps the building workflows carry.
@@ -41,6 +56,8 @@ permissions:
   contents: read
   checks: read
   pull-requests: read
+  # The rebuild dispatch and its marker comment go through the PAT (WRITE_TOKEN),
+  # like the merges; this token only reads.
 
 concurrency:
   # One at a time per repo, and never cancelled: a merge half-done by a run that
@@ -86,8 +103,19 @@ jobs:
                  | select(.head.ref | test("^(upgrade-latest/|sync-dev-kit/|chore/sync-ctl-packages$)"))
                  | {number, ref: .head.ref, sha: .head.sha, draft, url: .html_url}]' <<<"$pulls")"
 
+          # The workflow that owns each bot branch, i.e. the one that rebuilds it.
+          producer() {
+            case "$1" in
+              upgrade-latest/*) echo upgrade-latest.yml ;;
+              sync-dev-kit/*) echo sync-dev-kit.yml ;;
+              chore/sync-ctl-packages) echo sync-ctl-packages.yml ;;
+              *) echo "" ;;
+            esac
+          }
+
           red=()
           merged=()
+          rebuilt=()
           while IFS= read -r pr; do
             [ -n "$pr" ] || continue
             n="$(jq -r .number <<<"$pr")"; ref="$(jq -r .ref <<<"$pr")"; sha="$(jq -r .sha <<<"$pr")"
@@ -106,7 +134,29 @@ jobs:
               [ "$mergeable" != "null" ] && break
               sleep 3
             done
-            if [ "$mergeable" != "true" ]; then red+=("#$n $ref: does not merge cleanly with main"); continue; fi
+            if [ "$mergeable" != "true" ]; then
+              # One rebuild per head: the marker names the sha it was asked for.
+              marker="bot-prs: rebuild requested for head $sha"
+              wf="$(producer "$ref")"
+              comments="$(gh_api "$api/issues/$n/comments?per_page=100")"
+              expect "reading comments on #$n" 'type == "array"' "$comments"
+              if [ -z "$wf" ]; then
+                red+=("#$n $ref: does not merge cleanly with main, and no bot is known to rebuild it")
+              elif jq -e --arg m "$marker" 'any(.[]; .body | contains($m))' >/dev/null <<<"$comments"; then
+                red+=("#$n $ref: still does not merge cleanly with main after $wf rebuilt it")
+              else
+                code="$(gh_write -o /dev/null -w '%{http_code}' -X POST "$api/actions/workflows/$wf/dispatches" -d '{"ref":"main"}')"
+                if [ "$code" = "204" ]; then
+                  body="$marker -- it conflicted with main (another bot landed first), so $wf was re-run to rebuild it from today's main. If the rebuilt branch conflicts too, this PR is reported for a human."
+                  gh_write -o /dev/null -X POST "$api/issues/$n/comments" -d "$(jq -nc --arg b "$body" '{body:$b}')" || true
+                  rebuilt+=("#$n")
+                  echo "#$n $ref: conflicts with main; re-ran $wf to rebuild it"
+                else
+                  red+=("#$n $ref: does not merge cleanly with main, and re-running $wf failed (HTTP $code)")
+                fi
+              fi
+              continue
+            fi
             # sha pins the merge to what was checked: a bot force-pushing the
             # branch meanwhile makes this refuse rather than land unchecked code.
             res="$(gh_write -X PUT "$api/pulls/$n/merge" -d "$(jq -nc --arg sha "$sha" '{merge_method:"squash", sha:$sha}')")"
@@ -128,7 +178,9 @@ jobs:
             state=success
             # Never empty: the dashboard step reads an empty detail as missing.
             merged_detail="${merged[*]:+merged ${merged[*]}}"
-            detail="${merged_detail:-no bot PRs waiting}"
+            rebuilt_detail="${rebuilt[*]:+rebuilding ${rebuilt[*]}}"
+            detail="$(printf '%s' "$merged_detail${merged_detail:+${rebuilt_detail:+; }}$rebuilt_detail")"
+            detail="${detail:-no bot PRs waiting}"
           fi
           echo "state=$state" >> "$GITHUB_OUTPUT"
           echo "detail=${detail%; }" >> "$GITHUB_OUTPUT"

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.