feat(mdbook): switch versioning from git tags to versions/ directories

Replace the git-tag-based snapshot model with frozen-directory
snapshots. Each released spec version is its own subtree under
./versions/vX.Y.Z/ — a literal copy of ./src/ taken at release time.

Why: tagging the whole repo conflated *spec content* with *site
infrastructure* (book.toml, theme, picker JS, workflow, build
scripts). Improving any of those required cherry-picking the change
back to every old tag. With directory snapshots, content is frozen
but every deploy renders every version with TODAY's infrastructure
— site fixes propagate everywhere for free.

Changes:

- scripts/build-site.sh now iterates ./versions/v* directories
  instead of `git tag --list 'v*'`. Each per-version build sets
  MDBOOK_BOOK__SRC to the snapshot dir and MDBOOK_OUTPUT__HTML__SITE_URL
  to /meshcore-spec/<version>/. The root book.toml, theme, and
  picker JS apply uniformly.
- justfile gains `cut-version vX.Y.Z` — validates the name, refuses
  to overwrite, runs `cp -R src versions/<version>`, prints next-
  step hints. Cutting a release is now `just cut-version v0.1.0`,
  then a commit; optionally tag the commit for provenance, but
  tags no longer drive CI.
- .github/workflows/mdbook.yml drops the `tags: ['v*']` trigger
  and `fetch-depth: 0` (no longer iterating git history). Triggers
  on push to main and PRs.
- src/00-overview.md: "Spec Versions" section rewritten to describe
  the directory-snapshot model and the deliberate content-vs-
  infrastructure split.

Smoke-tested locally: `just build-site` with no versions/ produces
`_site/{latest/, versions.json=["latest"], index.html}`.
`just cut-version v0.0.1` + rebuild produces both `latest/` and
`v0.0.1/`, versions.json=`["latest","v0.0.1"]`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

scripts/build-site.sh

@@ -1,17 +1,19 @@
 #!/usr/bin/env sh
 # Build the full multi-version site into ./_site/:
-#   - "latest" from the current HEAD
-#   - one subtree per v* git tag
+#   - "latest" from ./src/
+#   - one subtree per ./versions/vX.Y.Z/ directory
+#
+# Each per-version build uses today's repo-root build infrastructure
+# (book.toml, theme/, picker JS, scripts/), only swapping in the
+# frozen content directory via MDBOOK_BOOK__SRC. This means every
+# deploy gives every published version the current theme — site
+# improvements never need backporting to old snapshots.
 #
-# Each per-version build gets MDBOOK_OUTPUT__HTML__SITE_URL set so its
-# canonical URL and sitemap are correct for the deployed location.
 # Emits _site/versions.json (newest first; consumed by
-# theme/version-picker.js) and a root index.html that redirects to
-# /latest/.
+# theme/version-picker.js) and _site/index.html (redirect to /latest/).
 #
-# Intended to be called via `just build-site`. SITE_BASE can be
-# overridden to deploy under a different URL prefix; the default
-# targets https://swaits.github.io/meshcore-spec/.
+# Cut a new frozen version with `just cut-version vX.Y.Z`, which
+# snapshots ./src/ into ./versions/vX.Y.Z/.
 
 set -eu
 
@@ -19,7 +21,6 @@ SITE_BASE="${SITE_BASE:-/meshcore-spec}"
 WORKSPACE="$(pwd)"
 SITE_DIR="$WORKSPACE/_site"
 
-# Section grouping for GitHub Actions logs; noop locally.
 group() { printf '::group::%s\n' "$1"; }
 endgroup() { printf '::endgroup::\n'; }
 warn() { printf '::warning::%s\n' "$1"; }
@@ -27,43 +28,45 @@ warn() { printf '::warning::%s\n' "$1"; }
 rm -rf "$SITE_DIR"
 mkdir -p "$SITE_DIR"
 
-# ---- latest (current HEAD) ----
+# ---- latest (from src/) ----
 group "build latest"
 MDBOOK_OUTPUT__HTML__SITE_URL="${SITE_BASE}/latest/" \
     mdbook build "$WORKSPACE" -d "$SITE_DIR/latest"
 endgroup
 
-# ---- each v* tag ----
-# Each tag is built from its own git worktree so today's mdbook config
-# / theme files don't bleed into older builds.
-TAGS="$(git tag --list 'v*' --sort=-v:refname 2>/dev/null || true)"
-for tag in $TAGS; do
-    [ -z "$tag" ] && continue
-    group "build $tag"
-    wt="$(mktemp -d -t mdbook-tag-XXXXXX)"
-    git worktree add --detach "$wt" "$tag"
-    if [ -f "$wt/book.toml" ]; then
-        if ! MDBOOK_OUTPUT__HTML__SITE_URL="${SITE_BASE}/${tag}/" \
-             mdbook build "$wt" -d "$SITE_DIR/${tag}"; then
-            warn "mdbook build failed for ${tag}; skipping"
-            rm -rf "${SITE_DIR:?}/${tag:?}"
-        fi
-    else
-        warn "${tag} has no book.toml; skipping"
+# ---- frozen versions (./versions/v*) ----
+# Discover and sort by semver (newest first). The list is captured
+# into a variable so we can iterate it twice — once to build, once to
+# emit versions.json — without re-scanning.
+list_versions() {
+    for d in versions/v*; do
+        [ -d "$d" ] || continue
+        basename "$d"
+    done | sort -V -r
+}
+VERSION_DIRS="$(list_versions)"
+
+for version in $VERSION_DIRS; do
+    vdir="versions/$version"
+    [ -d "$vdir" ] || continue
+    group "build $version"
+    if ! MDBOOK_BOOK__SRC="$vdir" \
+         MDBOOK_OUTPUT__HTML__SITE_URL="${SITE_BASE}/${version}/" \
+         mdbook build "$WORKSPACE" -d "$SITE_DIR/${version}"; then
+        warn "mdbook build failed for ${version}; skipping"
+        rm -rf "${SITE_DIR:?}/${version:?}"
     fi
-    git worktree remove --force "$wt"
     endgroup
 done
 
 # ---- versions.json (consumed by theme/version-picker.js) ----
-# Newest first; "latest" always at the top.
+# "latest" always first; then each successfully-built frozen version.
 {
     printf '['
     printf '"latest"'
-    for tag in $TAGS; do
-        [ -z "$tag" ] && continue
-        [ -d "$SITE_DIR/$tag" ] || continue
-        printf ',"%s"' "$tag"
+    for version in $VERSION_DIRS; do
+        [ -d "$SITE_DIR/$version" ] || continue
+        printf ',"%s"' "$version"
     done
     printf ']\n'
 } > "$SITE_DIR/versions.json"