@norskvideo/ctl-dev-kit 0.1.55 → 0.1.57

package/build/Dockerfile.bundle

@@ -50,6 +50,11 @@ COPY dashboards /usr/src/dashboards
 COPY components/lib /usr/src/components/lib
 # Optional product-template assets (funke's slate/black PNGs). Empty otherwise.
 COPY assets /usr/src/assets
+# The docs bundle (docs/generated/bundle/ on the host), served by the product
+# at /docs. Beside backend/ and frontend/ so server.ts reaches it the same way
+# it reaches frontend/dist (../../docs from the bundle dir). Empty when the
+# product built none.
+COPY docs ./docs
 ENV PORT=${PRODUCT_PORT}
 EXPOSE ${PRODUCT_PORT}
 CMD ["/usr/local/bin/bun", "run", "backend/dist/index.js"]

package/build/build-bundle-image.sh

@@ -23,6 +23,7 @@
 #   components/lib             the components workspace's build output
 #   native/                    native addon(s) (probe's signer) -> beside bundle
 #   assets/                    product-template assets (funke's PNGs)
+#   docs/generated/bundle/     the docs bundle (doc-guide buildBundle) -> docs/
 #   scripts/runtime-images.ts  -> emits the norsk-ctl.runtime-images label
 #
 # Only backend/dist is required. A product with no frontend/dashboard/components
@@ -51,7 +52,7 @@ trap 'rm -rf "${stage}"' EXIT
 
 echo "==> staging artifacts"
 mkdir -p "${stage}/backend" "${stage}/frontend/dist" "${stage}/components/lib" \
-  "${stage}/dashboards" "${stage}/native" "${stage}/assets"
+  "${stage}/dashboards" "${stage}/native" "${stage}/assets" "${stage}/docs"
 # The backend bundle is the one non-negotiable payload — every bundle product has
 # one, so a missing dist is a broken build, not an absent workspace.
 cp -R "${PRODUCT_DIR}/backend/dist" "${stage}/backend/dist"
@@ -87,6 +88,12 @@ if [ -d "${PRODUCT_DIR}/assets" ]; then
   cp -R "${PRODUCT_DIR}/assets/." "${stage}/assets/"
 fi
 
+# The docs bundle (optional): ONLY the built bundle, never the hand-written
+# docs/ tree beside it (planning notes, customer folders).
+if [ -d "${PRODUCT_DIR}/docs/generated/bundle" ]; then
+  cp -R "${PRODUCT_DIR}/docs/generated/bundle/." "${stage}/docs/"
+fi
+
 # Runtime images the default templates launch, stamped on as a label so a
 # golden-image bake can warm them with `docker inspect` + `docker pull` alone —
 # no daemon, no license. Derived from the rendered compose (scripts/runtime-images.ts),

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

@@ -95,9 +95,22 @@ they do not copy it:
   docsRoot, … })`, the Playwright config for the fixture/frontend tiers, carrying
   the CI defaults (bind+probe `127.0.0.1`, 120s webServer timeout, piped output).
 - `@norskvideo/ctl-dev-kit/doc-guide/build-manual` — `buildManual(spec, {
-  docsRoot })`, the generic assembler. The product supplies ONLY the page content
-  (`ManualSpec`: brand, overview, functionality[], examples[]); layout, CSS and
-  routing live in the assembler so every product's manual looks the same.
+  docsRoot, provenance })`, the generic assembler. The product supplies ONLY the
+  page content (`ManualSpec`: brand, overview, functionality[], examples[], and
+  `links` — the way out: the product's page on norsk.video, a contact); layout,
+  CSS and routing live in the assembler so every product's manual looks the
+  same. Every export ends in a provenance footer (build time, source sha, CI
+  run id — `provenanceFromEnv()` reads them from a GitHub Actions run).
+- `@norskvideo/ctl-dev-kit/doc-guide/bundle` — `buildBundle(spec, { docsRoot,
+  outDir, provenance })`, the docs bundle: `bundle.json` + `pages/<id>.md` +
+  `captures/` + the derived `manual.html`/`manual-linked.html`, in one
+  directory. Write it to `docs/generated/bundle/`: the image build stages that
+  directory as the image's `docs/` and the backend serves it at `/docs` with
+  the SDK's `serveDocs(app, docsBundleDir(import.meta.dir))` — one line in
+  `server.ts`, a no-op when there is no bundle. Declare the nav entry in the
+  manifest: `ui.sidebarEntries: [{ label: "Documentation", route: "/docs/" }]`;
+  ctl links it under `/products/<name>/`. An older ctl simply does not link it
+  (additive: nothing about launch changes).
 - `@norskvideo/ctl-dev-kit/doc-guide/{instance-proxy,live-browser}` — engine-tier
   support (serve the baked dashboard under its advertised instance prefix; launch
   the nix chromium for a live capture).
@@ -115,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/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;
@@ -34,6 +35,22 @@ export interface ManualOverview {
     /** The small print under the right column heading. */
     byExampleIntro: string;
 }
+/** A way out of the manual: the product's marketing page, the platform docs,
+ *  a contact. Rendered in the footer of every export. Hash links are the only
+ *  navigation otherwise, so a manual without these is a cul-de-sac. */
+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;
@@ -42,7 +59,29 @@ 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[];
+}
+/** Where a build came from, stamped into the footer so two copies of "the
+ *  manual" can be told apart without hashing them. `builtAt` defaults to now;
+ *  the rest is whatever the build knows (CI knows all of it, see
+ *  {@link provenanceFromEnv}). */
+export interface Provenance {
+    /** Source commit the captures and copy were built from. */
+    sha?: string;
+    /** The CI run that built it, when there was one. */
+    runId?: string;
+    /** ISO-8601. */
+    builtAt?: string;
+    /** The product version, when the build knows it. */
+    version?: string;
 }
+/** Provenance as a GitHub Actions run sees it (GITHUB_SHA / GITHUB_RUN_ID), or
+ *  as much of it as a local build has. */
+export declare function provenanceFromEnv(env?: NodeJS.ProcessEnv): Provenance;
 export interface BuildManualResult {
     /** Artifact-ready fragment (no doctype/head/body). */
     indexHtml: string;
@@ -55,6 +94,9 @@ export interface BuildManualResult {
     standaloneAssetHtml?: string;
     /** `<slug>/<file>` of every referenced capture not found on disk. */
     missing: string[];
+    /** `<slug>/<file>` -> the sidecar href it was written to. Only when `assets`
+     *  is set; what a bundle's markdown pages reference captures by. */
+    sidecarHrefs?: Record<string, string>;
 }
 /** Where to write de-inlined captures for the standalone manual. `dir` is the
  *  filesystem directory; `href` (default "images") is the relative URL prefix
@@ -63,7 +105,9 @@ export interface ManualAssets {
     dir: string;
     href?: string;
 }
-export declare function buildManual(spec: ManualSpec, opts: {
+export interface BuildManualOptions {
     docsRoot: string;
     assets?: ManualAssets;
-}): BuildManualResult;
+    provenance?: Provenance;
+}
+export declare function buildManual(spec: ManualSpec, opts: BuildManualOptions): BuildManualResult;

package/doc-guide/build-manual.js

@@ -26,6 +26,17 @@
 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) {
+    const p = { builtAt: new Date().toISOString() };
+    if (env.GITHUB_SHA)
+        p.sha = env.GITHUB_SHA;
+    if (env.GITHUB_RUN_ID)
+        p.runId = env.GITHUB_RUN_ID;
+    return p;
+}
 const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 /** Resize a captured PNG to <=1100px wide JPEG. A missing capture becomes a
  *  labelled placeholder so the manual still builds, and is recorded in `missing`. */
@@ -63,8 +74,22 @@ function fileUri(a, file, assets) {
     writeFileSync(join(assets.dir, name), a.kind === "svg" ? Buffer.from(a.text) : a.bytes);
     return `${assets.href ?? "images"}/${name}`;
 }
+/** The footer every export carries: provenance first, then the way out. */
+function footerHtml(spec, provenance) {
+    const facts = [];
+    if (provenance.version)
+        facts.push(`version ${esc(provenance.version)}`);
+    facts.push(`built ${esc(provenance.builtAt ?? new Date().toISOString())}`);
+    if (provenance.sha)
+        facts.push(`source <span class="mono">${esc(provenance.sha)}</span>`);
+    if (provenance.runId)
+        facts.push(`run <span class="mono">${esc(provenance.runId)}</span>`);
+    const links = (spec.links ?? []).map((l) => `<a href="${esc(l.href)}">${esc(l.label)}</a>`).join("");
+    return `<footer class="prov"><div class="facts">${esc(spec.brand)} &middot; ${facts.join(" &middot; ")}</div>${links ? `<div class="out">${links}</div>` : ""}</footer>`;
+}
 export function buildManual(spec, opts) {
     const { docsRoot, assets } = opts;
+    const provenance = { builtAt: new Date().toISOString(), ...opts.provenance };
     const missing = [];
     // Each shot is loaded (resized) at most once, then rendered inline for the
     // fragment and — when `assets` is set — as a sidecar file for the standalone.
@@ -79,9 +104,15 @@ export function buildManual(spec, opts) {
         return a;
     };
     const inline = (slug, file) => inlineUri(load(slug, file));
-    const external = (slug, file) => fileUri(load(slug, file), file, assets);
+    const sidecarHrefs = {};
+    const external = (slug, file) => {
+        const href = fileUri(load(slug, file), file, assets);
+        sidecarHrefs[`${slug}/${file}`] = href;
+        return href;
+    };
     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) => {
@@ -108,24 +139,37 @@ 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>`;
-        const html = `<title>${esc(spec.title)}</title>
-<style>
+  <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}
 @media (prefers-color-scheme:light){:root{--bg:#f5f7f9;--bg2:#eef1f4;--surf:#fff;--ink:#0f1620;
@@ -156,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}
@@ -185,6 +240,10 @@ main{min-width:0;padding:0 clamp(20px,5vw,72px)}
 .linklist{display:flex;flex-direction:column;gap:2px}
 .linklist a{text-decoration:none;color:var(--dim);font-size:14px;padding:5px 0}
 .linklist a:hover{color:var(--accent)}
+.prov{margin:0 0 48px;padding-top:18px;border-top:1px solid var(--line);font-size:12px;color:var(--faint);display:flex;flex-wrap:wrap;gap:8px 24px;justify-content:space-between}
+.prov .out{display:flex;flex-wrap:wrap;gap:14px}
+.prov a{color:var(--dim);text-decoration:none}
+.prov a:hover{color:var(--accent)}
 @media (max-width:880px){.wrap{grid-template-columns:1fr}
   aside{position:static;height:auto;border-right:none;border-bottom:1px solid var(--line)}
   .twocol{grid-template-columns:1fr}}
@@ -195,6 +254,8 @@ 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>
 
@@ -223,12 +284,17 @@ ${ALL.map(pageHtml).join("\n")}
 ${body}
 </body>
 </html>`;
+    // The Artifact tool supplies the head, so the fragment carries its own
+    // <title>; the standalone wraps the BODY alone, so the title appears once.
+    const fragment = (body) => `<title>${esc(spec.title)}</title>\n${body}`;
     // Fragment and standalone are both inlined (Artifact CSP; publishable on its
     // own). Sidecars are an EXTRA output, never a substitution.
-    const indexHtml = render(inline);
-    const standaloneHtml = document(indexHtml);
+    const body = render(inline);
+    const indexHtml = fragment(body);
+    const standaloneHtml = document(body);
     if (!assets)
         return { indexHtml, standaloneHtml, missing };
     mkdirSync(assets.dir, { recursive: true });
-    return { indexHtml, standaloneHtml, standaloneAssetHtml: document(render(external)), missing };
+    const standaloneAssetHtml = document(render(external));
+    return { indexHtml, standaloneHtml, standaloneAssetHtml, missing, sidecarHrefs };
 }

package/doc-guide/bundle.d.ts

@@ -0,0 +1,37 @@
+import { type BuildManualResult, type ManualLink, type ManualSpec, type Provenance } from "./build-manual.js";
+export declare const BUNDLE_SCHEMA_VERSION = 1;
+export interface BundlePageEntry {
+    id: string;
+    nav: string;
+    title: string;
+    kind: "overview" | "fn" | "ex" | "doc";
+    /** Relative to the bundle directory. */
+    file: string;
+}
+export interface BundleManifest {
+    schemaVersion: number;
+    brand: string;
+    title: string;
+    provenance: Provenance;
+    links: ManualLink[];
+    pages: BundlePageEntry[];
+    /** Derived single-page exports, relative to the bundle directory. */
+    exports: {
+        manual: string;
+        manualLinked: string;
+    };
+    /** `<slug>/<file>` of every referenced capture that was not on disk — a
+     *  bundle with gaps is still a bundle, but a consumer can see them. */
+    missing: string[];
+}
+export interface BuildBundleOptions {
+    docsRoot: string;
+    /** Where the bundle is written; created if absent. */
+    outDir: string;
+    provenance?: Provenance;
+}
+export interface BuildBundleResult extends BuildManualResult {
+    manifest: BundleManifest;
+    outDir: string;
+}
+export declare function buildBundle(spec: ManualSpec, opts: BuildBundleOptions): BuildBundleResult;

package/doc-guide/bundle.js

@@ -0,0 +1,105 @@
+// The docs bundle: what a product's docs build produces, and the unit every
+// downstream consumer reads (ADR-0012). A directory holding
+//
+//   bundle.json          this manifest — identity, provenance, the page list
+//   pages/<id>.md        one markdown page per manual page, captures by path
+//   captures/<file>      every referenced capture, resized (or a labelled gap)
+//   manual.html          derived: the self-contained single-page export
+//   manual-linked.html   derived: the same page referencing captures/
+//
+// The product image bakes this directory in and serves it at /docs; the public
+// plane ingests pages/*.md. `ManualSpec` stays the authoring input — the
+// bundle is that spec promoted to a contract, with the captures alongside.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildManual, } from "./build-manual.js";
+export const BUNDLE_SCHEMA_VERSION = 1;
+const yamlString = (s) => JSON.stringify(s);
+export function buildBundle(spec, opts) {
+    const { docsRoot, outDir } = opts;
+    const provenance = { builtAt: new Date().toISOString(), ...opts.provenance };
+    mkdirSync(join(outDir, "pages"), { recursive: true });
+    const manual = buildManual(spec, {
+        docsRoot,
+        provenance,
+        assets: { dir: join(outDir, "captures"), href: "captures" },
+    });
+    const hrefs = manual.sidecarHrefs ?? {};
+    // 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);
+        return t ? `[${t.nav}](${id}.md)` : "";
+    };
+    const pageMarkdown = (p) => {
+        const head = [
+            "---",
+            `title: ${yamlString(p.title)}`,
+            `nav: ${yamlString(p.nav)}`,
+            `kind: ${p.kind}`,
+            ...(p.tag ? [`tag: ${yamlString(p.tag)}`] : []),
+            "---",
+        ];
+        const steps = p.steps.map((s, i) => `### ${String(i + 1).padStart(2, "0")} ${s.head}\n\n${s.desc}\n\n![${s.head}](${captureRef(s.slug, s.file)})`);
+        const links = p.links.map(pageLink).filter(Boolean);
+        const related = links.length ? [`${p.kind === "fn" ? "Seen in" : "Uses"}: ${links.join(", ")}`] : [];
+        return [...head, "", p.intro, "", ...steps.flatMap((s) => [s, ""]), ...related].join("\n").trimEnd().concat("\n");
+    };
+    const ov = spec.overview;
+    const overviewMarkdown = [
+        "---",
+        `title: ${yamlString(ov.headline)}`,
+        `nav: "Overview"`,
+        "kind: overview",
+        "---",
+        "",
+        ov.lead,
+        "",
+        ...(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);
+    const manifest = {
+        schemaVersion: BUNDLE_SCHEMA_VERSION,
+        brand: spec.brand,
+        title: spec.title,
+        provenance,
+        links: spec.links ?? [],
+        pages,
+        exports,
+        missing: manual.missing,
+    };
+    writeFileSync(join(outDir, "bundle.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { ...manual, manifest, outDir };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -10,6 +10,7 @@
     "./docs/path-existence": "./docs/path-existence.ts",
     "./doc-guide": "./doc-guide/doc-guide.js",
     "./doc-guide/build-manual": "./doc-guide/build-manual.js",
+    "./doc-guide/bundle": "./doc-guide/bundle.js",
     "./doc-guide/guides-config": "./doc-guide/guides-config.js",
     "./doc-guide/instance-proxy": "./doc-guide/instance-proxy.js",
     "./doc-guide/live-browser": "./doc-guide/live-browser.js"
@@ -18,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": "*"