@norskvideo/ctl-dev-kit 0.2.92 → 0.2.94

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 keeps `docs/generated` as the
+`docs-captures` artifact after a passing engine tier; `publish-docs-site.yml`
+downloads the newest one 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,12 @@ 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 downloads the newest recorded-guide captures (the `docs-captures`
+artifact `publish-docs.yml` keeps for 30 days, not the Actions cache, whose
+entries are versioned by a compression that varies across runners); 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 keeps as an artifact: 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,9 +42,15 @@ 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
+  actions: read # the newest docs-captures artifact, from the capture run
 
 # Never cancel in flight: a cancelled `wrangler pages deploy` is a half-published
 # site, and the next push rebuilds from the same inputs anyway. Queue instead.
@@ -114,6 +122,30 @@ jobs:
         with:
           clean: true
 
+      # The recorded guides' captures, from the product's nightly capture run
+      # (publish-docs.yml keeps docs/generated as the docs-captures artifact
+      # after a passing engine tier): the newest unexpired one, put 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. gh comes from the
+      # build shell (the runners have no system gh).
+      - name: Restore the recorded guides' captures
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            run="$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=docs-captures&per_page=20" \
+              --jq "[.artifacts[] | select(.expired | not)][0].workflow_run.id // empty")"
+            if [ -z "$run" ]; then
+              echo "no docs-captures artifact yet: nothing to restore"
+              exit 0
+            fi
+            mkdir -p docs/generated
+            gh run download "$run" --repo "$GITHUB_REPOSITORY" --name docs-captures --dir docs/generated
+            echo "restored the recorded guides captured by run $run"
+          '
+
       # 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 +177,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,23 @@ 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
+      # downloads the newest docs-captures artifact, 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. An artifact, not actions/cache: a cache entry is
+      # versioned by its compression, and the runner pool mixes machines with
+      # and without zstd, so a save on one never matched a restore on another
+      # (relay, 2026-10-21: saved on ashton-nuc, missed on test2-runner-1).
+      - name: Keep the guide captures for the docs site
+        if: ${{ steps.engine.outcome == 'success' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-captures
+          path: docs/generated
+          retention-days: 30
+          if-no-files-found: error
+
       # 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.94",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",