From 811914e956c21be665275fd06dd978ad1487fa0f Mon Sep 17 00:00:00 2001
From: Tom Cobb <tom.cobb@diamond.ac.uk>
Date: Tue, 30 Jun 2026 15:20:38 +0000
Subject: [PATCH 1/2] publish: inline gather/extract bash, simplify gather with
 priority-overwrite model
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces assemble/assemble.sh with inline bash steps in publish.yml's deploy job
and restructures the gather phase around a "maximally gather, overwriting with higher
priority" model (releases → branch CI → current build).

Key changes:
- Delete assemble/assemble.sh; all gh/unzip/mv IO lives as named steps in publish.yml
- Seed release stored as $DEFAULT.zip (not skipped) so the overwrite chain supersedes it
- Combine default-branch and PR gather into one step with a shared gather_run() helper
  that does the API lookup + download in one call, using the workflow filename (ci.yml)
  consistently via the /actions/workflows/ci.yml/runs endpoint
- Download this run's docs artifact and Stage current build are now adjacent, share the
  same if: guard, and the current build wins by being placed last in the gather dir
- Remove guard-default-branch input: missing DEFAULT now always hard-fails (at the new
  Ensure default-branch zip step) rather than being suppressible
- assemble.mjs and docs updated to reflect the new gather model

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/CONTRIBUTING.md           |  14 --
 .github/workflows/publish.yml     | 168 ++++++++++++++++++------
 CLAUDE.md                         |  68 +++++-----
 assemble/assemble.mjs             |  23 ++--
 assemble/assemble.sh              | 210 ------------------------------
 docs/explanations/architecture.md |  55 ++++----
 docs/reference/workflows.md       |  43 +++---
 7 files changed, 220 insertions(+), 361 deletions(-)
 delete mode 100755 assemble/assemble.sh

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index a2f17bd..f289b3b 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -18,20 +18,6 @@ so edits are reflected on rebuild.
 **Browser caveat:** `<select>` popups don't open in the VS Code Simple Browser. Open
 the forwarded port in a real browser and hard-reload (MyST caches the localised esm).
 
-## Running assemble locally
-
-`assemble/assemble.sh` (run directly by `publish.yml`) is also runnable standalone so
-the `gh` plumbing can be exercised outside CI:
-
-```bash
-REPO=DiamondLightSource/myst-version-switcher-plugin GH_TOKEN=$(gh auth token) \
-  assemble/assemble.sh
-```
-
-The pure logic (ordering, prerelease detection, `switcher.json`/redirect rendering,
-the required-branch guard) lives in `assemble/assemble.mjs` and is unit-tested
-(`npm test`) without git, the network, or the filesystem.
-
 ## Releasing
 
 Releases are cut by pushing a tag (the UI "publish a release" flow can't attach the
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index af6d7f0..ce4afed 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -21,16 +21,16 @@ name: Publish
 #                  why the shim (not this engine) is the dispatch target.
 #   warn         — a FORK PR. Read-only token, never deploys; just surfaces the opt-in hint.
 #
-# The assemble logic is THIS repo's assemble/assemble.sh (+ assemble.mjs); we run it
-# directly rather than wrap it in a composite action. To version-match the scripts to
-# this workflow, we check out the reusable workflow's OWN repo at its OWN commit via the
-# `job` context: unlike github.workflow_* (which resolve to the CALLER's entry workflow),
+# The assemble logic is THIS repo's assemble.mjs (the pure kernel); the IO plumbing
+# lives as inline steps in this file. To version-match assemble.mjs to this workflow,
+# we check out the reusable workflow's OWN repo at its OWN commit via the `job` context:
+# unlike github.workflow_* (which resolve to the CALLER's entry workflow),
 # `job.workflow_repository` + `job.workflow_sha` resolve to the file that defines THIS
 # job — i.e. the reusable workflow at the ref a consumer pinned `publish.yml@<ref>` to.
-# So the scripts always match the workflow version, with no hardcoded repo and no manual
-# release-time bump. assemble.mjs runs `git tag` in the cwd, so the CONSUMER's repo is
-# checked out at the root (with tags) to supply their version list; the scripts come
-# from .mvs.
+# So assemble.mjs always matches the workflow version, with no hardcoded repo and no
+# manual release-time bump. assemble.mjs runs `git tag` in the cwd, so the CONSUMER's
+# repo is checked out at the root (with tags) to supply their version list; assemble.mjs
+# comes from .mvs.
 on:
   workflow_call:
     inputs:
@@ -39,14 +39,6 @@ on:
         required: false
         default: ""
         type: string
-      guard-default-branch:
-        description: >-
-          'true' (default) → hard-fail if the consumer's default branch is absent from
-          the assembled site (its build artifact expired). Set 'false' while a repo's
-          default branch is not yet publishing docs.zip (e.g. mid-migration).
-        required: false
-        default: "true"
-        type: string
       pr:
         description: External fork PR number to approve (pins its head SHA) and preview.
         required: false
@@ -97,6 +89,12 @@ jobs:
     concurrency:
       group: pages
       cancel-in-progress: false
+    env:
+      REPO: ${{ github.repository }}
+      DEFAULT: ${{ github.event.repository.default_branch }}
+      SITE: ${{ runner.temp }}/site
+      SEED_TAG: pages-default-seed
+      SOURCES_DIR: _sources
     steps:
       # The CONSUMER's repo, at the root cwd: assemble.mjs runs `git tag` here to
       # order that repo's deployed versions, so it needs their tags (fetch-depth: 0).
@@ -105,10 +103,10 @@ jobs:
           fetch-depth: 0
 
       # THIS reusable workflow's repo + commit (the `job` context resolves to the
-      # reusable file, not the caller), so the assemble scripts match the ref the
-      # consumer pinned publish.yml@<ref> to — automatically, no version bump.
+      # reusable file, not the caller), so assemble.mjs matches the ref the consumer
+      # pinned publish.yml@<ref> to — automatically, no version bump.
       # Sparse: only assemble/ is needed.
-      - name: Fetch assemble scripts
+      - name: Fetch assemble.mjs
         uses: actions/checkout@v7
         with:
           repository: ${{ job.workflow_repository }}
@@ -124,38 +122,134 @@ jobs:
         if: inputs.pr != ''
         env:
           GH_TOKEN: ${{ github.token }}
-          REPO: ${{ github.repository }}
-          PR: ${{ inputs.pr }}
         run: |
           set -euo pipefail
-          sha=$(gh pr view "$PR" --repo "$REPO" --json headRefOid -q .headRefOid)
+          sha=$(gh pr view "${{ inputs.pr }}" --repo "$REPO" --json headRefOid -q .headRefOid)
           gh api --method POST "repos/$REPO/statuses/$sha" \
             -f state=success -f context=preview-approved \
             -f description="Fork docs preview approved"
 
-      # When publishing within the build's own run (workflow_call), download this
-      # run's `docs` artifact so assemble can stage it directly as version-name —
-      # the run isn't a completed success yet, so the gather can't find it (or would
-      # find a stale prior build). Skipped when version-name is "" (the dispatch paths).
+      - name: Create staging dirs
+        run: mkdir -p "$SITE" "$RUNNER_TEMP/gather"
+
+      # Releases are permanent sources; the seed release (if present) stands in for the
+      # default branch until _sources/ is established — store it as $DEFAULT.zip so the
+      # priority-overwrite chain below can supersede it with a fresher source.
+      - name: Gather release artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          tags=$(gh api --paginate "repos/$REPO/releases" \
+            -q '.[] | select(any(.assets[]; .name=="docs.zip")) | .tag_name')
+          for tag in $tags; do
+            case "$tag" in */*) continue ;; esac
+            [ "$tag" = "$DEFAULT" ] && continue
+            [ "$tag" = "$SEED_TAG" ] && dest="$DEFAULT" || dest="$tag"
+            gh release download "$tag" --repo "$REPO" -p docs.zip \
+              -O "$RUNNER_TEMP/gather/$dest.zip" \
+              || echo "::warning::release $tag download failed — skipping"
+          done
+
+      # Branch CI artifacts overwrite the seed (higher priority). Default branch: latest
+      # successful push run. PRs: internal always; external forks only when the head SHA
+      # carries a preview-approved status. No $ARTIFACT_VERSION_NAME skip — the current
+      # build (staged next) overwrites anything gathered here with the same name.
+      - name: Gather branch CI artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gather_run() {
+            local query="$1" dest="$2" label="$3"
+            local run; run=$(gh api "repos/$REPO/actions/workflows/ci.yml/runs?$query&status=success&per_page=1" \
+              -q '.workflow_runs[0].id // empty')
+            [ -n "$run" ] || return 0
+            local tmp; tmp=$(mktemp -d)
+            gh run download "$run" --repo "$REPO" -n docs -D "$tmp" \
+              && mv "$tmp/docs.zip" "$RUNNER_TEMP/gather/$dest.zip" \
+              || echo "::warning::$label artifact unavailable — skipping"
+            rm -rf "$tmp"
+          }
+          gather_run "branch=$DEFAULT&event=push" "$DEFAULT" "default-branch CI"
+          prs=$(gh pr list --repo "$REPO" --state open --limit 200 \
+            --json number,headRefOid,isCrossRepository -q '.[] | [.number, .headRefOid, .isCrossRepository] | @tsv')
+          while IFS=$'\t' read -r num sha cross; do
+            [ -z "$num" ] && continue
+            if [ "$cross" = "true" ]; then
+              approved=$(gh api "repos/$REPO/commits/$sha/statuses" \
+                -q 'any(.[]; .context=="preview-approved" and .state=="success")')
+              [ "$approved" = "true" ] || continue
+            fi
+            gather_run "head_sha=$sha" "pr-$num" "PR #$num"
+          done <<< "$prs"
+
+      # Highest priority: the current build overwrites anything gathered above.
+      # Skipped on the dispatch paths (version-name is ""), which gather purely from durable sources.
       - name: Download this run's docs artifact
         if: inputs.version-name != ''
         uses: actions/download-artifact@v8
         with:
           name: docs
-          path: ${{ runner.temp }}/assemble-current
+          path: ${{ runner.temp }}/gather-current
+      - name: Stage current build
+        if: inputs.version-name != ''
+        env:
+          ARTIFACT_VERSION_NAME: ${{ inputs.version-name }}
+        run: |
+          set -euo pipefail
+          src="$RUNNER_TEMP/gather-current/docs.zip"
+          [ -f "$src" ] || { echo "::error::in-run artifact not found at $src"; exit 1; }
+          mv "$src" "$RUNNER_TEMP/gather/$ARTIFACT_VERSION_NAME.zip"
 
-      # Run the assemble script directly (cwd = the consumer's checkout, so its
-      # `git tag` sees the consumer's tags). The script self-locates assemble.mjs and
-      # writes `dir=<site>` to $GITHUB_OUTPUT.
-      - name: Assemble versioned site
-        id: site
+      # Final fallback: if no prior step provided $DEFAULT.zip, try the durable in-site
+      # copy. Hard-fail if it isn't there — a deploy missing the default branch is a hole.
+      - name: Ensure default-branch zip
         env:
           GH_TOKEN: ${{ github.token }}
-          REPO: ${{ github.repository }}
-          GUARD_DEFAULT_BRANCH: ${{ inputs.guard-default-branch }}
-          ARTIFACT_VERSION_NAME: ${{ inputs.version-name }}
-          ARTIFACT_ZIP: ${{ inputs.version-name != '' && format('{0}/assemble-current/docs.zip', runner.temp) || '' }}
-        run: bash "$GITHUB_WORKSPACE/.mvs/assemble/assemble.sh"
+        run: |
+          set -euo pipefail
+          [ -f "$RUNNER_TEMP/gather/$DEFAULT.zip" ] && exit 0
+          owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]')
+          pages_url="https://$owner.github.io/${REPO#*/}"
+          if curl -fsSL "$pages_url/$SOURCES_DIR/$DEFAULT.zip" \
+              -o "$RUNNER_TEMP/gather/$DEFAULT.zip" 2>/dev/null; then
+            echo "::notice::$DEFAULT restored from durable in-site copy ($pages_url/$SOURCES_DIR/$DEFAULT.zip)"
+          else
+            echo "::error::$DEFAULT: not provided by current build, releases, branch CI, or durable in-site copy — deploy aborted"
+            exit 1
+          fi
+
+      # Unzip every gathered zip into SITE/<version-name>.
+      # Persist the default-branch zip into SITE/_sources/ for future recovery.
+      - name: Extract artifacts into site
+        run: |
+          set -euo pipefail
+          for f in "$RUNNER_TEMP/gather"/*.zip; do
+            [ -f "$f" ] || continue
+            name=$(basename "$f" .zip)
+            tmp=$(mktemp -d)
+            unzip -q "$f" 'html/*' -d "$tmp" 2>/dev/null && [ -d "$tmp/html" ] \
+              && { rm -rf "$SITE/$name"; mv "$tmp/html" "$SITE/$name"; } \
+              || echo "::warning::$name: no html/ root in zip — skipping"
+            rm -rf "$tmp"
+          done
+          dzip="$RUNNER_TEMP/gather/$DEFAULT.zip"
+          [ -d "$SITE/$DEFAULT" ] && [ -f "$dzip" ] \
+            && { mkdir -p "$SITE/$SOURCES_DIR"; cp "$dzip" "$SITE/$SOURCES_DIR/$DEFAULT.zip"; }
+
+      # `generate` orders versions, writes switcher.json + index.html, and prints the
+      # stable-alias source dir (the newest release), or "" when no release is deployed yet.
+      # Hard-fails if the default branch is absent (Ensure step guarantees the zip, but
+      # the extract could still fail if the zip had no html/ root).
+      - name: Generate switcher.json and stable alias
+        id: site
+        run: |
+          set -euo pipefail
+          stable_src=$(node "$GITHUB_WORKSPACE/.mvs/assemble/assemble.mjs" generate \
+            --site-dir "$SITE" --repo "$REPO" --required "$DEFAULT")
+          [ -n "$stable_src" ] && ln -s "$stable_src" "$SITE/stable"
+          echo "dir=$SITE" >> "$GITHUB_OUTPUT"
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
diff --git a/CLAUDE.md b/CLAUDE.md
index 6d7ef85..4088d79 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,13 +10,12 @@ to `publish.yml`, not a separately consumed action.
 
 ```
 plugins/version-switcher.mjs                   # MyST directive + anywidget runtime (single file, no README — docs are in docs/)
-assemble/assemble.sh                           # INTERNAL: reconstruct the whole site from durable sources (gh/unzip plumbing); run directly by publish.yml; runnable standalone for local testing
-assemble/assemble.mjs                          # INTERNAL: dependency-free Node kernel behind assemble.sh (the `generate` subcommand)
+assemble/assemble.mjs                          # INTERNAL: dependency-free Node kernel for publish.yml's "Generate" step (the `generate` subcommand writes switcher.json + index.html)
 scripts/migrate.sh                             # operator gh-pages → durable-source migration (bash); two-phase: reversible cutover, then guarded --delete-gh-pages
 test/                                          # npm test suite (node, no framework)
 docs/                                          # this repo's own docs (dogfoods the plugin)
 .github/workflows/docs.yml                     # PUBLIC reusable: build at the versioned BASE_URL → pack docs.zip → upload `docs` artifact (workflow_call; build-command input)
-.github/workflows/publish.yml                  # PUBLIC reusable ENGINE (PRIVILEGED): branches on the event into 3 jobs — deploy (assemble@job.workflow_sha + Pages), tag-re-dispatch (re-fire the shim), fork-warn. workflow_call ONLY; reached via the publish-dispatch.yml shim
+.github/workflows/publish.yml                  # PUBLIC reusable ENGINE (PRIVILEGED): branches on the event into 3 jobs — deploy (gather+extract inline bash + assemble.mjs@job.workflow_sha + Pages), tag-re-dispatch (re-fire the shim), fork-warn. workflow_call ONLY; reached via the publish-dispatch.yml shim
 .github/workflows/publish-dispatch.yml         # PUBLIC thin shim: workflow_call (ci.yml's publish, every event) + workflow_dispatch (tag re-dispatch + fork-PR opt-in + manual re-deploy) → forwards to publish.yml. The dispatchable file consumers copy (reusable workflows can't be dispatched cross-repo)
 .github/workflows/release.yml                  # PUBLIC reusable: attach the run's build artifacts (docs.zip; + version-switcher.mjs via _test.yml) to the tag's GitHub Release via gh (create-or-upload, immutable-safe). Consumers `uses:` it directly
 .github/workflows/ci.yml                       # this repo's own entry: _lint / _test / docs.yml / release, then ONE publish job nesting publish-dispatch.yml (shim) → publish.yml for every event (publish.yml branches: deploy / tag-re-dispatch / fork-warn)
@@ -31,7 +30,7 @@ docs/                                          # this repo's own docs (dogfoods
 
 One `vX.Y.Z` tag versions both. The plugin is published as a GitHub Release asset
 (alongside the tag's `docs.zip`); the workflows are consumed by `uses:` at the same
-tag (and `publish.yml` self-checks-out its `assemble/` scripts at that tag via
+tag (and `publish.yml` self-checks-out `assemble.mjs` at that tag via
 `job.workflow_sha`). `assemble/` is internal — consumed only by `publish.yml`, not a
 public action.
 
@@ -79,38 +78,36 @@ re-dispatches the shim). One `publish` job, no ref/fork guards in `ci.yml`.
 Because the inline publish runs **inside the build's own CI run**, the current build
 isn't a *completed* successful run the gather can discover (and for a main push the
 gather would find the *previous* build). So `ci.yml` passes `publish.yml` the build's
-version name (`needs.docs.outputs.version-name`); `publish.yml` hands it to assemble
-as `ARTIFACT_VERSION_NAME`. `publish.yml` downloads the same-run `docs` artifact and
-`assemble.sh` unzips + stages it directly, **skipping the re-gather of that version**.
-Everything else (other releases, other open PRs, the rest) still comes from durable
-sources.
-
-`publish.yml` runs **`assemble/assemble.sh`** (checked out from this repo at
-`job.workflow_sha`, so the scripts match the workflow's own ref) to gather + generate
-+ output the site dir, then `deploy-pages`. Operator note: because internal PRs/tags now deploy from
-their **own ref** (not only the default branch), the `github-pages` environment's
+version name (`needs.docs.outputs.version-name`); `publish.yml` downloads this run's
+`docs` artifact and stages it into the gather dir as the **highest-priority** source —
+overwriting any same-name zip gathered from durable sources. Everything else (other
+releases, other open PRs, the rest) still comes from durable sources.
+
+`publish.yml`'s `deploy` job runs inline gather + extract steps, then calls
+`assemble.mjs` (checked out from this repo at `job.workflow_sha`, so the kernel
+matches the workflow's own ref) to generate + output the site dir, then
+`deploy-pages`. Operator note: because internal PRs/tags now deploy from their
+**own ref** (not only the default branch), the `github-pages` environment's
 deployment-branch policy must allow those refs (or be unrestricted) — this is the
-cost of nesting publish for visibility. Bash in `assemble` does the `gh`/`unzip`/`mv`
-IO (gather); the JS kernel does the pure logic (`generate` + the folded-in
+cost of nesting publish for visibility. Inline bash steps do the `gh`/`unzip`/`mv`
+IO (gather + extract); the JS kernel does the pure logic (`generate` + the folded-in
 `missingRequired` guard) and is unit-tested without git/network/fs. There is **no
 sanitisation**: version names are clean by construction — `main`, `pr-<number>`, or
 a tag without `/` (the `tags: ['*']` trigger never builds `/`-tags).
 
-### Self-referencing the assemble scripts (no separate action)
-`publish.yml` runs `assemble/assemble.sh` directly rather than wrapping it in a
-composite action. To version-match the scripts to the workflow, it sparse-checks-out
-**this** repo's `assemble/` at `job.workflow_repository` + `job.workflow_sha` — the
-`job` context resolves to the file that defines the running job, i.e. the *reusable*
-workflow (unlike `github.workflow_*`, which resolve to the *caller's* entry
-workflow). So a consumer pinning `publish.yml@vX` gets `assemble@vX` automatically,
-with no hardcoded repo and no release-time bump, and this repo's own publish job
-tests the working-tree scripts (no dogfood gap). The consumer's repo stays checked
-out at the root so `assemble.mjs`'s `git tag` lists *their* versions; the scripts run
-from `.mvs`. (`uses:` can't take an expression, so a composite action could only be
-pinned to a literal tag — the `job` context is the only way to self-reference at the
-running ref.) Note: actionlint's `job`-context schema is stale and false-flags
-`job.workflow_sha`/`job.workflow_repository`; the GitHub docs confirm both. This repo
-lints with biome, not actionlint.
+### Self-referencing assemble.mjs (no separate action)
+`publish.yml` sparse-checks-out **this** repo's `assemble/` at `job.workflow_repository`
++ `job.workflow_sha` — the `job` context resolves to the file that defines the running
+job, i.e. the *reusable* workflow (unlike `github.workflow_*`, which resolve to the
+*caller's* entry workflow). So a consumer pinning `publish.yml@vX` gets
+`assemble.mjs@vX` automatically, with no hardcoded repo and no release-time bump,
+and this repo's own publish job tests the working-tree script (no dogfood gap). The
+consumer's repo stays checked out at the root so `assemble.mjs`'s `git tag` lists
+*their* versions; `assemble.mjs` runs from `.mvs`. (`uses:` can't take an expression,
+so a composite action could only be pinned to a literal tag — the `job` context is
+the only way to self-reference at the running ref.) Note: actionlint's `job`-context
+schema is stale and false-flags `job.workflow_sha`/`job.workflow_repository`; the
+GitHub docs confirm both. This repo lints with biome, not actionlint.
 
 ### BASE_URL must be set before `myst build`
 ```yaml
@@ -159,10 +156,11 @@ One entry workflow (`ci.yml`) that nests the privileged publish:
 - `publish.yml` — **assemble + deploy ENGINE, privileged; owns the event branching.**
   `workflow_call` ONLY (reached via the shim). Three jobs by originating event:
   **deploy** (internal PR / default-branch push inline, or any dispatch → sparse-checks
-  out this repo's `assemble/` at `job.workflow_sha` so the scripts match the pinned ref —
-  see "Self-referencing the assemble scripts" below — runs `assemble.sh`, then
-  `upload-pages-artifact` + `deploy-pages` + verify, carrying the `github-pages`
-  environment + perms + `concurrency`), **re-dispatch** (a tag — waits for the release,
+  out `assemble.mjs` at `job.workflow_sha` so it matches the pinned ref — see
+  "Self-referencing assemble.mjs" above — runs inline gather + extract steps then
+  `assemble.mjs generate`, then `upload-pages-artifact` + `deploy-pages` + verify,
+  carrying the `github-pages` environment + perms + `concurrency`), **re-dispatch**
+  (a tag — waits for the release,
   then `gh workflow run <dispatch-workflow>` in the consumer's repo with their token, so
   the deploy lands as a `workflow_dispatch` that re-serves; a same-SHA tag deploy is
   otherwise dropped — deploy-pages#383), and **warn** (a fork PR — read-only, posts the
diff --git a/assemble/assemble.mjs b/assemble/assemble.mjs
index a441502..cdea77b 100644
--- a/assemble/assemble.mjs
+++ b/assemble/assemble.mjs
@@ -1,17 +1,16 @@
 /**
- * assemble — the logic kernel behind the `assemble` composite action.
+ * assemble.mjs — the pure logic kernel for publish.yml's "Generate" step.
  *
- * The action reconstructs the *whole* versioned docs site on every deploy from
- * durable sources (main's build, `docs.zip` release assets, open-PR CI artifacts),
- * then the publish workflow deploys it directly to GitHub Pages. Bash does the IO
- * plumbing (`gh` downloads, `unzip`, `mv`); this file is the pure-ish kernel it
- * shells into, exposed as one subcommand:
+ * publish.yml's gather steps download every version's docs.zip into a staging
+ * dir, then the extract step unzips them all into the site tree. This file is
+ * the final step: given the populated site tree it orders the versions, writes
+ * switcher.json + index.html, and prints the stable-alias source dir on stdout.
+ * Exposed as one subcommand:
  *
  *   node assemble.mjs generate --site-dir <dir> --repo <org/repo> [--required <csv>]
  *       → write switcher.json + index.html into <dir>; print the stable-alias
- *         source dir (the newest deployed release) on stdout, or nothing. Runs
- *         after all gathering, so it also exit-1s if a --required branch is
- *         absent from the site (the required-branch guard).
+ *         source dir (the newest deployed release) on stdout, or nothing. Also
+ *         exit-1s if a --required branch is absent from the site.
  *
  * The pure functions take plain data so they unit-test without git, the network,
  * or (mostly) the filesystem. Only `discoverVersions`, `getSortedTags` and the
@@ -26,9 +25,9 @@ import { parseArgs } from "node:util";
 export const STABLE_ALIAS = "stable";
 
 /**
- * The in-site durable store directory (`_sources/<default>.zip`) that assemble.sh
- * writes the default branch's docs.zip into each deploy. It is published with the
- * site but is NOT a version, so version discovery skips it.
+ * The in-site durable store directory (`_sources/<default>.zip`) persisted by
+ * publish.yml's extract step each deploy. Published with the site but NOT a
+ * version, so version discovery skips it.
  */
 export const SOURCES_DIR = "_sources";
 
diff --git a/assemble/assemble.sh b/assemble/assemble.sh
deleted file mode 100755
index 8975e0f..0000000
--- a/assemble/assemble.sh
+++ /dev/null
@@ -1,210 +0,0 @@
-#!/usr/bin/env bash
-#
-# assemble — reconstruct the whole versioned docs site from durable sources into
-# $SITE, write switcher.json + a root redirect + the stable/ alias, and print the
-# site dir. The reusable publish.yml workflow runs this directly (it checks out
-# this repo's assemble/ at the workflow's own ref); it is also runnable standalone
-# so the `gh` plumbing can be exercised locally:
-#
-#   REPO=DiamondLightSource/myst-version-switcher-plugin GH_TOKEN=$(gh auth token) \
-#     assemble/assemble.sh
-#
-# The default branch is the one version with no permanent source (releases have
-# their docs.zip Release asset; PRs are ephemeral by design) — it is gathered from
-# the latest CI run's `docs` artifact, which EXPIRES. So each deploy also persists
-# the default branch's docs.zip into the published site at `_sources/<branch>.zip`,
-# and falls back to that durable in-site copy when the fresh artifact is gone, so the
-# default branch can't silently drop out once it has built docs at least once. Before
-# that first build a migration can publish a one-time seed release ($SEED_TAG) that is
-# read as a last resort and persisted to _sources on that deploy.
-#
-# Driven by env (publish.yml passes these; set them yourself to run locally):
-#   REPO                  org/repo for gh lookups + version URLs        (required)
-#   GUARD_DEFAULT_BRANCH  'true' (default) → hard-fail if the default branch is
-#                         absent from the site; any other value disables the guard
-#   GH_TOKEN              token for gh (release assets, runs, statuses)
-#   PAGES_URL             base URL of the live Pages site, for the durable default-
-#                         branch fallback (default: https://<owner>.github.io/<repo>)
-#   SEED_TAG              published seed release tag for the default branch's docs.zip,
-#                         read once during a migration (default: pages-default-seed)
-#   SITE                  output dir (default: $RUNNER_TEMP/site, else ./_site)
-#   ARTIFACT_VERSION_NAME version name (pr-<n> | main | <tag>) to stage directly from
-#                         ARTIFACT_ZIP instead of gathering — used when publishing
-#                         inside the build's own run (the run isn't a completed
-#                         success yet). The matching gather is skipped. The action
-#                         downloads the artifact; this script unzips + stages it.
-#   ARTIFACT_ZIP          docs.zip (bare html/ root) to stage at ARTIFACT_VERSION_NAME
-#
-# Requires node + gh + unzip + curl on PATH. assemble.mjs sits next to this script.
-set -euo pipefail
-
-here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-: "${REPO:?REPO is required (org/repo)}"
-GUARD_DEFAULT_BRANCH="${GUARD_DEFAULT_BRANCH:-true}"
-ARTIFACT_VERSION_NAME="${ARTIFACT_VERSION_NAME:-}"
-ARTIFACT_ZIP="${ARTIFACT_ZIP:-}"
-if [ -n "${SITE:-}" ]; then :
-elif [ -n "${RUNNER_TEMP:-}" ]; then SITE="$RUNNER_TEMP/site"
-else SITE="$PWD/_site"
-fi
-TMP="${RUNNER_TEMP:-$(mktemp -d)}"
-
-# Live Pages URL, for the durable default-branch fallback. Default to the standard
-# project-pages URL derived from REPO (owner lowercased for the github.io subdomain);
-# override PAGES_URL for user/org pages or a custom domain.
-_owner=$(printf '%s' "${REPO%%/*}" | tr '[:upper:]' '[:lower:]'); _name=${REPO#*/}
-PAGES_URL="${PAGES_URL:-https://$_owner.github.io/$_name}"
-SOURCES_DIR="_sources"   # durable in-site store: $SITE/_sources/<default>.zip
-# A migration may publish a one-time seed release holding the default branch's
-# docs.zip (e.g. captured from gh-pages), read once to bootstrap _sources/ before the
-# branch builds docs itself. Published (a contents:read deploy can't read a draft);
-# on this sentinel tag so it never collides with a branch and is excluded as a
-# version below. scripts/migrate.sh creates it and deletes it once _sources is live.
-SEED_TAG="${SEED_TAG:-pages-default-seed}"
-
-default=$(gh repo view "$REPO" --json defaultBranchRef -q .defaultBranchRef.name)
-mkdir -p "$SITE"
-
-# Unzip a docs.zip (bare html/ root) into SITE/<dest>, replacing any prior. A
-# missing file or a docs.zip without an html/ root (e.g. a pre-cutover artifact of
-# a different shape) is a clean skip, not a hard failure.
-extract() {  # $1=zip  $2=dest dir  $3=label
-  local t="$TMP/x-$2"
-  rm -rf "$t"; mkdir -p "$t"
-  if [ -f "$1" ] && unzip -q "$1" 'html/*' -d "$t" 2>/dev/null && [ -d "$t/html" ]; then
-    rm -rf "${SITE:?}/$2"
-    mv "$t/html" "$SITE/$2"
-  else
-    echo "::warning::$3: docs.zip missing or has no html/ root — skipping"
-  fi
-  rm -rf "$t"
-}
-
-# Download a run's `docs` artifact (→ <out>/docs.zip); skip on miss (expired).
-download_run() {  # $1=runId  $2=out dir  $3=label
-  rm -rf "$2"; mkdir -p "$2"
-  if ! gh run download "$1" --repo "$REPO" -n docs -D "$2"; then
-    echo "::warning::$3 docs artifact unavailable (expired?) — skipping"
-    return 1
-  fi
-}
-
-# --- current build: unzip + stage the docs.zip publish.yml downloaded (if any) ---
-# Published inside the build's own run, so it isn't a completed success the gather
-# can discover (and a main/tag push would otherwise re-gather the PREVIOUS build).
-# Each gather below skips ARTIFACT_VERSION_NAME so nothing clobbers this fresh build.
-if [ -n "$ARTIFACT_VERSION_NAME" ]; then
-  if [ -f "$ARTIFACT_ZIP" ]; then
-    extract "$ARTIFACT_ZIP" "$ARTIFACT_VERSION_NAME" "current build '$ARTIFACT_VERSION_NAME'"
-  else
-    echo "::error::ARTIFACT_VERSION_NAME=$ARTIFACT_VERSION_NAME but ARTIFACT_ZIP=$ARTIFACT_ZIP is not a file"
-    exit 1
-  fi
-fi
-
-# --- default branch: this run's build, else latest push build, else durable copy ---
-# Track the docs.zip the default branch arrived as in `default_zip`, so the persist
-# step below can store it verbatim. For the current build it is ARTIFACT_ZIP (already
-# staged above). Otherwise try, in order: the fresh CI artifact; the docs.zip a
-# previous deploy persisted in the live site (so an artifact expiry can't silently
-# drop the branch); and finally a one-time migration seed release. The first that
-# works is staged + persisted to _sources/<default>.zip for next time.
-default_zip=""
-if [ "$default" = "$ARTIFACT_VERSION_NAME" ]; then
-  default_zip="$ARTIFACT_ZIP"
-else
-  # Try each source in turn and ACCEPT it only if it actually staged $SITE/$default.
-  # A source that downloads but yields no usable docs.zip — a pre-cutover artifact
-  # that is a bare html dir (not a docs.zip), or a docs.zip without an html/ root —
-  # must NOT stop the search: the default branch is required, so we fall through to
-  # the durable in-site copy and then the migration seed instead of failing hard.
-  # (Mid-migration the old pipeline can still upload a `docs` artifact of the wrong
-  # shape, so download success alone can't mean the branch is staged.)
-  main_run=$(gh run list --repo "$REPO" --workflow ci.yml --branch "$default" \
-    --event push --status success --limit 1 --json databaseId -q '.[0].databaseId // empty')
-  if [ -n "$main_run" ] && download_run "$main_run" "$TMP/dl-$default" "branch $default"; then
-    extract "$TMP/dl-$default/docs.zip" "$default" "branch $default"
-    if [ -d "$SITE/$default" ]; then default_zip="$TMP/dl-$default/docs.zip"; fi
-  fi
-  if [ -z "$default_zip" ] && \
-     curl -fsSL "$PAGES_URL/$SOURCES_DIR/$default.zip" -o "$TMP/durable-$default.zip" 2>/dev/null; then
-    extract "$TMP/durable-$default.zip" "$default" "branch $default (durable in-site copy)"
-    if [ -d "$SITE/$default" ]; then
-      default_zip="$TMP/durable-$default.zip"
-      echo "::notice::default branch '$default' restored from the durable in-site copy ($PAGES_URL/$SOURCES_DIR/$default.zip)"
-    fi
-  fi
-  if [ -z "$default_zip" ] && \
-     gh release download "$SEED_TAG" --repo "$REPO" -p docs.zip -O "$TMP/seed-$default.zip" 2>/dev/null; then
-    extract "$TMP/seed-$default.zip" "$default" "branch $default (migration seed)"
-    if [ -d "$SITE/$default" ]; then
-      default_zip="$TMP/seed-$default.zip"
-      echo "::notice::default branch '$default' staged from the migration seed release '$SEED_TAG' — persisted to _sources this deploy"
-    fi
-  fi
-  if [ -z "$default_zip" ]; then
-    echo "::warning::default branch '$default': no fresh CI build (with a usable docs.zip), durable in-site copy, or seed release"
-  fi
-fi
-
-# --- releases: tags whose release has a docs.zip (one paginated call) ---
-tags=$(gh api --paginate "repos/$REPO/releases" \
-  -q '.[] | select(any(.assets[]; .name=="docs.zip")) | .tag_name')
-for tag in $tags; do
-  case "$tag" in */*) continue ;; esac          # never built/published; skip
-  [ "$tag" = "$default" ] && continue
-  [ "$tag" = "$SEED_TAG" ] && continue          # migration seed → staged as the default branch, not a version
-  [ "$tag" = "$ARTIFACT_VERSION_NAME" ] && continue  # staged fresh from this run's build
-  if gh release download "$tag" --repo "$REPO" -p docs.zip -O "$TMP/rel-$tag.zip"; then
-    extract "$TMP/rel-$tag.zip" "$tag" "release $tag"
-  else
-    echo "::warning::release $tag docs.zip download failed — skipping"
-  fi
-done
-
-# --- open PRs: internal always, external forks only when approved ---
-prs=$(gh pr list --repo "$REPO" --state open --limit 200 \
-  --json number,headRefOid,isCrossRepository \
-  -q '.[] | [.number, .headRefOid, .isCrossRepository] | @tsv')
-while IFS=$'\t' read -r num sha cross; do
-  [ -z "$num" ] && continue
-  [ "pr-$num" = "$ARTIFACT_VERSION_NAME" ] && continue  # staged fresh from this run's build
-  if [ "$cross" = "true" ]; then
-    approved=$(gh api "repos/$REPO/commits/$sha/statuses" \
-      -q 'any(.[]; .context=="preview-approved" and .state=="success")')
-    [ "$approved" = "true" ] || continue       # unapproved fork → skip
-  fi
-  # The successful CI run for this PR's CURRENT head commit (empty if the latest
-  # build hasn't passed yet, or the SHA changed since approval).
-  run=$(gh api "repos/$REPO/actions/runs?head_sha=$sha&status=success" \
-    -q 'first(.workflow_runs[] | select(.name=="CI") | .id) // empty')
-  [ -n "$run" ] || continue
-  if download_run "$run" "$TMP/dl-pr-$num" "PR #$num"; then
-    extract "$TMP/dl-pr-$num/docs.zip" "pr-$num" "PR #$num"
-  fi
-done <<< "$prs"
-
-# --- persist the default branch durably in the site ($SITE/_sources/<default>.zip) ---
-# Store the docs.zip it arrived as, verbatim, so the NEXT deploy can restore the
-# default branch even once the CI artifact expires. The _sources/ dir is published
-# with the site and excluded from version discovery (see assemble.mjs).
-if [ -n "$default_zip" ] && [ -f "$default_zip" ]; then
-  mkdir -p "$SITE/$SOURCES_DIR"
-  cp "$default_zip" "$SITE/$SOURCES_DIR/$default.zip"
-fi
-
-# --- generate switcher.json + redirect + stable-alias source ---
-# `generate` discovers the gathered dirs, orders them, writes switcher.json +
-# index.html, and prints the stable-alias source dir (or nothing). It also exit-1s
-# (→ set -e) if the --required (default) branch is absent — the required-branch guard.
-required=""
-[ "$GUARD_DEFAULT_BRANCH" = "true" ] && required="$default"
-stable_src=$(node "$here/assemble.mjs" generate \
-  --site-dir "$SITE" --repo "$REPO" --required "$required")
-
-# --- stable alias: a symlink, inflated to a real copy by upload-pages-artifact ---
-[ -n "$stable_src" ] && ln -s "$stable_src" "$SITE/stable"
-
-echo "Assembled site at $SITE"
-[ -n "${GITHUB_OUTPUT:-}" ] && echo "dir=$SITE" >> "$GITHUB_OUTPUT"
diff --git a/docs/explanations/architecture.md b/docs/explanations/architecture.md
index 3d83a28..19d32cb 100644
--- a/docs/explanations/architecture.md
+++ b/docs/explanations/architecture.md
@@ -16,7 +16,7 @@ one artifact as the *entire* site, which is a whole-site-replace.
 |---|---|---|
 | current build | the build staged into the publish run via `version-name` | n/a (just built) |
 | released tags | the `docs.zip` asset attached to each **GitHub Release** | permanent |
-| default branch (e.g. `main`) | the latest CI **push** artifact, else the durable `_sources/<branch>.zip` persisted in the live site | durable (re-persisted each deploy) |
+| default branch (e.g. `main`) | the latest CI **push** artifact, else the durable `_sources/<branch>.zip` persisted in the live site (hard-fail if neither exists) | durable (re-persisted each deploy) |
 | open PRs (`pr-<n>`) | each PR's build artifact, keyed by head SHA | ephemeral (drops on merge/close) |
 
 Releases are permanent, so old versions never vanish. PR previews come from CI
@@ -69,8 +69,7 @@ ordering:
   `pages-default-seed` release captured from the old gh-pages tree) before the first
   publish — which is the pipeline PR's own CI. This makes that first publish safe even
   when the repo already serves Pages from Actions (where a publish deploys live
-  immediately); with `guard-default-branch` at its default `true`, an un-seeded publish
-  fails loudly rather than silently dropping the branch.
+  immediately); an un-seeded publish fails loudly rather than silently dropping the branch.
 
 ## The `docs.zip` and version-token contracts
 
@@ -164,22 +163,21 @@ Because the inline publish runs *inside* the build's own CI run, that run isn't
 *completed* successful run yet — so `assemble`'s normal gather can't discover it. For
 a `main` push it would be worse than missing: the gather would find the **previous**
 successful run and publish a build behind by one commit. So `ci.yml` passes the
-build's version name to `publish.yml`, which hands it to `assemble` as
-`ARTIFACT_VERSION_NAME`; `publish.yml` downloads this run's `docs` artifact and
-`assemble` unzips + stages it directly, **skipping the re-gather of that version**.
-Everything else still comes from durable sources. The dispatch paths (the tag
-re-dispatch and the fork opt-in) pass no current build — they gather entirely from
-durable sources, the tag from its just-attached `docs.zip` Release asset and a fork
-from its approved head SHA's successful run.
-
-## The bash / JS split inside `assemble`
-
-`assemble` is two implementation files, run directly by `publish.yml` (which
-sparse-checks-them-out at `job.workflow_sha`):
-
-- **`assemble.sh`** does the IO plumbing — `gh` downloads, `unzip`, `mv`, the
-  `stable/` symlink — where shelling out is concise. It is also runnable standalone,
-  so the `gh` plumbing can be exercised locally.
+build's version name to `publish.yml`, which downloads this run's `docs` artifact and
+stages it into the gather dir as the **highest-priority** source — overwriting any
+same-name zip gathered from durable sources. Everything else still comes from durable
+sources. The dispatch paths (the tag re-dispatch and the fork opt-in) pass no current
+build — they gather entirely from durable sources, the tag from its just-attached
+`docs.zip` Release asset and a fork from its approved head SHA's successful run.
+
+## The inline-bash / JS split inside `assemble`
+
+The `assemble` logic is split between `publish.yml` inline steps and `assemble.mjs`
+(sparse-checked-out at `job.workflow_sha`):
+
+- **`publish.yml`'s gather and extract steps** do the IO plumbing — `gh` downloads,
+  `unzip`, `mv`, the `stable/` symlink — as inline bash. The steps are individually
+  named so each one's timing and failures are visible in the GH Actions UI.
 - **`assemble.mjs`** is the pure-ish kernel: ordering, prerelease detection,
   `switcher.json`/redirect rendering, and the folded-in required-branch guard. Its
   functions take plain data and return strings/verdicts, so they unit-test without
@@ -188,8 +186,9 @@ sparse-checks-them-out at `job.workflow_sha`):
 Pure bash is ruled out — semver ordering, prerelease detection and JSON rendering
 are not unit-testable in bash. Bash never parses JSON itself: every extraction uses
 `gh`'s built-in `-q`/`--jq` (it embeds real jq), never a piped standalone `jq` — a
-`gh … | jq` pipe would mask an API failure as empty output. Gather order is
-irrelevant; all ordering and prerelease logic lives in `generate`.
+`gh … | jq` pipe would mask an API failure as empty output. Gather order encodes
+priority — releases first, then branch CI overwrites them, then the current build
+overwrites those; all version-ordering and prerelease logic lives in `generate`.
 
 ## Fork-PR previews: per-commit maintainer opt-in
 
@@ -247,9 +246,9 @@ The `stable` segment name is a fixed convention, hardcoded in the widget.
   redirect → `main/`. Graceful; no release required.
 - **Release without `docs.zip`** (cut before this scheme): not selected by the
   releases query (it filters on a `docs.zip` asset) → skipped, no hard failure.
-- **Default branch missing** (`guard-default-branch: true`): if `main` has no recent
-  successful build to gather and none was injected, `generate` **hard-fails** rather
-  than publish a site missing it.
+- **Default branch missing**: if `main` has no recent successful CI artifact, no durable
+  `_sources/main.zip` in the live site, and no migration seed release, the deploy
+  **hard-fails** rather than publish a site missing it.
 - **PR build not yet green / SHA moved:** an open PR whose current head SHA has no
   successful CI run is skipped; its preview appears once the build passes.
 - **Merged/closed PR:** drops from the gather (open-PRs only) on the next deploy.
@@ -276,9 +275,11 @@ full analysis and an implementation sketch are tracked as future work in
   (`docs.yml`) computes the clean token inline and uploads the `docs` artifact.
 - **Direct Pages publish, no `gh-pages` branch** (`upload-pages-artifact` +
   `deploy-pages`), requiring the repo's Pages source set to "GitHub Actions".
-- **JS core + bash glue.** Pure functions (and their node tests) live in
-  `assemble.mjs`; bash does the `gh`/`unzip`/`mv` IO. Python was a contender (the
-  team is Python-heavy) but loses on a second toolchain in a JS-only repo.
+- **JS core + inline-bash glue.** Pure functions (and their node tests) live in
+  `assemble.mjs`; the `gh`/`unzip`/`mv` IO lives as inline bash steps in
+  `publish.yml` — individually named so step timing and failures are visible in
+  the GH Actions UI. Python was a contender (the team is Python-heavy) but loses
+  on a second toolchain in a JS-only repo.
 - **`release.yml` attaches `docs.zip`** (it downloads the run's artifacts and
   creates/uploads the Release via `gh`, verbatim), so `assemble` only ever *reads*
   release assets.
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index f5ce9b7..1cfa8ba 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -50,11 +50,11 @@ jobs. The `deploy` job carries the `github-pages` environment, `concurrency: pag
 generic.
 
 - **`deploy`** — internal PR / default-branch push (inline), or any `workflow_dispatch`.
-  Self-checks-out this repo's `assemble/` at `job.workflow_sha` / `job.workflow_repository`
-  (the `job` context resolves to the reusable file, not the caller), so the scripts match
-  the `<tag>` the consumer pinned — no version bump; the consumer's repo stays checked out
-  at the root so `assemble.mjs`'s `git tag` lists *their* versions. The inline path injects
-  the in-run build via `version-name`; the dispatch paths pure-gather.
+  Self-checks-out `assemble.mjs` at `job.workflow_sha` / `job.workflow_repository`
+  (the `job` context resolves to the reusable file, not the caller), so the kernel
+  matches the `<tag>` the consumer pinned — no version bump; the consumer's repo stays
+  checked out at the root so `assemble.mjs`'s `git tag` lists *their* versions. The
+  inline path injects the in-run build via `version-name`; the dispatch paths pure-gather.
 - **`re-dispatch`** — a tag push. Waits for the release, then re-fires the shim
   (`dispatch-workflow`, a file in the consumer's repo — a `workflow_call` run executes with
   the caller's token, so it can dispatch it) so the deploy lands as a `workflow_dispatch`
@@ -80,7 +80,6 @@ re-dispatch, a fork-PR preview, a manual re-deploy). A reusable workflow can't b
 | input | required | default | meaning |
 |---|---|---|---|
 | `version-name` | no | `""` | Version name of **this run's** `docs` artifact to stage directly, instead of gathering it from durable sources. Set by `ci.yml`'s inline publish (the run isn't a completed success yet, so the gather can't discover it — or would find a stale previous build). Empty → pure durable gather (the dispatch paths). |
-| `guard-default-branch` | no | `true` | When `true`, hard-fail if the consumer's default branch is absent from the site (its build artifact expired). Set `false` while a repo's default branch isn't yet publishing `docs.zip` (mid-migration). |
 | `pr` | no | `""` | Fork PR number to approve (pins its head SHA as `preview-approved`) and preview. Set on the shim's `workflow_dispatch` path. |
 | `dispatch-workflow` | no | `publish-dispatch.yml` | Filename of the shim in the consumer's repo, re-fired by the `re-dispatch` job. Override only if you renamed the shim. |
 
@@ -90,15 +89,15 @@ Every deploy rebuilds the complete tree from authoritative inputs:
 
 | version kind | source | durability |
 |---|---|---|
-| current build | this run's `docs` artifact, staged via `version-name` | n/a (just built) |
-| default branch (e.g. `main`) | latest CI **push** artifact → durable `_sources/<branch>.zip` in the live site → one-time migration seed release | durable — re-persisted into the site each deploy |
-| released tags | the `docs.zip` asset attached to each **GitHub Release** | permanent |
+| current build | this run's `docs` artifact, staged via `version-name` (highest priority — overwrites any same-name gathered source) | n/a (just built) |
+| default branch (e.g. `main`) | latest CI **push** artifact → durable `_sources/<branch>.zip` in the live site (hard-fail if neither exists) | durable — re-persisted into the site each deploy |
+| released tags | the `docs.zip` asset attached to each **GitHub Release** (the migration seed release, if present, seeds the default-branch zip) | permanent |
 | open PRs (`pr-<n>`) | each PR's build artifact, keyed by current head SHA — internal always, fork PRs only when the SHA carries a `preview-approved` status | ephemeral — drops when the PR merges/closes |
 
 A version no longer gathered (a merged/closed PR, a deleted release) is correctly
-dropped, because `deploy-pages` replaces the *entire* site. The version passed as
-`version-name` is staged first and **skipped** by every gather, so a stale previous
-build never clobbers the fresh one.
+dropped, because `deploy-pages` replaces the *entire* site. Sources are gathered in
+priority order (releases lowest, then branch CI, then the current build highest), so a
+fresher source always wins when names collide.
 
 ## The `docs.zip` / version-name contracts
 
@@ -116,18 +115,10 @@ without coordination — `docs.yml` owns both:
   There is **no sanitisation**: version names are clean by construction (the
   `tags: ['*']` trigger never builds `/`-tags).
 
-## Internals: running `assemble` standalone
+## Internals: `assemble.mjs`
 
-`assemble/assemble.sh` (run directly by `publish.yml`) is also runnable outside CI so
-the `gh` plumbing can be exercised locally:
-
-```bash
-REPO=DiamondLightSource/myst-version-switcher-plugin GH_TOKEN=$(gh auth token) \
-  assemble/assemble.sh
-```
-
-It is driven entirely by env (`REPO`, `GUARD_DEFAULT_BRANCH`, `GH_TOKEN`, `SITE`, and —
-for injection — `ARTIFACT_VERSION_NAME` + `ARTIFACT_ZIP`, the `docs.zip` `publish.yml`
-downloads before calling the script). The pure logic (ordering, prerelease detection,
-`switcher.json`/redirect rendering, the required-branch guard) lives in `assemble.mjs`
-and is unit-tested without git, the network, or the filesystem.
+The pure logic (ordering, prerelease detection, `switcher.json`/redirect rendering,
+the required-branch guard) lives in `assemble/assemble.mjs` and is unit-tested
+(`npm test`) without git, the network, or the filesystem. The `gh`/`unzip`/`mv` IO
+plumbing lives as inline bash steps in `publish.yml`'s `deploy` job — named and
+separated so step timing and failures are visible in the GH Actions UI.

From 6d8f7f1cd07adfd1a303469bbcb2fbcb43cadee9 Mon Sep 17 00:00:00 2001
From: Tom Cobb <tom.cobb@diamond.ac.uk>
Date: Tue, 30 Jun 2026 15:26:50 +0000
Subject: [PATCH 2/2] publish: fix runner.temp unavailable in reusable workflow
 job-level env

runner context is not available during expression parsing of a called reusable
workflow's job-level env block. Replace SITE=${{ runner.temp }}/site with
$RUNNER_TEMP/site (runner env var, always set) in shell steps, and
${{ runner.temp }}/site in step with:/env blocks where runner is valid.
Drops the now-unnecessary id: site step output.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/publish.yml | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index ce4afed..3523b37 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -92,7 +92,6 @@ jobs:
     env:
       REPO: ${{ github.repository }}
       DEFAULT: ${{ github.event.repository.default_branch }}
-      SITE: ${{ runner.temp }}/site
       SEED_TAG: pages-default-seed
       SOURCES_DIR: _sources
     steps:
@@ -130,7 +129,7 @@ jobs:
             -f description="Fork docs preview approved"
 
       - name: Create staging dirs
-        run: mkdir -p "$SITE" "$RUNNER_TEMP/gather"
+        run: mkdir -p "$RUNNER_TEMP/site" "$RUNNER_TEMP/gather"
 
       # Releases are permanent sources; the seed release (if present) stands in for the
       # default branch until _sources/ is established — store it as $DEFAULT.zip so the
@@ -230,31 +229,29 @@ jobs:
             name=$(basename "$f" .zip)
             tmp=$(mktemp -d)
             unzip -q "$f" 'html/*' -d "$tmp" 2>/dev/null && [ -d "$tmp/html" ] \
-              && { rm -rf "$SITE/$name"; mv "$tmp/html" "$SITE/$name"; } \
+              && { rm -rf "$RUNNER_TEMP/site/$name"; mv "$tmp/html" "$RUNNER_TEMP/site/$name"; } \
               || echo "::warning::$name: no html/ root in zip — skipping"
             rm -rf "$tmp"
           done
           dzip="$RUNNER_TEMP/gather/$DEFAULT.zip"
-          [ -d "$SITE/$DEFAULT" ] && [ -f "$dzip" ] \
-            && { mkdir -p "$SITE/$SOURCES_DIR"; cp "$dzip" "$SITE/$SOURCES_DIR/$DEFAULT.zip"; }
+          [ -d "$RUNNER_TEMP/site/$DEFAULT" ] && [ -f "$dzip" ] \
+            && { mkdir -p "$RUNNER_TEMP/site/$SOURCES_DIR"; cp "$dzip" "$RUNNER_TEMP/site/$SOURCES_DIR/$DEFAULT.zip"; }
 
       # `generate` orders versions, writes switcher.json + index.html, and prints the
       # stable-alias source dir (the newest release), or "" when no release is deployed yet.
       # Hard-fails if the default branch is absent (Ensure step guarantees the zip, but
       # the extract could still fail if the zip had no html/ root).
       - name: Generate switcher.json and stable alias
-        id: site
         run: |
           set -euo pipefail
           stable_src=$(node "$GITHUB_WORKSPACE/.mvs/assemble/assemble.mjs" generate \
-            --site-dir "$SITE" --repo "$REPO" --required "$DEFAULT")
-          [ -n "$stable_src" ] && ln -s "$stable_src" "$SITE/stable"
-          echo "dir=$SITE" >> "$GITHUB_OUTPUT"
+            --site-dir "$RUNNER_TEMP/site" --repo "$REPO" --required "$DEFAULT")
+          [ -n "$stable_src" ] && ln -s "$stable_src" "$RUNNER_TEMP/site/stable"
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:
-          path: ${{ steps.site.outputs.dir }}
+          path: ${{ runner.temp }}/site
 
       # Deploy the uploaded artifact. deploy-pages stamps the deployment with
       # pages_build_version = GITHUB_SHA and has no input to change it; the value is
@@ -289,7 +286,7 @@ jobs:
       - name: Verify the deployed origin matches what we assembled
         env:
           PAGE_URL: ${{ steps.deployment.outputs.page_url }}
-          SITE_DIR: ${{ steps.site.outputs.dir }}
+          SITE_DIR: ${{ runner.temp }}/site
         run: |
           set -euo pipefail
           [ -n "$PAGE_URL" ] || { echo "::error::deploy-pages did not report a page_url"; exit 1; }