From c70ab07c32e25eebe198192ea46ad65757312a3c Mon Sep 17 00:00:00 2001
From: Stephen Waits <steve@waits.net>
Date: Tue, 12 May 2026 10:21:36 -0600
Subject: [PATCH] feat(mdbook): show spec version in overview body + page title
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first version cut (v0.1.0) revealed a real gap: nothing in the
rendered book identified which release the reader was on. The
version-picker chip says "version: v0.1.0" when you're on /v0.1.0/,
but it's a small UI affordance — and on /latest/ it can't say
"v0.1.0" because /latest/ is the rolling main build, not the v0.1.0
release.

Two complementary fixes, both visible without JS:

1. **Body marker.** Top of every chapter-0 (overview) page now reads
   `Spec version: <token>`. The token is `latest (main)` in src/, and
   gets frozen to the actual version (`v0.1.0`) when cut-version
   snapshots the directory. So /latest/ overview says "latest (main)"
   and /v0.1.0/ overview says "v0.1.0".

2. **Per-build page title.** scripts/build-site.sh now sets
   `MDBOOK_BOOK__TITLE` for each build:
     - latest → "MeshCore Protocol Specification — latest (main)"
     - vX.Y.Z → "MeshCore Protocol Specification — vX.Y.Z"
   The browser tab and mdBook sidebar header reflect the version.

`just cut-version` updated to run a one-line sed on the snapshot's
00-overview.md replacing the `latest (main)` marker. Defensive grep
warns if the marker isn't found (e.g., src/ was edited away from
the expected line).

versions/v0.1.0/00-overview.md regenerated by re-running
`just cut-version v0.1.0` after the marker landed in src/ — so the
v0.1.0 snapshot now self-identifies correctly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 justfile                       | 8 ++++++++
 scripts/build-site.sh          | 2 ++
 src/00-overview.md             | 3 +++
 versions/v0.1.0/00-overview.md | 3 +++
 4 files changed, 16 insertions(+)

diff --git a/justfile b/justfile
index c716dfe..42ee482 100644
--- a/justfile
+++ b/justfile
@@ -51,6 +51,14 @@ cut-version VERSION:
     fi
     mkdir -p versions
     cp -R src "versions/{{VERSION}}"
+    # Freeze the version marker in the snapshot. src/ keeps the literal
+    # `latest (main)` so the rolling /latest/ build stays accurate.
+    sed -i 's|`latest (main)`|`{{VERSION}}`|' "versions/{{VERSION}}/00-overview.md"
+    if ! grep -q '`{{VERSION}}`' "versions/{{VERSION}}/00-overview.md"; then
+        echo "warning: expected version marker not found in 00-overview.md; the" >&2
+        echo "snapshot still says 'latest (main)'. Check that src/00-overview.md" >&2
+        echo "contains the marker line ('**Spec version:** \`latest (main)\`')." >&2
+    fi
     echo "Snapshotted src/ -> versions/{{VERSION}}"
     echo
     echo "Next steps:"
diff --git a/scripts/build-site.sh b/scripts/build-site.sh
index aadf8fe..2cbf3ff 100755
--- a/scripts/build-site.sh
+++ b/scripts/build-site.sh
@@ -30,6 +30,7 @@ mkdir -p "$SITE_DIR"
 
 # ---- latest (from src/) ----
 group "build latest"
+MDBOOK_BOOK__TITLE="MeshCore Protocol Specification — latest (main)" \
 MDBOOK_OUTPUT__HTML__SITE_URL="${SITE_BASE}/latest/" \
     mdbook build "$WORKSPACE" -d "$SITE_DIR/latest"
 endgroup
@@ -51,6 +52,7 @@ for version in $VERSION_DIRS; do
     [ -d "$vdir" ] || continue
     group "build $version"
     if ! MDBOOK_BOOK__SRC="$vdir" \
+         MDBOOK_BOOK__TITLE="MeshCore Protocol Specification — ${version}" \
          MDBOOK_OUTPUT__HTML__SITE_URL="${SITE_BASE}/${version}/" \
          mdbook build "$WORKSPACE" -d "$SITE_DIR/${version}"; then
         warn "mdbook build failed for ${version}; skipping"
diff --git a/src/00-overview.md b/src/00-overview.md
index 39294af..25543f0 100644
--- a/src/00-overview.md
+++ b/src/00-overview.md
@@ -2,6 +2,9 @@
 
 ## Section 0: Overview
 
+**Spec version:** `latest (main)` &middot; see
+[Spec Versions](#spec-versions) for the full list of frozen releases.
+
 ### Status and Provenance
 
 > **This is an unofficial, independent specification.** It is **not** part of
diff --git a/versions/v0.1.0/00-overview.md b/versions/v0.1.0/00-overview.md
index 39294af..1a7a7c4 100644
--- a/versions/v0.1.0/00-overview.md
+++ b/versions/v0.1.0/00-overview.md
@@ -2,6 +2,9 @@
 
 ## Section 0: Overview
 
+**Spec version:** `v0.1.0` &middot; see
+[Spec Versions](#spec-versions) for the full list of frozen releases.
+
 ### Status and Provenance
 
 > **This is an unofficial, independent specification.** It is **not** part of