@norskvideo/ctl-dev-kit 0.2.93 → 0.2.94

package/conventions/docs-site.md

@@ -177,9 +177,9 @@ 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. 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
+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
@@ -214,9 +214,11 @@ 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. 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.
+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

@@ -8,7 +8,7 @@
 # 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
+# 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.
@@ -50,6 +50,7 @@ on:
 
 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.
@@ -122,17 +123,28 @@ jobs:
           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.
+      # (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
-        uses: actions/cache/restore@v4
-        with:
-          path: docs/generated
-          key: docs-captures-${{ github.sha }}
-          restore-keys: docs-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

package/conventions/publish-docs.yml

@@ -319,16 +319,21 @@ jobs:
         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
+      # 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/cache/save@v4
+        uses: actions/upload-artifact@v4
         with:
+          name: docs-captures
           path: docs/generated
-          key: docs-captures-${{ github.sha }}-${{ github.run_id }}
+          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).

package/package.json

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