ci(pages): cache-bust openapi.json with commit SHA

[jstjoe]

Summary

After #21 deployed, the Pages site kept serving the old endpoint summaries because GitHub Pages sets a long-lived Cache-Control on static assets and Scalar memoises the fetched spec client-side. Spec on the wire was correct; spec in every previously-opened tab was stale until a hard reload.

Fix: append ?v=__CACHE_BUST__ to the data-url in docs/index.html; substitute the literal at deploy time with ${GITHUB_SHA} via a one-line sed step in .github/workflows/pages.yml. Each release rotates the query string, so browsers (and Scalar's localStorage cache) fetch the new spec.

Local dev keeps working — python -m http.server -d docs happily serves openapi.json regardless of the query string.

Test plan

• Local: open docs/index.html via python -m http.server -d docs; Scalar still loads the spec (literal token doesn't break the static server).
• After merge: pages.yml runs, deployed index.html has ?v=<sha>, hard reload no longer required.
• Next spec edit lands and is visible without Cmd+Shift+R.

🤖 Generated with Claude Code

[jstjoe]

@claude could you review?

[claude]

Claude finished @jstjoe's task in 1m 0s —— View job

---

Review

• Gather context
• Read changed files
• Provide review feedback

---

Verdict: LGTM — clean, minimal fix. A few observations below, none blocking.

---

.github/workflows/pages.yml — the sed step

- name: Cache-bust the spec URL in docs/index.html
  run: sed -i "s/__CACHE_BUST__/${GITHUB_SHA}/g" docs/index.html

• Correct placement: runs after spec regeneration but before configure-pages / upload. Order is fine.
• Shell expansion: double-quoted sed string correctly lets the shell expand ${GITHUB_SHA} before sed sees it.
• No injection risk: GITHUB_SHA is a lowercase hex string — no sed metacharacters possible.
• -g flag: redundant (one occurrence of __CACHE_BUST__ in the file) but completely harmless.
• Path: docs/index.html is relative to the repo root, which is the working directory after checkout@v4. Correct.

Optional hardening (not a blocker): you could add a one-liner assertion after the sed to fail fast if the token wasn't present/replaced:

run: |
  sed -i "s/__CACHE_BUST__/${GITHUB_SHA}/g" docs/index.html
  grep -q "${GITHUB_SHA}" docs/index.html || { echo "cache-bust token not substituted"; exit 1; }

---

docs/index.html — the placeholder token

• The sentinel __CACHE_BUST__ is distinctive enough that accidental matches elsewhere in the repo are essentially impossible.
• The explanatory comment (lines 13–19) is accurate and covers the local-dev case clearly — nice touch.
• Leaving the literal token in source is intentional and well-documented; readers won't be confused.

---

Future-proofing note

If additional HTML entry points are ever added under docs/, the sed command targets only docs/index.html. At that point you'd either need to widen the glob (sed -i … docs/**/*.html) or add another step. Not an issue now, just worth remembering.

---

Overall this is a correct, idiomatic approach to cache-busting a static Pages site. No changes needed to merge.