@norskvideo/ctl-dev-kit 0.2.3 → 0.2.4

package/conventions/check-drift.ts

@@ -21,6 +21,7 @@ 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";
+import { checkTheme } from "../docs-theme/sync.ts";
 
 export interface DriftReport {
   ok: boolean;
@@ -366,6 +367,34 @@ function verbatimProblem(
 // absent ⇒ `studio`, so existing repos are unaffected.
 export type ProductShape = "studio" | "sdk-app";
 
+/** The docs site, when a repo has one: the directory holding `astro.config.mjs`.
+ *  One name across the fleet (norsk-ctl's and the Manager's both), so the gate
+ *  can find a site without being told. */
+export const DOCS_SITE_DIR = "website";
+
+/** `<repo>/website/astro.config.mjs` — the site's existence test. A docs site is
+ *  a NESTED standalone package a repo may or may not have, which is why the
+ *  theme is gated conditionally while every other convention file is demanded
+ *  outright. */
+export function hasDocsSite(repoRoot: string): boolean {
+  return existsSync(join(repoRoot, DOCS_SITE_DIR, "astro.config.mjs"));
+}
+
+/** The shared docs theme's copies inside a repo's docs site, as gate problems.
+ *  The theme has its own writer/checker pair (docs-theme/sync.ts) because it
+ *  predates this clause and a site in THIS monorepo runs it directly; routing it
+ *  through here as well is what makes `bun run check:drift` sufficient for a
+ *  product repo, which has no second suite to hang it off. */
+export function docsThemeProblems(repoRoot: string, themeCanonical?: string): string[] {
+  if (!hasDocsSite(repoRoot)) return [];
+  const site = join(repoRoot, DOCS_SITE_DIR);
+  const { problems } = themeCanonical === undefined ? checkTheme(site) : checkTheme(site, themeCanonical);
+  // Paths are reported site-relative by the theme's own checker, so prefix them
+  // — a product repo reads them from its root — and name the repo script that
+  // fixes them, which the theme's message cannot know.
+  return problems.map((p) => `${DOCS_SITE_DIR}/${p} (\`bun run sync:drift\` rewrites it.)`);
+}
+
 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});
@@ -373,6 +402,9 @@ export interface CheckDriftOptions {
   repoName?: string;
   /** The product shape ({@link resolveShape}); a fixture passes it. Absent ⇒ `studio`. */
   shape?: ProductShape;
+  /** The canonical docs-theme directory. Defaults to this package's own, which
+   *  is what a product repo wants; a fixture passes one. */
+  themeCanonical?: string;
 }
 
 /** A product's shape from `package.json` `ctlProduct.shape`; `studio` when the
@@ -697,6 +729,13 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
     }
   }
 
+  // The docs site's theme (docs-theme/): gated only when the repo HAS a site,
+  // since that is a nested standalone package rather than a repo-root file. A
+  // site in this monorepo also runs the theme gate from its own test suite; a
+  // product repo has no such suite, so check:drift is where the copies get
+  // checked, and one clause covers both.
+  for (const p of docsThemeProblems(repoRoot, opts.themeCanonical)) push(p);
+
   for (const p of demoProblems(repoRoot, canonical.demoShim)) push(p);
 
   return { ok: problems.length === 0, problems };

package/conventions/docs-site.md

@@ -0,0 +1,185 @@
+# The product docs site (shared across all Norsk ctl product repos)
+
+What a product repo needs in order to have a **docs site** — the public manual at
+`<product>.norsk.video`, an Astro + Starlight package on the shared Norsk theme.
+This is the shared half; the per-product half is the content.
+
+Like [`docs.md`](./docs.md) and [`personas.md`](./personas.md) this is a **shipped
+reference**, not a drift-gated copy: read it from
+`node_modules/@norskvideo/ctl-dev-kit/conventions/docs-site.md`. What IS gated is
+the theme itself — see "The theme is a copy, and the gate is what makes that
+safe" below.
+
+**`create-product` renders all of it.** A repo generated by
+`bunx @norskvideo/ctl-dev-kit create-product` comes out with a `website/` that
+builds, so the rest of this document is for a repo that predates the generator,
+or for understanding what you have.
+
+## Two documentation channels, and which is which
+
+A product has two, on purpose, and they are not competing drafts:
+
+|                | **The illustrated manual** ([`docs.md`](./docs.md))       | **The docs site** (this document)                     |
+| -------------- | --------------------------------------------------------- | ----------------------------------------------------- |
+| What it is     | one hash-routed HTML page + a bundle of markdown/captures | a multi-page Starlight site                           |
+| Where it lives | `docs/generated/bundle/`, baked into the product image    | `website/`, published to `<product>.norsk.video`      |
+| How it's read  | at `/docs` on the running container, through the daemon   | on the open internet, without the product in hand     |
+| Version        | exactly the version running — that is its whole point     | the tip; it says which version it was built against   |
+| Cadence        | per image                                                 | per commit to main                                    |
+| Reader         | an operator who already has it                            | an evaluator, and anyone without a deployment to hand |
+
+The bundle is the **version-true** channel and the only channel a turnkey has
+(ADR-0012). The site is the **discoverable** channel. A product with a public
+audience wants both; a turnkey wants only the bundle and should not carry a site.
+
+## What the repo owns, and what the theme owns
+
+A site is deliberately thin. It owns **four** things:
+
+| The site's own                    | Where                         |
+| --------------------------------- | ----------------------------- |
+| its canonical origin              | `website/src/lib/site.ts`     |
+| its two names + sidebar           | `website/astro.config.mjs`    |
+| the versions it was built against | `website/src/lib/versions.ts` |
+| its content                       | `website/src/content/docs/`   |
+
+Everything else comes from the shared theme (`docs-theme/`): the palette, the
+self-hosted Geist faces, the three Starlight component overrides, the content
+schema, the favicon, and `norskDocsSite()` — the whole Astro config bar those
+four. So `astro.config.mjs` is a sidebar plus five lines:
+
+```js
+import { defineConfig } from "astro/config";
+import { norskDocsSite } from "./src/starlight.ts";
+import { PUBLIC_SITE_ORIGIN } from "./src/lib/site.ts";
+
+export default defineConfig(
+  norskDocsSite({
+    origin: PUBLIC_SITE_ORIGIN,
+    tabTitle: "Norsk",          // browser-tab suffix: the FAMILY
+    wordmark: "norsk-acme",     // masthead: the product in hand
+    buildVersions: [{ label: "norsk-acme", value: version }],
+    sidebar: [...],
+  }),
+);
+```
+
+**The two names are different on purpose.** Several Norsk manuals open in one tab
+strip, and tabs truncate, so the tab suffix is the family; the masthead names the
+binary or product the reader is holding.
+
+### The five sections
+
+    Start here · Guides · How-to · Concepts · Reference
+
+Every Norsk manual uses this top level — norsk-ctl's, the Manager's, and every
+generated product's — so a reader who has learned one can navigate the next. Who
+each section serves, in the vocabulary of [`personas.md`](./personas.md):
+
+- **Start here** — the Evaluator. What this does, and where to go next.
+- **Guides** — the Builder. One task, start to finish, in the order it is done.
+  These are the pages worth **capturing** rather than illustrating; see
+  [`docs.md`](./docs.md) for the toolchain and the `capturedAgainst` front matter
+  the theme renders at the foot of such a page.
+- **How-to** — the Administrator. Looked up, repeatedly, while running it.
+- **Concepts** — the vocabulary the rest of the manual uses. Not architecture.
+- **Reference** — the Integrator. Exhaustive and generated from the source of
+  truth where possible.
+
+Add sections below these if a product genuinely needs them. Do not rename or
+reorder these five: the shape is the shared part.
+
+## The theme is a copy, and the gate is what makes that safe
+
+The theme reaches a site as **files copied into it**, not as an import, and
+`docs-theme/README.md` has the measurement behind that: a docs site is a
+standalone package with its own install, so it cannot depend on this one — a
+`file:` dep fails on this package's own `workspace:*` deps.
+
+    website/src/starlight.ts          website/src/components/*.astro
+    website/src/custom.css            website/src/fonts/*.woff2
+    website/src/content.config.ts     website/public/favicon.png
+
+**Never hand-edit one.** A change to any of them belongs in the dev-kit, where it
+reaches every product's manual at once.
+
+- `bun run check:drift` fails when a copy has drifted, naming the file and the
+  line. It is the same gate, and the same CI job, that holds `biome.json` and the
+  shared workflows — the clause is conditional on `website/astro.config.mjs`
+  existing, so a repo without a site is not asked for one.
+- `bun run sync:drift` rewrites the copies from the installed dev-kit. The
+  nightly `sync-dev-kit.yml` runs it after bumping the pin, so a theme change
+  rolls out hands-free and only a change that genuinely breaks the site goes red.
+
+**Keeping the copies at exactly those paths is load-bearing**, not tidiness:
+Astro derives a component's scoped-style class from its path, so moving
+`Footer.astro` rewrites a class attribute on every page of the site.
+
+## Adding a site to a repo that has none
+
+`create-product` does all of this; by hand it is:
+
+1. **`website/package.json`** — a standalone package (`<name>-docs`), NOT a member
+   of the root `workspaces` array. Its dependencies are what the theme imports:
+   `astro`, `@astrojs/starlight`, `@astrojs/markdown-remark` (an _optional_ peer
+   of both, so nothing installs it for you) and `sharp`, plus `playwright` as a
+   dev dependency for pages that render a mermaid diagram.
+2. **`website/tsconfig.json`** — `{"extends": "astro/tsconfigs/strict"}`.
+3. **`website/astro.config.mjs`**, `website/src/lib/{site,versions}.ts` — the four
+   things above.
+4. **`bun run sync:drift`** to lay the theme copies down.
+5. **`website/src/content/docs/`** — at least an `index.mdx`, plus a page per
+   section.
+6. **Root `package.json` scripts** — `docs:dev`, `docs:site`, `docs:site:public`,
+   each `bun run --cwd website …`.
+7. **`.gitignore`** — `website/dist-embedded/`, `website/dist-public/`,
+   `website/.astro/`. The shared core block only knows about `dist/`.
+
+Then `bun install --cwd website` (the repo-root install does NOT cover a
+standalone package) and `bun run docs:site`.
+
+## The two builds
+
+One content collection, two outputs, selected by `ASTRO_BUILD`:
+
+| Build    | `ASTRO_BUILD` | base    | outDir          | What it is                                    |
+| -------- | ------------- | ------- | --------------- | --------------------------------------------- |
+| embedded | unset         | `/docs` | `dist-embedded` | a bundle a product binary can embed and serve |
+| public   | `public`      | `/`     | `dist-public`   | the site on its own domain                    |
+
+Content is authored with absolute `/docs/...` links — right for the embedded
+build; the public build strips the prefix in a post-build pass, because Astro does
+not base-prefix absolute links in MDX. So **write `/docs/...` links** and let the
+theme handle the other case.
+
+A product only needs the public build. The embedded one costs nothing to keep
+(the theme produces it either way) and is there for a binary that wants to serve
+its own manual offline, as `norsk-ctl` and `norsk-mgr` both do — for about 1.2 MB
+of compressed docs on a ~68 MB binary.
+
+## Publishing
+
+Per site, and none of it is needed to build or review one locally:
+
+1. **A Cloudflare Pages project**, e.g. `norsk-acme-docs`.
+2. **A custom domain** on it — `<product>.norsk.video` — and the DNS record.
+3. **API token scope.** The existing `CLOUDFLARE_API_TOKEN` is deliberately narrow
+   (Pages:Edit). It must cover the new project: widen it to all Pages projects in
+   the account, or issue a second token.
+4. **A publish step** that runs the public build and `wrangler pages deploy`. Take
+   the project name from a repo variable rather than a literal, and skip the
+   deploy with a message when it is unset — so main is green before Cloudflare
+   exists and publishes the day the variable is set.
+
+There is no shared `publish-docs-site.yml` in this package yet: the two existing
+sites publish from norsk-ctl's own monorepo workflow. The first product repo to
+publish one should bring the workflow back here and drift-gate it, the way
+`publish-docs.yml` (the bundle's) already is.
+
+## Search does not cross products
+
+Each site indexes itself (Pagefind), so a reader searching one product's manual
+does not find another's. That is accepted rather than solved: the alternative is
+one corpus and one navigation carrying six products. A hub page listing the
+products is the cheap mitigation; cross-site search is possible later and nothing
+here forecloses it.

package/conventions/sync-drift.ts

@@ -20,15 +20,18 @@
 // product surfaces as a red lint/typecheck/test — not as a silent bad copy.
 import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { checkTheme, syncTheme } from "../docs-theme/sync.ts";
 import {
   BEGIN,
   type CanonicalBytes,
   CTL_HASH_LINE,
   CTL_VERSION_LINE,
   carriesIntegrationMarker,
+  DOCS_SITE_DIR,
   END,
   GITIGNORE_BEGIN,
   GITIGNORE_END,
+  hasDocsSite,
   PRODUCT_LINE,
   PRODUCT_SENTINEL,
   type ProductShape,
@@ -260,6 +263,25 @@ function syncWithDisplay(repoRoot: string, canonical: string, r: SyncReport): vo
   chmodSync(path, 0o755);
 }
 
+// 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),
+// it only keeps an existing one's copies in step. That is what makes a theme
+// change roll out through sync-dev-kit.yml like any other convention.
+function syncDocsTheme(repoRoot: string, r: SyncReport): void {
+  if (!hasDocsSite(repoRoot)) {
+    r.skipped.push(`${DOCS_SITE_DIR}/ docs theme (no docs site)`);
+    return;
+  }
+  const site = join(repoRoot, DOCS_SITE_DIR);
+  // The report names what CHANGED, and syncTheme rewrites every copy
+  // unconditionally — so ask the gate first which ones are actually adrift. Its
+  // problems are `<site-relative path>: <reason>`.
+  const adrift = checkTheme(site).problems.map((p) => p.slice(0, p.indexOf(":")));
+  syncTheme(site);
+  for (const rel of adrift) r.written.push(`${DOCS_SITE_DIR}/${rel}`);
+}
+
 export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: ProductShape = "studio"): SyncReport {
   const r: SyncReport = { written: [], skipped: [] };
   // Shape-selected canonicals: an sdk-app's flake + checks are its own variants
@@ -310,6 +332,7 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes, shape: Pr
   syncDprint(repoRoot, canonical.dprint, r);
   syncDemoShim(repoRoot, canonical.demoShim, r);
   syncWithDisplay(repoRoot, canonical.withDisplay, r);
+  syncDocsTheme(repoRoot, r);
 
   return r;
 }

package/create-product/create-product.ts

@@ -12,7 +12,9 @@
 // The convention layer is shared verbatim across every shape.
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { syncTheme } from "../docs-theme/sync.ts";
 import { type Canon, loadAsset, loadCanon, PRODUCT_SENTINEL } from "./canon.ts";
+import { SITE_DIR as DOCS_SITE_DIR } from "./docs-site.ts";
 import { turnkey } from "./turnkey.ts";
 
 // A SHAPE is a preset over FEATURES, not a separate skeleton — the four
@@ -289,5 +291,12 @@ export function createProduct(opts: CreateProductOptions): { files: string[] } {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, file.content, { mode: file.executable ? 0o755 : 0o644 });
   }
-  return { files: plan.map((f) => f.path) };
+  // The docs site's theme files are written by the THEME'S OWN writer, not
+  // rendered here: they include two woff2 faces (a plan entry is a string), and
+  // more to the point one copier and one gate is the whole arrangement — the
+  // same `syncTheme` the drift gate's writer half calls, against the same
+  // canonical bytes `check-drift` compares. A second rendering of those bytes
+  // here is exactly the drift this package exists to stop.
+  const themeFiles = syncTheme(join(opts.dir, DOCS_SITE_DIR)).map((rel) => `${DOCS_SITE_DIR}/${rel}`);
+  return { files: [...plan.map((f) => f.path), ...themeFiles] };
 }

package/create-product/docs-site.ts

@@ -0,0 +1,316 @@
+// The product's DOCS SITE — `website/`, an Astro + Starlight package on the
+// shared theme (docs-theme/), with the five-section top level every Norsk
+// manual uses: Start here, Guides, How-to, Concepts, Reference.
+//
+// Emitted for every shape, not as a feature, because it is not optional in the
+// way an operator screen is: every product has readers. What the generator
+// writes is a SKELETON — five near-empty pages saying what belongs in each
+// section — because a site whose sections a product must invent is a site the
+// product will instead paste from somewhere else.
+//
+// Two things make this different from every other workspace here:
+//
+//   1. It is NOT in the root `workspaces` array. A docs site is a STANDALONE
+//      package with its own install, deliberately: Astro's dependency tree has
+//      no business in the product's own install, and the theme is copied rather
+//      than imported for exactly that reason (docs-theme/sync.ts has the bun
+//      error that proves it). So `bun install` at the repo root does not install
+//      it — `bun install --cwd website` does, and the generated README says so.
+//   2. Its theme files are NOT written from here. `createProduct` lays them
+//      down with the theme's own writer (`syncTheme`), so there is one copier
+//      and one gate (`bun run check:drift`, via check-drift's docsThemeProblems)
+//      rather than a second rendering of the same bytes that could drift.
+//
+// It does NOT replace the illustrated manual (conventions/docs.md): that bundle
+// is still what the image serves at `/docs` and what a public product publishes
+// nightly. The two channels and the choice between them are set out in
+// conventions/docs-site.md.
+import type { GeneratedFile, ShapeContext } from "./create-product.ts";
+
+/** The docs site's directory, and the name check-drift's gate looks for. */
+export const SITE_DIR = "website";
+
+/**
+ * What a site needs installed to build. Dictated by the theme, not by taste:
+ * `starlight.ts` imports `@astrojs/starlight`, `@astrojs/markdown-remark` and
+ * `rehype-mermaid`, and `content.config.ts` imports `astro:content`. Kept on the
+ * same versions as the two sites in the norsk-ctl monorepo so one theme is only
+ * ever exercised against one Astro major; docs-site.test.ts pins the set to the
+ * theme's own imports so a theme that grows a dependency cannot ship a site that
+ * cannot build.
+ */
+export const SITE_DEPENDENCIES: Record<string, string> = {
+  // An OPTIONAL peer of both astro and starlight, so nothing installs it for
+  // you: `starlight.ts` builds the markdown pipeline out of it (`unified()`),
+  // and a site that leaves it to hoisting is one lockfile away from a build
+  // that cannot resolve it.
+  "@astrojs/markdown-remark": "^7.3.0",
+  "@astrojs/starlight": "^0.41.3",
+  astro: "^7.1.0",
+  "rehype-mermaid": "^3.0.0",
+  // Astro's image pipeline; an optional dep of astro, declared so a build never
+  // depends on whether it was hoisted.
+  sharp: "^0.33.5",
+};
+
+/** rehype-mermaid renders a diagram by driving a real browser, so a page with a
+ *  mermaid fence needs one. Nothing else in the site does. */
+export const SITE_DEV_DEPENDENCIES: Record<string, string> = { playwright: "^1.59.0" };
+
+function packageJson(ctx: ShapeContext): string {
+  return `${JSON.stringify(
+    {
+      name: `${ctx.name}-docs`,
+      version: "0.0.1",
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "astro dev",
+        // --force clears Astro's content cache: the collection is fed by
+        // symlinks into ../docs, and a cached entry outlives the file it came
+        // from.
+        build: "astro build --force",
+        preview: "astro preview",
+      },
+      dependencies: SITE_DEPENDENCIES,
+      devDependencies: SITE_DEV_DEPENDENCIES,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+const TSCONFIG = `{
+  "extends": "astro/tsconfigs/strict"
+}
+`;
+
+function siteTs(ctx: ShapeContext): string {
+  return `/** The canonical public origin of this product's docs.
+ *
+ *  ONE value: Astro's \`site\` (which drives the sitemap and the canonical
+ *  links) and anything that checks what was published read it from here rather
+ *  than repeating a literal.
+ *
+ *  The domain is NOT live until somebody creates the Cloudflare Pages project
+ *  and the DNS record for it — see conventions/docs-site.md, "Publishing". The
+ *  value belongs here from the start so the sitemap and the canonical links are
+ *  right the day it is. */
+export const PUBLIC_SITE_ORIGIN = "https://${ctx.dashboardKey}.norsk.video";
+`;
+}
+
+const VERSIONS_TS = `/**
+ * The version this docs build was built against, rendered in the sidebar
+ * footer, so a reader can tell what the page describes.
+ *
+ * Read with node fs at build time rather than imported: the site is a
+ * standalone package outside the repo's workspaces, so it cannot import from
+ * them. \`shared/src/version.ts\` carries the same version as the runtime's own
+ * copy; the repo's package.json is the one a docs build can read.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function readProductVersion(repoRoot: string): string {
+  const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")) as { version?: string };
+  if (!pkg.version) throw new Error("docs versions: the repo's package.json has no version");
+  return pkg.version;
+}
+`;
+
+function astroConfig(ctx: ShapeContext): string {
+  return `import { fileURLToPath } from "node:url";
+import { defineConfig } from "astro/config";
+// The shared Norsk docs theme. \`src/starlight.ts\`, \`src/custom.css\`,
+// \`src/content.config.ts\`, \`src/components/\`, \`src/fonts/\` and
+// \`public/favicon.png\` are COPIES of @norskvideo/ctl-dev-kit's docs-theme,
+// rewritten by \`bun run sync:drift\` and gated by \`bun run check:drift\` —
+// never hand-edited. The dev-kit's docs-theme/README.md says why a copy and not
+// a dependency (this package is standalone: its install is its own, and a file:
+// dep on the dev-kit cannot resolve the dev-kit's workspace deps).
+import { norskDocsSite } from "./src/starlight.ts";
+import { PUBLIC_SITE_ORIGIN } from "./src/lib/site.ts";
+import { readProductVersion } from "./src/lib/versions.ts";
+
+// The repo root, one level up — the docs state the version they were built
+// against, read from the product's own files.
+const repoRoot = fileURLToPath(new URL("..", import.meta.url));
+
+export default defineConfig(
+  norskDocsSite({
+    origin: PUBLIC_SITE_ORIGIN,
+    // The BROWSER TAB suffix ("Install | Norsk") — the product FAMILY, as on
+    // every other Norsk manual, so several of them read as one family in a tab
+    // strip. The masthead below is deliberately different and names the product
+    // in hand.
+    tabTitle: "Norsk",
+    wordmark: "${ctx.name}",
+    buildVersions: [{ label: "${ctx.name}", value: readProductVersion(repoRoot) }],
+    // FIVE SECTIONS, the same top level as every other Norsk manual, so a
+    // reader who knows one can navigate this one. Keep the shape; replace the
+    // placeholder pages. What belongs in each is on the page itself, and the
+    // reader each serves is in the dev-kit's conventions/personas.md.
+    sidebar: [
+      { label: "Start here", items: [{ label: "${ctx.name}", slug: "" }] },
+      { label: "Guides", items: [{ label: "Overview", slug: "guides" }] },
+      { label: "How-to", items: [{ label: "Overview", slug: "how-to" }] },
+      { label: "Concepts", items: [{ label: "Overview", slug: "concepts" }] },
+      { label: "Reference", items: [{ label: "Overview", slug: "reference" }] },
+    ],
+  }),
+);
+`;
+}
+
+/** A placeholder page: real front matter, and prose that says what the section is
+ *  for and who reads it rather than lorem ipsum a product might ship by accident. */
+function page(title: string, description: string, body: string): string {
+  return `---
+title: "${title}"
+description: "${description}"
+---
+
+${body}`;
+}
+
+function indexMdx(ctx: ShapeContext): string {
+  return page(
+    ctx.name,
+    `What ${ctx.name} does and where to start.`,
+    `**${ctx.name}** — one paragraph saying what this product does, for someone who has just arrived and does not yet know. Lead with the capability, not the architecture.
+
+This page is the **Evaluator's** page: it answers "does this do what I need?" in a couple of minutes, and hands off to the rest of the manual.
+
+## Where to start
+
+- **See it working:** a link into [Guides](/docs/guides/), once there is a walkthrough to link to.
+- **Run it somewhere real:** a link into [How-to](/docs/how-to/).
+- **Understand the model:** [Concepts](/docs/concepts/) is the vocabulary the rest of the manual uses.
+
+The four readers this manual serves — Evaluator, Builder, Integrator, Administrator — are defined in the dev-kit's
+\`node_modules/@norskvideo/ctl-dev-kit/conventions/personas.md\`, and which of them each section is for is on that section's own page.
+`,
+  );
+}
+
+const GUIDES_MDX = page(
+  "Guides",
+  "Walkthroughs: one task, start to finish, in the order a reader does it.",
+  `A **guide** walks one task from start to finish, in the order a reader does it, and does not stop to explain alternatives. Its reader is the **Builder** — the person standing the product up for the first time.
+
+One page per task. Where the same task can be done more than one way (a CLI, a web UI, an HTTP API), each way is its own page under one navigation entry, because a reader has already chosen before they arrive.
+
+Guides are the pages worth **capturing rather than illustrating**: a walkthrough generated by a test that really ran cannot describe a screen that does not exist. The dev-kit's \`conventions/docs.md\` covers the capture toolchain, and the \`capturedAgainst\` front matter the shared theme renders at the foot of such a page.
+
+_Replace this page with the first guide, and put it in the sidebar in \`astro.config.mjs\`._
+`,
+);
+
+const HOW_TO_MDX = page(
+  "How-to",
+  "Operator tasks: install, upgrade, back up, and the contracts a host must meet.",
+  `A **how-to** answers a question an operator arrives with — install, upgrade, back up, restore, what a host must provide — and it assumes they already know why they are doing it. Its reader is the **Administrator**.
+
+The difference from Guides is the reader's state, not the format: a guide is read once, front to back, by someone learning the product; a how-to is looked up, repeatedly, by someone running it.
+
+_Replace this page with the operator runbook, and put it in the sidebar in \`astro.config.mjs\`._
+`,
+);
+
+const CONCEPTS_MDX = page(
+  "Concepts",
+  "The vocabulary the rest of this manual uses.",
+  `**Concepts** is the vocabulary — the nouns this product deals in, what each one is, and how they relate. It is not architecture, and it is not a tour of the implementation: a reader comes here because a word in a guide meant nothing to them.
+
+Keep it to terms that appear elsewhere in the manual. A concept nothing else references is a sign the section is documenting the code rather than the product.
+
+_Replace this page with the model, and put its pages in the sidebar in \`astro.config.mjs\`._
+`,
+);
+
+const REFERENCE_MDX = page(
+  "Reference",
+  "Exhaustive, look-up-able: the API, the configuration, the limits.",
+  `**Reference** is the exhaustive, look-up-able material — the HTTP API, every configuration field, the limits. Its reader is the **Integrator**, who is writing something against this product and needs the whole surface rather than a path through it.
+
+Reference pages are the ones worth generating from the source of truth (an OpenAPI document, a schema) rather than writing by hand, because a hand-written reference is wrong the first time the surface changes.
+
+_Replace this page with the real reference, and put it in the sidebar in \`astro.config.mjs\`._
+`,
+);
+
+function readmeMd(ctx: ShapeContext): string {
+  return `# ${ctx.name} docs site
+
+The public manual for ${ctx.name}, an [Astro](https://astro.build) +
+[Starlight](https://starlight.astro.build) site on the **shared Norsk docs
+theme**. \`https://${ctx.dashboardKey}.norsk.video\` once it is published; until
+then it builds and is read locally.
+
+## Working on it
+
+This is a **standalone package** — its own install, outside the repo's
+workspaces, because Astro's dependency tree has no business in the product's
+install. So the repo-root \`bun install\` does not cover it:
+
+\`\`\`
+bun install --cwd website     # once
+bun run docs:dev              # dev server, hot reload
+bun run docs:site             # build (base /docs, into website/dist-embedded)
+bun run docs:site:public      # build for the public domain (into website/dist-public)
+\`\`\`
+
+## What is this site's, and what is the theme's
+
+This site owns four things, all in \`website/astro.config.mjs\` and
+\`website/src/lib/\`: its origin, its two names (the browser-tab suffix and the
+masthead wordmark), its sidebar, and the version rows in the sidebar footer.
+Its content is \`website/src/content/docs/\`.
+
+Everything else — the palette, the fonts, the component overrides, the content
+schema, the two-build shape — is the **shared theme**, and reaches this repo as
+COPIES: \`src/starlight.ts\`, \`src/custom.css\`, \`src/content.config.ts\`,
+\`src/components/\`, \`src/fonts/\` and \`public/favicon.png\`. Do not hand-edit
+them: \`bun run check:drift\` fails when they drift from the installed
+\`@norskvideo/ctl-dev-kit\`, and \`bun run sync:drift\` rewrites them. A styling
+change belongs in the dev-kit, where it reaches every product's manual at once.
+
+\`node_modules/@norskvideo/ctl-dev-kit/conventions/docs-site.md\` is the full contract — the five
+sections, the two builds, publishing, and how this site relates to the
+illustrated manual the image serves at \`/docs\`.
+`;
+}
+
+export function docsSiteFiles(ctx: ShapeContext): GeneratedFile[] {
+  return [
+    { path: `${SITE_DIR}/package.json`, content: packageJson(ctx) },
+    { path: `${SITE_DIR}/tsconfig.json`, content: TSCONFIG },
+    { path: `${SITE_DIR}/astro.config.mjs`, content: astroConfig(ctx) },
+    { path: `${SITE_DIR}/README.md`, content: readmeMd(ctx) },
+    { path: `${SITE_DIR}/src/lib/site.ts`, content: siteTs(ctx) },
+    { path: `${SITE_DIR}/src/lib/versions.ts`, content: VERSIONS_TS },
+    { path: `${SITE_DIR}/src/content/docs/index.mdx`, content: indexMdx(ctx) },
+    { path: `${SITE_DIR}/src/content/docs/guides/index.mdx`, content: GUIDES_MDX },
+    { path: `${SITE_DIR}/src/content/docs/how-to/index.mdx`, content: HOW_TO_MDX },
+    { path: `${SITE_DIR}/src/content/docs/concepts/index.mdx`, content: CONCEPTS_MDX },
+    { path: `${SITE_DIR}/src/content/docs/reference/index.mdx`, content: REFERENCE_MDX },
+  ];
+}
+
+/** Astro's build output and cache — gitignored, since the repo-root core block
+ *  only knows about `dist/`. */
+export const DOCS_SITE_GITIGNORE = `# The docs site (website/) is a standalone Astro package: its own install, and
+# two builds (base /docs for a bundle a binary can embed, / for the public site).
+${SITE_DIR}/dist-embedded/
+${SITE_DIR}/dist-public/
+${SITE_DIR}/.astro/
+`;
+
+/** 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`,
+};

package/create-product/turnkey.ts

@@ -14,6 +14,7 @@
 // validate(), INVARIANTS + parity + byte-snapshot + studio-load wired into
 // test:unit, and an image smoke tier.
 import { type GeneratedFile, type ShapeContext, type ShapeModule, studioPackage } from "./create-product.ts";
+import { DOCS_SITE_GITIGNORE, DOCS_SITE_SCRIPTS, docsSiteFiles } from "./docs-site.ts";
 import {
   COMPONENTS_GITIGNORE,
   componentsFiles,
@@ -188,6 +189,32 @@ fresh image and checks the pins before relaunching.
 6. \`bun run docs:handover\` — once a daemon has this product added; fills the
    handover's generated block from the launch truth.
 
+## The docs site (\`website/\`)
+
+A **standalone package**, deliberately outside the root \`workspaces\` array:
+Astro's dependency tree has no business in the product's install. Two
+consequences that bite in that order —
+
+- \`bun install\` at the root does NOT install it. \`bun install --cwd website\`
+  does, once; then \`bun run docs:dev\` / \`bun run docs:site\`.
+- \`website/src/starlight.ts\`, \`website/src/custom.css\`,
+  \`website/src/content.config.ts\`, \`website/src/components/\`,
+  \`website/src/fonts/\` and \`website/public/favicon.png\` are **copies of the
+  dev-kit's shared theme**, not this repo's files. \`bun run check:drift\`
+  fails on a hand-edited one; \`bun run sync:drift\` rewrites them. A styling or
+  layout change belongs in the dev-kit, where it reaches every product's manual.
+
+This repo owns four things: the origin (\`website/src/lib/site.ts\`), the two
+names and the sidebar (\`website/astro.config.mjs\`), and the content
+(\`website/src/content/docs/\`). Keep the five top-level sections — Start here,
+Guides, How-to, Concepts, Reference — they are what make several Norsk manuals
+navigable by one reader. The placeholder pages say what belongs in each.
+
+It is NOT the bundle the image serves at /docs (\`bun run docs:manual\`); both
+channels exist on purpose, and the dev-kit's
+\`node_modules/@norskvideo/ctl-dev-kit/conventions/docs-site.md\` says which to
+reach for.
+
 ## Version pins
 
 Media + Studio container tags derive from **\`manifest.seed.json\`** (the
@@ -273,6 +300,9 @@ function rootPackageJson(ctx: ShapeContext): string {
         "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: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
+        // own: `bun install --cwd website` before the first build.
+        ...DOCS_SITE_SCRIPTS,
         "sync:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/sync-drift.ts",
         // codegen first: components/_gen/types.ts is gitignored build output,
         // so on a clean checkout tsc has nothing to resolve against without it.
@@ -1880,6 +1910,7 @@ ${optional}- \`backend/\` — the control-plane service (manifest, product-templ
 - \`examples/\` — starter configs; \`examples/default/input.json\` is the default template.
 - \`tests/\` — unit, image and demo tiers; \`tests/demo.spec.ts\` is the customer journey.
 - \`docs/\` — reader-facing documents; \`docs/README.md\` is the index.
+- \`website/\` — the public docs site (Astro + Starlight on the shared Norsk theme).
 - \`deployment/\` — the image build wrapper and the iterate loop.
 
 ## First run
@@ -1903,11 +1934,20 @@ norsk-ctl and the pinned Norsk SDK:
 
 ## Documentation
 
-\`bun run docs:manual\` builds the docs bundle from \`docs/handover.md\` and
-\`docs/known-limitations.md\`; the image build runs it, so every image serves
-them at /docs (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 product added; CI runs its \`--check\`.
+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
+  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
+  product added; CI runs its \`--check\`.
+- **The docs site**, \`website/\` — the public manual on the shared Norsk theme,
+  five sections deep, faster-moving and readable without the product in hand.
+  \`bun install --cwd website\` once, then \`bun run docs:dev\` /
+  \`bun run docs:site\`. \`website/README.md\` says what is the site's and what
+  is the theme's; the dev-kit's
+  \`node_modules/@norskvideo/ctl-dev-kit/conventions/docs-site.md\` is the contract.
 
 \`CLAUDE.md\` has the conventions and the traps.
 `;
@@ -1924,6 +1964,10 @@ served at /docs at the version that is running.
 | \`docs/handover.md\`          | the platform team deploying this product  | Deploying from the exported bundle without norsk-ctl: every mount, environment and injected setting |
 | \`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
+manual, on the shared Norsk theme, not built from these files. See
+\`website/README.md\`.
+
 \`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.
@@ -2012,6 +2056,7 @@ function gitignoreTail(ctx: ShapeContext): string {
   const blocks = ["# Repo-specific entries go below (the block above is drift-gated verbatim).\n"];
   if (ctx.features.has("components")) blocks.push(COMPONENTS_GITIGNORE);
   if (ctx.features.has("dashboard")) blocks.push(DASHBOARD_GITIGNORE);
+  blocks.push(DOCS_SITE_GITIGNORE);
   return blocks.join("\n");
 }
 
@@ -2033,6 +2078,7 @@ export const turnkey: ShapeModule = {
       { path: "deployment/iterate.sh", content: iterateSh(ctx), executable: true },
       { path: "scripts/demo", content: ctx.canon.demoShim, executable: true },
       { path: "README.md", content: readmeMd(ctx) },
+      ...docsSiteFiles(ctx),
       { path: "docs/README.md", content: docsReadmeMd(ctx) },
       { path: "docs/handover.md", content: handoverMd(ctx) },
       { path: "docs/known-limitations.md", content: KNOWN_LIMITATIONS_MD },

package/docs-theme/README.md

@@ -7,6 +7,7 @@ genuinely differs — its content, its sidebar, its origin and its two names.
 
     custom.css              the palette + self-hosted Geist faces
     fonts/                  the woff2 those @font-face rules point at
+    public/favicon.png      the favicon `starlight.ts` names (copied to the site ROOT, not src/)
     components/Footer.astro    the "captured against" line on a generated guide
     components/Sidebar.astro   the "Built against" versions footer
     components/SiteTitle.astro the masthead wordmark, decoupled from the tab title
@@ -63,20 +64,43 @@ bun node_modules/@norskvideo/ctl-dev-kit/docs-theme/sync.ts check <site>
 
 `<site>` is the directory holding `astro.config.mjs`; the copies land in its
 `src/`, so this directory mirrors a site's `src/` and the path map is an
-identity. A site runs `check` in its own test suite (norsk-ctl:
+identity. The one exception is `public/`, which mirrors the site's `public/` —
+Astro serves it verbatim from the site root, and `starlight.ts` already dictates
+the favicon's path (`favicon: "/favicon.png"`), so its bytes belong here too.
+
+A site runs `check` in its own test suite (norsk-ctl:
 `website/tests/theme-drift.test.ts`, which `bun run check` runs), so a
-hand-edited copy fails before it is published.
+hand-edited copy fails before it is published. A PRODUCT repo has no such suite;
+there, `conventions/check-drift.ts` runs the same check as part of
+`bun run check:drift`, and `sync-drift.ts` rewrites the copies as part of
+`bun run sync:drift` — see below.
 
 **Keeping the copies at those exact paths is load-bearing.** Astro derives a
 component's scoped-style class from its path, so moving `Footer.astro` rewrites
 a class attribute on every page of the site.
 
-## Not yet
+## The two gates are one gate
+
+`conventions/check-drift.ts` gains a clause when — and only when — the repo has a
+site: `hasDocsSite()` tests for `website/astro.config.mjs`, and
+`docsThemeProblems()` routes this directory's `checkTheme` into the same report as
+`biome.json` and the shared workflows. `conventions/sync-drift.ts` is the writer
+half, so `sync-dev-kit.yml` rolls a theme change out to every product hands-free
+like any other convention. The site directory is `website/` across the fleet
+(`DOCS_SITE_DIR`).
+
+A site inside THIS monorepo still runs `sync.ts check` from its own test suite,
+because it has one and because `bun run check` is what a monorepo contributor
+runs; a product repo has no second suite, which is why the clause exists.
+
+## `create-product` renders a site
+
+Every generated repo comes out with a `website/` on this theme, five sections
+deep, that builds — `create-product/docs-site.ts`. Two notes on how:
 
-- **`conventions/check-drift.ts` does not know about this directory.** Its gate
-  runs at a product repo's root against files at fixed repo-root paths; a docs
-  site is a nested package a repo may or may not have. When the first product
-  repo outside this monorepo grows a site, the two gates should become one —
-  `check-drift` gaining a "if `website/astro.config.mjs` exists, check the theme"
-  clause is the obvious shape.
-- **`create-product` does not render a site.** No generated repo has one yet.
+- the theme files are written by **this directory's `syncTheme`**, called from
+  `createProduct` after the plan is written, not re-rendered by the generator: one
+  copier, one gate, and the woff2 faces are not strings;
+- what a product repo needs in order to have a site at all — the five sections,
+  the two builds, publishing, and how the site relates to the illustrated manual
+  the image serves — is `conventions/docs-site.md`.

package/docs-theme/sync.ts

@@ -30,10 +30,17 @@
  *
  * The copies land at the paths Starlight and Astro already expect
  * (`src/custom.css`, `src/components/*.astro`, `src/content.config.ts`), which
- * is also why the canonical directory mirrors a site's `src/`: the map below is
- * an identity. Keeping the component paths identical is load-bearing for more
- * than tidiness — Astro derives a component's scoped-style class from its path,
- * so moving one rewrites a class attribute on every page.
+ * is also why the canonical directory mirrors a site's own tree: the map below
+ * is an identity. Keeping the component paths identical is load-bearing for
+ * more than tidiness — Astro derives a component's scoped-style class from its
+ * path, so moving one rewrites a class attribute on every page.
+ *
+ * One canonical subdirectory is NOT under `src/`: `public/` mirrors the site's
+ * `public/`, because `starlight.ts` already names the favicon
+ * (`favicon: "/favicon.png"`) and a path the theme dictates whose bytes each
+ * site supplies for itself is half a convention. Both sites' copies were
+ * byte-identical when it moved here, so the gate gained a file rather than the
+ * sites gaining a difference.
  *
  * Canonical bytes are resolved relative to THIS file, so the script works both
  * workspace-symlinked and installed from the published tarball — the same
@@ -48,11 +55,21 @@ const CANONICAL = dirname(fileURLToPath(import.meta.url));
 /** The site subdirectory the canonical tree is copied into. */
 export const SITE_DIR = "src";
 
+/** The one canonical subdirectory that mirrors the site's root, not its `src/`
+ *  — Astro serves `public/` verbatim, and `starlight.ts` names `/favicon.png`. */
+export const PUBLIC_DIR = "public";
+
+/** Where a canonical file lands in a site, relative to the site root. */
+export function sitePath(rel: string): string {
+  return rel === PUBLIC_DIR || rel.startsWith(`${PUBLIC_DIR}/`) ? rel : join(SITE_DIR, rel);
+}
+
 /**
  * Every canonical file, as a path relative to this directory — which is also
- * its path relative to the site's `src/`. Derived from the tree rather than
- * listed, so a file added here reaches every site without a second edit; the
- * script's own source and its test are the only exclusions.
+ * its path relative to the site's `src/` ({@link sitePath}, bar `public/`).
+ * Derived from the tree rather than listed, so a file added here reaches every
+ * site without a second edit; the script's own source and its test are the only
+ * exclusions.
  */
 export function themeFiles(canonical: string = CANONICAL): string[] {
   const out: string[] = [];
@@ -84,17 +101,17 @@ const RESYNC = "Edit the dev-kit source and re-run `sync`, never hand-edit the c
 export function checkTheme(siteRoot: string, canonical: string = CANONICAL): ThemeDrift {
   const problems: string[] = [];
   for (const rel of themeFiles(canonical)) {
-    const copy = join(siteRoot, SITE_DIR, rel);
+    const at = sitePath(rel);
     const want = readFileSync(join(canonical, rel));
     let got: Buffer;
     try {
-      got = readFileSync(copy);
+      got = readFileSync(join(siteRoot, at));
     } catch {
-      problems.push(`${SITE_DIR}/${rel}: missing — the docs theme is not synced. ${RESYNC}`);
+      problems.push(`${at}: missing — the docs theme is not synced. ${RESYNC}`);
       continue;
     }
     if (got.equals(want)) continue;
-    problems.push(`${SITE_DIR}/${rel}: ${firstDiff(got, want)}. ${RESYNC}`);
+    problems.push(`${at}: ${firstDiff(got, want)}. ${RESYNC}`);
   }
   return { ok: problems.length === 0, problems };
 }
@@ -117,10 +134,11 @@ function firstDiff(got: Buffer, want: Buffer): string {
 export function syncTheme(siteRoot: string, canonical: string = CANONICAL): string[] {
   const written: string[] = [];
   for (const rel of themeFiles(canonical)) {
-    const to = join(siteRoot, SITE_DIR, rel);
+    const at = sitePath(rel);
+    const to = join(siteRoot, at);
     mkdirSync(dirname(to), { recursive: true });
     cpSync(join(canonical, rel), to);
-    written.push(`${SITE_DIR}/${rel}`);
+    written.push(at);
   }
   return written;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",