docs-s3: versioned web publishing

[JArmandoAnaya]

Part of the Documentation Site workstream (see the epic) · decided in ADR-0009 · specified in the roadmap. Depends on docs-s1; independent of docs-s2 in principle, but land it after.

Publishes the manual on the web, versioned, with a pipeline that works today when only dev/ exists and grows a version directory each time the maintainer tags a release.

Hard constraints — read first

1. Nothing in this sprint may create a tag or a release. The roadmap's release philosophy is explicit: only the maintainer publishes; automation and AI agents never tag. Workflows react to tags (on: push: tags:) and nothing more.
2. No tags exist in this repository after the roadmap reset. The pipeline must therefore be correct and demonstrable with dev/ alone — a version-selector that only works once two versions exist is not acceptable.
3. The maintainer owns every AWS action. This sprint delivers amplify.yml, the workflows, and a runbook. Do not attempt to create, configure, or authenticate an Amplify app, a domain, or any AWS resource. Do not add AWS credentials to the repo.
4. Site CI is Linux-only; the C++/CMake build stays Node-free.

Deliverables

1. build:web

Standard Starlight output with search (Pagefind) enabled, built with a configurable --base=/<segment>/ so the same source builds correctly under /dev/, /v0.1.0/, /latest/, or a scratch prefix.

2. Assembly workflows

GitHub Actions assembling the published tree:

/                 → redirect to latest/ (or dev/ while no release exists)
/versions.json    → the version list the dropdown reads
/dev/             → built from main
/vX.Y.Z/          → built from each release tag
/latest/          → copy of the highest semver version

• main push → rebuild dev/.
• Release tag push → build vX.Y.Z/, recompute latest/ as the highest semver (not "most recent tag"), regenerate the root redirect and versions.json.
• The assembled tree lives on a publishing branch (docs-published). Assembly must be idempotent and must not lose existing version directories when only one is rebuilt.
• The root redirect points at latest/ when a release exists and dev/ otherwise. Verify the no-release case works, since that is today's state.

3. Version dropdown

A small header control reading the root versions.json. Switching versions preserves the current page path when that path exists in the target version, and falls back to that version's landing page when it does not (a page added after v0.1.0 will not exist in v0.1.0 — do not produce a 404).

4. Dry-run path

A clearly-marked workflow_dispatch entry point taking a version input and writing to a scratch prefix, so the tag-driven flow is demonstrable and reviewable before any real tag exists. Label it unmistakably as a dry run in the workflow name and in its output, and make sure it cannot write over dev/, latest/, versions.json, or the root redirect.

5. amplify.yml + runbook

amplify.yml configured for serving the prebuilt branch — Amplify does not build from source (rejected in ADR-0009: tag-driven multi-version assembly is Actions territory, and building in Amplify would move build logic into a console UI).

A maintainer runbook in docs/ covering: creating the Amplify app against the prebuilt branch, the connection/permissions it needs, domain notes, the end-to-end flow from git push to a live page, how to verify a deploy, and what to do when an assembly run fails. Written for the maintainer to follow without reading the workflow YAML.

Acceptance

• dev/ assembly runs green from main and produces a tree that serves correctly (root redirect → dev/, search working, base path correct).
• The workflow_dispatch dry run demonstrates versioned assembly into a scratch prefix, including latest/ recomputation and versions.json regeneration, without touching the real tree.
• The version dropdown reads versions.json, preserves the current path where it exists, and degrades to the landing page where it does not.
• No workflow creates a tag or a release — state this explicitly in the PR and show it in the workflow triggers.
• The runbook is complete enough that the maintainer can create the Amplify app from it alone.
• C++ jobs untouched.

Out of scope — do not touch

• Anything AWS-side: creating the Amplify app, domains, certificates, credentials.
• Creating a tag, a release, or a version of RoadMaker.
• The local reader build, packaging, or the Help-menu action (docs-s2).
• The authoring guide and dependency cadence (docs-s4).
• Page structure and tiering (docs-s1).
• Analytics, comment systems, or any third-party script on the site.
• Help pipeline: tutorial pages' parent-relative links rewrite to wrong guide-root URLs #297 — not fixed, not closed here.

---

Epic: #344

[JArmandoAnaya]

Closed by #561 (squash-merged as 30211cc, all 18 CI checks green).

Delivered

1. build:web with a configurable --base=/<segment>/, gated by check-web-build.mjs.
2. Assembly workflow — dev/ from main, vX.Y.Z/ from a release tag, latest/ as a copy of the highest semver, root redirect, versions.json, onto docs-published. Idempotent and non-destructive: one segment is replaced and the derived files recomputed from disk, so a version an individual run knows nothing about survives it.
3. Version dropdown in the header, preserving the current page where the target has it and falling back to that version's landing page where it does not.
4. Dry run via workflow_dispatch into a scratch prefix.
5. amplify.yml (empty build phases, baseDirectory: /, copied onto the published branch) + the maintainer runbook at docs/contributing/docs-site-publishing.md.

Nothing added creates a tag or a release. Triggers are a push to main, a push of a tag that already exists, and the manual dry run. Stated precisely: release.yml does publish a GitHub release reacting to a maintainer's tag — it predates this and is not modified here. What is true is that nothing this PR adds creates a tag or a release, and no workflow in the repository creates a tag.

Works today with dev/ alone

That is the state after the roadmap reset, so it is the state that had to work: latest is null, the root redirect points at dev/, and the dropdown hides itself rather than offering a choice of one.

Rehearsed, not asserted

Four versions published in tag order, the last being a patch on an old line:

Published	latest
dev	(none yet)
v0.1.0	v0.1.0
v0.10.0	v0.10.0
v0.9.1 (tagged last)	v0.10.0, unmoved

And a dry run left the live tree byte-identical by hash while producing a complete _dryrun/ tree with its own recomputed latest; the live manifest never learned the candidate existed. Containment is structural — the assembler is handed the scratch directory as its root, so the real dev/, latest/, versions.json and redirect are not addressable from inside it — and a following step asks git what changed and fails on anything outside the prefix.

The defect found on the way

Astro applies base to the links it generates; a link written in the guide's Markdown is content and passes through untouched. Under a version segment the sidebar and nav worked while every in-content cross-page link 404ed — the failure a spot check from the front page cannot see. Found by building with a base and reading the output, not by reasoning. The adapter now applies the same prefix from the same environment variable the config reads, and PR CI builds under /dev/ rather than /, since a root build cannot exercise the base at all.

Deliberate design note

The dropdown reads each version's page list from versions.json rather than issuing a HEAD probe. A probe would make correctness depend on how the host answers for a missing file, and a host with an SPA-style 200 fallback would make every switch look successful while landing readers on a not-found page that renders like a real one.

Verification

17/17 script tests (13 new for the assembler), both builds green, licence gate clean at 374 packages with no dependency added, all workflow files parse, link check differential against an extracted main shows no new findings, no C++ or CMake touched. Three sabotages — dropping the base prefix, latest = most recent tag, and dry-run containment — each verified present in the source first, each caught.

Outstanding — maintainer only

• Create the hosting app against the docs-published branch (not main), decline framework detection, and attach the domain. Every AWS action is yours by scope; the runbook is the deliverable that unblocks it.
• Confirm the first live deploy against the runbook's five-point checklist — in particular following a link in body text rather than in the sidebar, which is the check the base defect would have escaped.

The docs-published branch is created by the first workflow run; you do not seed it by hand.