@norskvideo/ctl-dev-kit 0.1.56 → 0.1.58

package/conventions/build-docs.yml

@@ -0,0 +1,147 @@
+# Nightly: regenerate this product's docs bundle and bake it into the product
+# image. The EMBEDDED variant of the docs workflow (ADR-0012): the bundle is
+# built, put in the image the way a release build puts it there, and read back
+# out of that image as the proof. NOTHING LEAVES THE REPO -- no release asset,
+# no upload, no write permission on the repo, no token held. A turnkey's documentation
+# reaches exactly one customer, inside the image they already run.
+#
+# THE TWO VARIANTS (a repo carries exactly one; the drift gate enforces it):
+#   - build-docs.yml   (this file)  embedded: bundle -> image, full stop.
+#                                   Turnkeys (norsk-ctl-turnkey-*) carry this.
+#   - publish-docs.yml              public: the same build, then the bundle is
+#                                   published for the norsk-ctl docs site to
+#                                   ingest. ONLY a norsk-ctl-product-* repo may
+#                                   carry it -- the gate refuses it elsewhere.
+#
+# This workflow is SINGLE-SOURCED in @norskvideo/ctl-dev-kit
+# (conventions/build-docs.yml) and copied verbatim, same as checks.yml. It is
+# deliberately product-agnostic: everything per-repo lives in repo-local scripts
+# it calls --
+#   - scripts/doc-guide/regen-manual.sh   : the guide tiers + slug list + assemble
+#   - scripts/doc-guide/prepull-extra.sh  : OPTIONAL, any images beyond media+studio
+#   - deployment/build-image.sh           : the product image wrapper (dev-kit driver)
+# so the drift gate can keep every copy byte-identical. A turnkey with prose-only
+# pages (no doc-guides yet) has a regen-manual.sh that just assembles.
+#
+# Nightly-only by design, mirroring publish-docs.yml: a guide's engine tier
+# stands up real instances (slow, licensed), so it does not ride every push.
+name: build-docs
+
+on:
+  schedule:
+    - cron: "30 1 * * *" # 01:30 UTC — ahead of ctl's nightly docs build
+  workflow_dispatch:
+
+permissions:
+  contents: read # builds and bakes; nothing leaves the repo
+
+concurrency:
+  group: build-docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: x64
+    steps:
+      # A guide's engine tier launches the same docker instances the integration
+      # suite does, leaving root-owned bind-mount target dirs under test-temp/
+      # that the non-root runner can't remove — which fails actions/checkout's
+      # own cleanup before anything runs. Nuke them from a throwaway root
+      # container first. Best-effort. (Mirrors integration.yml.)
+      - name: Clear stale root-owned test-temp (pre-checkout)
+        run: |
+          set -uo pipefail
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          docker run --rm --user 0:0 -v "$tt":/t alpine sh \
+            -c 'rm -rf /t/* /t/.[!.]* 2>/dev/null || true' || rm -rf "$tt"/* 2>/dev/null || true
+
+      - uses: actions/checkout@v5
+        with:
+          clean: false
+
+      - name: Write the Norsk license (from the org secret)
+        env:
+          NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
+        run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
+
+      - name: Download the released norsk-ctl binary (latest channel)
+        run: |
+          set -euo pipefail
+          S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
+          ver="$(curl -fsSL "$S3/latest")"
+          echo "norsk-ctl latest channel -> $ver"
+          curl -fsSL "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
+          chmod +x "$RUNNER_TEMP/norsk-ctl"
+          "$RUNNER_TEMP/norsk-ctl" --version || true
+
+      # Cold-runner first pulls overrun the harness's per-test launch timeouts;
+      # pre-pull the universal media + studio images (every product pins them in
+      # manifest.seed.json) so compose/run hit local images. A product needing
+      # more (e.g. a WHIP driver) pulls them in scripts/doc-guide/prepull-extra.sh.
+      - name: Pre-pull the media + studio images
+        run: |
+          set -euo pipefail
+          for img in "$(jq -r '.latest.media' manifest.seed.json)" "$(jq -r '.latest.studio' manifest.seed.json)"; do
+            echo "pre-pulling $img"
+            docker pull "$img"
+          done
+          if [ -x scripts/doc-guide/prepull-extra.sh ]; then
+            echo "running scripts/doc-guide/prepull-extra.sh"
+            ./scripts/doc-guide/prepull-extra.sh
+          fi
+
+      # Rebuild every workspace the bundle depends on (a guide's engine tier packs
+      # the freshly-built dashboard + frontend dist into the launched template),
+      # then run the product's doc-guide tiers and assemble the bundle.
+      # regen-manual.sh owns the slug list and which tiers run; with-display.sh
+      # wraps the whole run in an X display for headless chromium (the engine tier
+      # drives a raw chromium that needs one).
+      - name: Regenerate the docs bundle (all tiers)
+        env:
+          NORSK_CTL_BINARY: ${{ runner.temp }}/norsk-ctl
+          NORSK_LICENSE_FILE: ${{ runner.temp }}/norsk-license.json
+          # This runner launches Studio as a HOST sibling (DooD), so the harness
+          # reaches host-published ports via the host-gateway alias, not
+          # localhost — same as the integration suite.
+          NORSK_TEST_HOST: host.docker.internal
+          # Reach launched instances over norsk-net by service DNS (as the
+          # integration tier already does) AND, on a ctl that supports it, launch
+          # them binding no host ports — so concurrent doc-guide instances can't
+          # collide on the product's deterministic host-port bands.
+          NORSK_TEST_NET: direct
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # clean:false persists node_modules between runs for speed, but a
+            # workspace dep whose version moved leaves stale copies that
+            # --frozen-lockfile does not reliably relink, so a new export is "not
+            # found". Nuke EVERY node_modules — including nested per-workspace ones
+            # — for a deterministic install. A nightly can afford it.
+            find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
+            bun install --frozen-lockfile
+            bun run build:no-lint
+            bash scripts/with-display.sh scripts/doc-guide/regen-manual.sh
+          '
+
+      # The proof: the bundle the tiers just built goes into the product image
+      # the way a release build puts it there (deployment/build-image.sh stages
+      # docs/generated/bundle/ as the image's docs/), and the image is asked for
+      # its manifest. A bundle that does not build, or does not reach the image,
+      # fails here — on the commit that broke it. The image is local to the
+      # runner: nothing is pushed, nothing is uploaded, no token is held.
+      - name: Bake the bundle into the product image and read it back
+        env:
+          IMAGE_TAG: build-docs-bake:${{ github.sha }}
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            man="docs/generated/bundle/bundle.json"
+            [ -s "$man" ] || { echo "::error::bundle was not generated at $man"; exit 1; }
+            bash deployment/build-image.sh
+            docker run --rm --entrypoint /usr/local/bin/bun "$IMAGE_TAG" -e "
+              const m = require(\"/usr/src/app/docs/bundle.json\");
+              console.log(\"image carries docs bundle schema\", m.schemaVersion, \"with\", m.pages.length, \"pages, built\", m.provenance.builtAt);
+            "
+            docker image rm -f "$IMAGE_TAG" >/dev/null
+          '

package/conventions/check-drift.ts

@@ -17,6 +17,7 @@
 // dev-kit forces a re-sync. Canonical bytes ship alongside this script
 // (conventions/* + build/*), resolved package-relative so they work both
 // workspace-symlinked and installed from the published tarball.
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { parseManifestSeed } from "@norskvideo/ctl-sdk/manifest-seed";
@@ -238,6 +239,8 @@ export interface CanonicalBytes {
   upgradeLatest: string;
   syncDevKit: string;
   publishDocs: string;
+  /** conventions/build-docs.yml — the embedded docs variant (bundle -> image, no upload). */
+  buildDocs: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -320,7 +323,59 @@ function verbatimProblem(
   return undefined;
 }
 
-export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftReport {
+export interface CheckDriftOptions {
+  /** The GitHub repo name (`norsk-ctl-product-playout`), which decides whether the
+   *  public docs variant may be carried. The CLI resolves it ({@link resolveRepoName});
+   *  a fixture passes it. Unknown is allowed only while nothing depends on it. */
+  repoName?: string;
+}
+
+/** `owner/name` from GITHUB_REPOSITORY (Actions), else the last path segment of
+ *  the origin remote. Undefined when neither is available. */
+export function resolveRepoName(repoRoot: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const fromEnv = env.GITHUB_REPOSITORY?.split("/").pop();
+  if (fromEnv) return fromEnv;
+  try {
+    const url = execFileSync("git", ["-C", repoRoot, "remote", "get-url", "origin"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const name = url
+      .split(/[/:]/)
+      .pop()
+      ?.replace(/\.git$/, "");
+    return name || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const PUBLIC_DOCS_REPO = /^norsk-ctl-product-/;
+
+/** 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
+ *  one only where GitHub calls the repo norsk-ctl-product-*; a name it cannot
+ *  determine is a finding, never a silent pass. */
+export function docsExposureProblems(hasPublish: boolean, hasBuild: boolean, repoName: string | undefined): string[] {
+  const problems: string[] = [];
+  if (hasPublish && hasBuild) {
+    problems.push(
+      "a repo carries exactly one docs workflow: .github/workflows/publish-docs.yml (public: the bundle is published for the norsk-ctl docs site) OR .github/workflows/build-docs.yml (embedded: the bundle goes into the image and nowhere else). Both are present; delete one.",
+    );
+  }
+  if (hasPublish && repoName === undefined) {
+    problems.push(
+      ".github/workflows/publish-docs.yml publishes this repo's docs publicly, and the gate cannot tell which repo this is (no GITHUB_REPOSITORY, no origin remote). Only a norsk-ctl-product-* repo may carry the public variant.",
+    );
+  } else if (hasPublish && !PUBLIC_DOCS_REPO.test(repoName as string)) {
+    problems.push(
+      `.github/workflows/publish-docs.yml publishes this repo's docs publicly, but this repo is ${repoName}, not a norsk-ctl-product-* repo. A turnkey's documentation never leaves the box: carry build-docs.yml (the embedded variant) instead.`,
+    );
+  }
+  return problems;
+}
+
+export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: CheckDriftOptions = {}): DriftReport {
   const problems: string[] = [];
   const push = (problem: string | undefined) => {
     if (problem) problems.push(problem);
@@ -490,6 +545,18 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftRe
     }
   }
 
+  // build-docs.yml is the embedded twin of publish-docs.yml: optional, verbatim.
+  const buildDocsPath = join(repoRoot, ".github", "workflows", "build-docs.yml");
+  if (existsSync(buildDocsPath)) {
+    const actual = readFileSync(buildDocsPath, "utf8");
+    if (actual !== canonical.buildDocs) {
+      push(
+        `.github/workflows/build-docs.yml has drifted from @norskvideo/ctl-dev-kit conventions/build-docs.yml (${firstDiffLine(actual, canonical.buildDocs)}). ${RESYNC}`,
+      );
+    }
+  }
+  for (const p of docsExposureProblems(existsSync(publishDocsPath), existsSync(buildDocsPath), opts.repoName)) push(p);
+
   for (const p of demoProblems(repoRoot, canonical.demoShim)) push(p);
 
   return { ok: problems.length === 0, problems };
@@ -503,6 +570,7 @@ if (import.meta.main) {
     upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "utf8"),
     publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
+    buildDocs: readFileSync(join(import.meta.dir, "build-docs.yml"), "utf8"),
     checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(import.meta.dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(import.meta.dir, "tsconfig.base.json"), "utf8"),
@@ -513,7 +581,7 @@ if (import.meta.main) {
     smoke: readFileSync(join(import.meta.dir, "smoke.yml"), "utf8"),
     demoShim: readFileSync(join(import.meta.dir, "demo.sh"), "utf8"),
   };
-  const report = checkDrift(repoRoot, canonical);
+  const report = checkDrift(repoRoot, canonical, { repoName: resolveRepoName(repoRoot) });
   if (report.ok) {
     console.log("drift-check: all shared-convention copies match @norskvideo/ctl-dev-kit.");
     process.exit(0);

package/conventions/docs.md

@@ -128,19 +128,28 @@ pulls them in an optional `scripts/doc-guide/prepull-extra.sh`.
 
 ## The publish contract
 
-Latest-only, republished by ctl:
-
-- Each product's nightly (`publish-docs.yml`, single-sourced + drift-gated)
-  rebuilds the manual to ONE self-contained `manual.html` and publishes it as the
-  asset of a **moving `docs-latest` GitHub Release** — never versioned, its single
-  asset clobbered each night. Stable URL:
-  `https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html`.
-- **norsk-ctl's docs build fetches each registered product's `docs-latest` asset
-  and mounts it at `/products/<slug>/`**, deploying the one Cloudflare Pages
-  project — so ctl republishes every product's manual whenever it builds its docs.
-  A true per-product subdir on ctl's site only works by ctl aggregating, because a
-  Pages deploy is whole-site.
-
-Two files back the contract: `manual.html` (the standalone document — publish
-THIS, not the Artifact fragment `index.html`) and, on the ctl side, the product
-registry the aggregator reads.
+The unit is the **docs bundle** (`buildBundle` -> `docs/generated/bundle/`:
+`bundle.json`, `pages/*.md`, `captures/`, and the derived `manual.html`).
+Exposure is declared by which docs workflow the repo carries — exactly one,
+single-sourced here and drift-gated:
+
+- **`build-docs.yml` — embedded.** Nightly: regenerate the bundle, bake it into
+  the product image through `deployment/build-image.sh`, read it back out of the
+  image as the proof. No upload, no write permission on the repo, no token. A
+  turnkey (`norsk-ctl-turnkey-*`) carries this and nothing else: its
+  documentation reaches exactly one customer, inside the image they already run.
+- **`publish-docs.yml` — public.** The same build, then `manual.html` is
+  published as the asset of the moving `docs-latest` GitHub Release
+  (`https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html`)
+  for norsk-ctl's docs site to fetch and mount at `/products/<slug>/`. Versioned
+  bundle assets behind a `latest` pointer, and ingestion of `pages/*.md` into the
+  site, come with the public-plane work. **Only a repo GitHub calls
+  `norsk-ctl-product-*` may carry it.** `check:drift` refuses it anywhere else,
+  refuses a repo carrying both, and refuses the public variant when it cannot
+  tell the repo's name (`GITHUB_REPOSITORY` in CI, the origin remote locally).
+
+Either way the image serves the bundle at `/docs` (SDK `serveDocs`), reached
+through the daemon at `/products/<name>/docs/` behind its auth guard and linked
+from the product's hub via `ui.sidebarEntries`. That is the sole channel for a
+turnkey and the version-true channel for a product; the public site is the
+faster-cadence copy, for products only.

package/conventions/sync-drift.ts

@@ -232,6 +232,12 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
   if (existsSync(join(repoRoot, publishDocsRel))) {
     writeIfChanged(join(repoRoot, publishDocsRel), canonical.publishDocs, publishDocsRel, r.written);
   }
+  // build-docs.yml, the embedded variant, the same way: carrying it is the
+  // repo's declaration (ADR-0012); sync only keeps the copy verbatim.
+  const buildDocsRel = ".github/workflows/build-docs.yml";
+  if (existsSync(join(repoRoot, buildDocsRel))) {
+    writeIfChanged(join(repoRoot, buildDocsRel), canonical.buildDocs, buildDocsRel, r.written);
+  }
 
   syncFlake(repoRoot, canonical.flake, r);
   syncClaude(repoRoot, canonical.core, r);
@@ -251,6 +257,7 @@ if (import.meta.main) {
     upgradeLatest: readFileSync(join(dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(dir, "sync-dev-kit.yml"), "utf8"),
     publishDocs: readFileSync(join(dir, "publish-docs.yml"), "utf8"),
+    buildDocs: readFileSync(join(dir, "build-docs.yml"), "utf8"),
     checks: readFileSync(join(dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(dir, "tsconfig.base.json"), "utf8"),

package/create-product/assets/ci-status-dispatch.yml

@@ -19,7 +19,7 @@ inputs:
     description: "Product key: commentary | playout | probe | studio | funke | reuters."
     required: true
   pipeline:
-    description: "Pipeline key: build-image | integration | drift | nightly."
+    description: "Pipeline key: build-image | integration | checks | nightly | dev-kit | smoke | docs."
     required: true
   status:
     description: "success or failure."

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

@@ -20,8 +20,9 @@ export interface ManualOverview {
     headline: string;
     /** The lead paragraph under it. */
     lead: string;
-    /** The hero capture (a representative shot) and its caption. */
-    hero: {
+    /** The hero capture (a representative shot) and its caption. A prose-only
+     *  manual (a turnkey handover) has none. */
+    hero?: {
         slug: string;
         file: string;
         alt: string;
@@ -41,6 +42,15 @@ export interface ManualLink {
     label: string;
     href: string;
 }
+/** A prose page: hand-written markdown carried as-is (a turnkey's handover
+ *  document, an operator runbook). Rendered to HTML in the manual, verbatim in
+ *  the bundle. Captures are optional per page; a document has none. */
+export interface ManualDocument {
+    id: string;
+    nav: string;
+    title: string;
+    markdown: string;
+}
 export interface ManualSpec {
     /** Sidebar wordmark + document brand. */
     brand: string;
@@ -49,6 +59,8 @@ export interface ManualSpec {
     overview: ManualOverview;
     functionality: ManualPage[];
     examples: ManualPage[];
+    /** Prose pages, listed after the walkthroughs. */
+    documents?: ManualDocument[];
     /** Outbound links for the footer. Optional, but every published manual should
      *  carry at least one. */
     links?: ManualLink[];

package/doc-guide/build-manual.js

@@ -26,6 +26,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { marked } from "marked";
 /** Provenance as a GitHub Actions run sees it (GITHUB_SHA / GITHUB_RUN_ID), or
  *  as much of it as a local build has. */
 export function provenanceFromEnv(env = process.env) {
@@ -111,6 +112,7 @@ export function buildManual(spec, opts) {
     };
     const FN = spec.functionality;
     const EX = spec.examples;
+    const DOCS = spec.documents ?? [];
     const ALL = [...FN, ...EX];
     const byId = new Map(ALL.map((p) => [p.id, p]));
     const render = (uri) => {
@@ -137,22 +139,36 @@ export function buildManual(spec, opts) {
     <p class="lead">${esc(p.intro)}</p>
     <ol class="steps">${steps}</ol>
     ${thin}${links}
+  </article>`;
+        }
+        function documentHtml(d) {
+            return `<article class="page doc" id="${d.id}">
+    <div class="phead"><span class="kind doc">Document</span><h1>${esc(d.title)}</h1></div>
+    <div class="prose">${marked.parse(d.markdown, { async: false })}</div>
   </article>`;
         }
         const ov = spec.overview;
+        const hero = ov.hero
+            ? `\n  <div class="heroshot"><div class="shot"><img src="${uri(ov.hero.slug, ov.hero.file)}" alt="${esc(ov.hero.alt)}"></div><p class="hcap">${esc(ov.hero.caption)}</p></div>`
+            : "";
+        const linklist = (pages) => `<div class="linklist">${pages.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div>`;
+        const cols = [
+            FN.length ? `<div><h2>${esc(ov.byFunctionHeading ?? "By function")}</h2>${linklist(FN)}</div>` : "",
+            EX.length
+                ? `<div><h2>${esc(ov.byExampleHeading ?? "By example")}</h2><p class="mini">${esc(ov.byExampleIntro)}</p>${linklist(EX)}</div>`
+                : "",
+            DOCS.length ? `<div><h2>Documents</h2>${linklist(DOCS)}</div>` : "",
+        ].filter(Boolean);
         const overview = `<article class="page" id="overview">
   <div class="phead"><span class="kind ov">Overview</span><h1>${esc(ov.headline)}</h1></div>
-  <p class="lead">${esc(ov.lead)}</p>
-  <div class="heroshot"><div class="shot"><img src="${uri(ov.hero.slug, ov.hero.file)}" alt="${esc(ov.hero.alt)}"></div><p class="hcap">${esc(ov.hero.caption)}</p></div>
-  <div class="twocol">
-    <div><h2>${esc(ov.byFunctionHeading ?? "By function")}</h2><div class="linklist">${FN.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div></div>
-    <div><h2>${esc(ov.byExampleHeading ?? "By example")}</h2><p class="mini">${esc(ov.byExampleIntro)}</p><div class="linklist">${EX.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div></div>
-  </div>
+  <p class="lead">${esc(ov.lead)}</p>${hero}
+  ${cols.length ? `<div class="twocol">\n    ${cols.join("\n    ")}\n  </div>` : ""}
 </article>`;
+        const navGroup = (head, pages) => pages.length
+            ? `\n  <div class="ngroup"><div class="ghead">${head}</div>${pages.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>`
+            : "";
         const nav = `
-  <a href="#overview" data-nav class="ovlink">Overview</a>
-  <div class="ngroup"><div class="ghead">Functionality</div>${FN.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>
-  <div class="ngroup"><div class="ghead">Examples <span class="ct">${EX.length}</span></div>${EX.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>`;
+  <a href="#overview" data-nav class="ovlink">Overview</a>${navGroup("Functionality", FN)}${navGroup(`Examples <span class="ct">${EX.length}</span>`, EX)}${navGroup("Documents", DOCS)}`;
         const html = `<style>
 :root{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;--faint:#5f6a79;
   --line:#212a36;--accent:#54d6cf;--measure:64ch}
@@ -184,7 +200,18 @@ main{min-width:0;padding:0 clamp(20px,5vw,72px)}
 @media (prefers-reduced-motion:reduce){.page{animation:none}}
 .phead{margin-bottom:20px}
 .kind{display:inline-block;font-family:ui-monospace,Menlo,monospace;font-size:10px;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);margin-bottom:12px}
-.kind.ex{color:var(--dim)}.kind.ov{color:var(--faint)}
+.kind.ex{color:var(--dim)}.kind.ov{color:var(--faint)}.kind.doc{color:var(--dim)}
+.prose{max-width:var(--measure)}
+.prose h2{font-size:22px;margin:36px 0 10px;letter-spacing:-.015em}
+.prose h3{font-size:17px;margin:26px 0 8px}
+.prose p,.prose li{color:var(--dim);font-size:15px}
+.prose code{font-family:ui-monospace,Menlo,monospace;font-size:.92em;background:var(--surf);border:1px solid var(--line);border-radius:4px;padding:1px 5px}
+.prose pre{background:var(--surf);border:1px solid var(--line);border-radius:9px;padding:14px 16px;overflow-x:auto;font-size:13px}
+.prose pre code{background:none;border:none;padding:0}
+.prose table{border-collapse:collapse;width:100%;font-size:14px;margin:16px 0}
+.prose th,.prose td{text-align:left;padding:8px 10px;border-bottom:1px solid var(--line);vertical-align:top}
+.prose th{color:var(--ink);font-weight:600}
+.prose a{color:var(--accent)}
 .phead h1{font-size:clamp(26px,4vw,42px);line-height:1.05;letter-spacing:-.028em;margin:0;font-weight:730;text-wrap:balance}
 .ptag{margin-top:12px;font-size:12px;color:var(--faint)}
 .lead{font-size:clamp(15px,1.9vw,18px);color:var(--dim);max-width:var(--measure);margin:0 0 8px}
@@ -227,6 +254,7 @@ main{min-width:0;padding:0 clamp(20px,5vw,72px)}
 <main>
 ${overview}
 ${ALL.map(pageHtml).join("\n")}
+${DOCS.map(documentHtml).join("\n")}
 ${footerHtml(spec, provenance)}
 </main>
 </div>

package/doc-guide/bundle.d.ts

@@ -4,7 +4,7 @@ export interface BundlePageEntry {
     id: string;
     nav: string;
     title: string;
-    kind: "overview" | "fn" | "ex";
+    kind: "overview" | "fn" | "ex" | "doc";
     /** Relative to the bundle directory. */
     file: string;
 }

package/doc-guide/bundle.js

@@ -28,6 +28,7 @@ export function buildBundle(spec, opts) {
     // Pages live one level down, so a capture href is reached via `../`.
     const captureRef = (slug, file) => `../${hrefs[`${slug}/${file}`]}`;
     const all = [...spec.functionality, ...spec.examples];
+    const docs = spec.documents ?? [];
     const byId = new Map(all.map((p) => [p.id, p]));
     const pageLink = (id) => {
         const t = byId.get(id);
@@ -57,28 +58,35 @@ export function buildBundle(spec, opts) {
         "",
         ov.lead,
         "",
-        `![${ov.hero.alt}](${captureRef(ov.hero.slug, ov.hero.file)})`,
-        "",
-        `_${ov.hero.caption}_`,
-        "",
-        `## ${ov.byFunctionHeading ?? "By function"}`,
-        "",
-        ...spec.functionality.map((p) => `- ${pageLink(p.id)}`),
-        "",
-        `## ${ov.byExampleHeading ?? "By example"}`,
-        "",
-        ov.byExampleIntro,
-        "",
-        ...spec.examples.map((p) => `- ${pageLink(p.id)}`),
-        "",
+        ...(ov.hero
+            ? [`![${ov.hero.alt}](${captureRef(ov.hero.slug, ov.hero.file)})`, "", `_${ov.hero.caption}_`, ""]
+            : []),
+        ...(spec.functionality.length
+            ? [`## ${ov.byFunctionHeading ?? "By function"}`, "", ...spec.functionality.map((p) => `- ${pageLink(p.id)}`), ""]
+            : []),
+        ...(spec.examples.length
+            ? [
+                `## ${ov.byExampleHeading ?? "By example"}`,
+                "",
+                ov.byExampleIntro,
+                "",
+                ...spec.examples.map((p) => `- ${pageLink(p.id)}`),
+                "",
+            ]
+            : []),
+        ...(docs.length ? ["## Documents", "", ...docs.map((d) => `- [${d.nav}](${d.id}.md)`), ""] : []),
     ].join("\n");
+    const documentMarkdown = (d) => ["---", `title: ${yamlString(d.title)}`, `nav: ${yamlString(d.nav)}`, "kind: doc", "---", "", d.markdown].join("\n");
     const pages = [
         { id: "overview", nav: "Overview", title: ov.headline, kind: "overview", file: "pages/overview.md" },
         ...all.map((p) => ({ id: p.id, nav: p.nav, title: p.title, kind: p.kind, file: `pages/${p.id}.md` })),
+        ...docs.map((d) => ({ id: d.id, nav: d.nav, title: d.title, kind: "doc", file: `pages/${d.id}.md` })),
     ];
     writeFileSync(join(outDir, "pages/overview.md"), overviewMarkdown);
     for (const p of all)
         writeFileSync(join(outDir, `pages/${p.id}.md`), pageMarkdown(p));
+    for (const d of docs)
+        writeFileSync(join(outDir, `pages/${d.id}.md`), documentMarkdown(d));
     const exports = { manual: "manual.html", manualLinked: "manual-linked.html" };
     writeFileSync(join(outDir, exports.manual), manual.standaloneHtml);
     writeFileSync(join(outDir, exports.manualLinked), manual.standaloneAssetHtml ?? manual.standaloneHtml);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -19,7 +19,8 @@
     "ctl-dev-kit": "./create-product/cli.ts"
   },
   "dependencies": {
-    "@norskvideo/ctl-sdk": "^0.1.0"
+    "@norskvideo/ctl-sdk": "^0.1.0",
+    "marked": "18.0.11"
   },
   "peerDependencies": {
     "@playwright/test": "*"