@norskvideo/ctl-dev-kit 0.2.54 → 0.2.56

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

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 },