@norskvideo/ctl-dev-kit 0.2.92 → 0.2.93

package/conventions/docs-site.md

@@ -176,12 +176,14 @@ ln -s ../../../../../docs/generated/<slug> website/src/content/docs/guides/<slug
 ```
 
 `docs:site` runs the dev-kit's `docs/guide-stubs.ts stub` first, so the site
-builds on a checkout that has never captured; `publish-docs-site.yml` runs
-`guide-stubs.ts check` after the build and refuses to deploy while any guide
-is still a placeholder. That refusal is deliberate: a product that declares
-recorded guides must also restore (or regenerate) its captures in that
-workflow before the build, and until it does, the publish stops rather than
-shipping an empty page.
+builds on a checkout that has never captured. The captures come from the
+product's nightly `publish-docs.yml`, which saves `docs/generated` to the
+Actions cache after a passing engine tier; `publish-docs-site.yml` restores
+the newest set before its build (and runs when `publish-docs` completes, so a
+fresh capture publishes without waiting for a push). It then runs
+`guide-stubs.ts check` and refuses to deploy while any guide is still a
+placeholder: until the guide has been captured once, the publish stops rather
+than shipping an empty page.
 
 ## The two builds
 
@@ -211,9 +213,10 @@ holds the copy byte-identical, and `bun run sync:drift` writes it — creating i
 where the repo has a site and is not a turnkey. On every push to `main` (and on
 demand) it installs `website/`, builds the public variant and deploys
 `website/dist-public` to Cloudflare Pages with `wrangler`. It never cancels a
-run in flight, because a cancelled deploy is a half-published site. It restores
-no capture cache: a product site builds from the committed prose, so there is
-nothing a nightly run would have that a push does not.
+run in flight, because a cancelled deploy is a half-published site. Before the
+build it restores the newest recorded-guide captures from the Actions cache
+(`docs-captures-*`, saved by `publish-docs.yml`); a site with no recorded
+guides restores nothing it reads, and builds from its committed prose.
 
 Where it may exist is the gate's business (ADR-0012, and the documentation
 plan): a repo with `website/astro.config.mjs` may carry it; a repo without a

package/conventions/publish-docs-site.yml

@@ -4,12 +4,14 @@
 #
 # This is the SITE channel, not the bundle: publish-docs.yml / build-docs.yml
 # regenerate the illustrated manual the product image serves at /docs, nightly,
-# from a licensed Docker run. The site builds from the committed prose alone,
-# needs no licence and no Docker, and so rides every push (conventions/
-# docs-site.md, "Two documentation channels"). A site that also symlinks
-# RECORDED guides (website/src/content/docs/guides/<slug> -> docs/generated/<slug>)
-# builds against a placeholder when the capture is absent, and the gate below
-# refuses to deploy one.
+# from a licensed Docker run. The site needs no licence and no Docker, and so
+# rides every push (conventions/docs-site.md, "Two documentation channels").
+# A site that also symlinks RECORDED guides (website/src/content/docs/guides/
+# <slug> -> docs/generated/<slug>) publishes them from the captures that nightly
+# run saves to the Actions cache: they are restored before the build, which
+# stubs only a guide never captured, and the gate below refuses to deploy a
+# stub. So the site also runs when publish-docs completes, to publish a fresh
+# capture without waiting for the next push.
 #
 # This workflow is SINGLE-SOURCED in @norskvideo/ctl-dev-kit
 # (conventions/publish-docs-site.yml) and copied verbatim: there is no per-repo
@@ -40,6 +42,11 @@ on:
   push:
     branches: [main]
   workflow_dispatch:
+  # a fresh capture of the recorded guides (publish-docs.yml saves it)
+  workflow_run:
+    workflows: [publish-docs]
+    types: [completed]
+    branches: [main]
 
 permissions:
   contents: read
@@ -114,6 +121,19 @@ jobs:
         with:
           clean: true
 
+      # The recorded guides' captures, from the product's nightly capture run
+      # (publish-docs.yml saves docs/generated after a passing engine tier):
+      # the newest set, restored where docs:site:public expects it. None yet --
+      # a site that records no guides, or before the first capture -- restores
+      # nothing; the build stubs what is missing and the gate below refuses to
+      # deploy a stub.
+      - name: Restore the recorded guides' captures
+        uses: actions/cache/restore@v4
+        with:
+          path: docs/generated
+          key: docs-captures-${{ github.sha }}
+          restore-keys: docs-captures-
+
       # website/ is a STANDALONE package -- its own bun.lock, outside the root
       # workspaces -- so the repo-root install never covers it, and the build
       # needs both: the root for @norskvideo/ctl-dev-kit (docs:site:public stubs
@@ -145,8 +165,9 @@ jobs:
       # be replaced with "run the doc-guide locally", and nothing else would
       # notice -- the build is green, the links resolve. --content reads the
       # guides the site declares by symlink, so a site that declares none has
-      # nothing to refuse; one that does needs its captures on the runner, and
-      # until the repo restores them this step says which pages are missing.
+      # nothing to refuse; one that does needs its captures, restored above,
+      # and until the nightly run has captured them this step says which pages
+      # are missing.
       - name: Refuse to publish placeholder guides
         run: |
           nix develop .#build --command bash -c '

package/conventions/publish-docs.yml

@@ -318,6 +318,18 @@ jobs:
         if: ${{ steps.engine.outcome == 'success' }}
         run: nix develop .#build --command bun run docs:manual
 
+      # The captures, for the product's own docs site: publish-docs-site.yml
+      # restores the newest set, so its recorded guides publish from this run,
+      # the only one that can make them. Only after a passing engine tier, so a
+      # site never takes a half-captured set over the last good one. Each run
+      # its own key: a cache entry is never overwritten.
+      - name: Cache the guide captures for the docs site
+        if: ${{ steps.engine.outcome == 'success' }}
+        uses: actions/cache/save@v4
+        with:
+          path: docs/generated
+          key: docs-captures-${{ github.sha }}-${{ github.run_id }}
+
       # Said three ways, so a failure is never silent: a warning on the run, a
       # line in its summary, and the cell's detail (the notify job).
       - name: Report the engine tier (not gating)

package/package.json

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