[AAASM-3752] 🐛 (aggregate): Restore per-module version switcher in docs hub

[Chisanan232]

Description

Restore the per-module documentation version switcher in the aggregated docs
hub. The first aggregation cut (AAASM-3659) built one flat default-channel page
per module and dropped the version machinery each switcher needs, so the switchers
404'd on docs.agent-assembly.com while still working on the standalone
*.github.io sites. This makes the aggregator publish, under each /<module>/,
the version manifest and the version/channel subpaths the switcher references.

Mechanism (per module):

Module	Mechanism	Switcher lists
python-sdk	Reuse the published gh-pages mike tree verbatim (cp -RL, derefs alias symlinks)	full set: latest, stable, every alpha/beta, pre-release
core	Build master HEAD → /core/latest/, copy committed docs/versions.json → /core/versions.json, site-root redirect	default channel (latest) from the committed manifest
go-sdk	Run the repo's own build_all_versions.sh (PAGES_BASE=/go-sdk) → /go-sdk/<channel>/, site-root redirect	default channel (latest) from committed versions.toml
node-sdk	unchanged (dropdown baked in from committed versioned_docs/)	committed versions

python is "full" because it keeps a persistent gh-pages branch (reused for free);
core/go publish via a deploy-time Pages artifact with no versioned branch, and their
committed manifests declare only the latest channel (moving channels + archived
tags are release-job-computed and live only on the deployed artifact). Mirroring
those archived tags into the hub is a documented follow-up. See AGGREGATION.md.

Before / after (what now publishes under each subpath)

Path	Before	After
/python-sdk/versions.json	404	present (11 versions) + every referenced version dir
/go-sdk/latest/	404 (built flat at /go-sdk/)	present + /go-sdk/ root redirect
/core/versions.json	404 (manifest not copied)	present + /core/latest/ + root redirect
/node-sdk/	works	unchanged (not regressed)

Type of Change

• 🐛 Bug fix (correcting inaccurate or missing content)
• 🔧 Configuration / CI change

Related Issues

• Related Jira ticket: AAASM-3752

Closes AAASM-3752

Documentation Checklist

• Commits follow GitEmoji convention and are small / atomic
• Self-hosted instructions not included (SaaS-only scope)
• bash -n docs/scripts/aggregate.sh passes; modules.json valid JSON

Verification

Built the changed build_* paths locally (mdbook 0.5.2, uv/mike via gh-pages,
hugo 0.163 extended, go 1.26), served public/ over http://localhost, and
drove a headless Chromium to confirm each switcher populates with no 4xx
on any manifest:

• core — #aaasm-version-selector populated: latest (master) → /core/latest/. No 4xx.
• python-sdk — mike/material dropdown populated with all 11 versions (latest, 0.0.2/stable, alphas, betas, pre-release, 0.0.0); every referenced version dir resolves 200. No 4xx.
• go-sdk — channel selector populated: latest (master) → /go-sdk/latest/; page renders with assets under /go-sdk/latest/. No 4xx.

Screenshots saved locally to /tmp/fix-docshub/verification/{core,python,go}-switcher.png
(not committed — binary build artifacts; gh cannot attach images to a PR body).
The only blocked requests in verification were Google Analytics beacons (expected, irrelevant).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cc1vBBiNxp9qLKQ5Gq85w8

[Chisanan232]

🔎 Claude Code review — docs-hub version switcher (AAASM-3752)

CI: ✅ Green. Aggregate all module docs passes (the Aggregate step runs the full end-to-end aggregate.sh — clone+build all 4 modules, dir-verify gate, the new version-manifest gate, and Pagefind), SonarCloud passes, Deploy correctly skipped (PR). The end-to-end aggregation succeeding is strong evidence the full hub still builds.

Scope vs AAASM-3752: ✅ Delivers Option A (full restore). python-sdk = full mike tree reused verbatim from gh-pages (cp -RL derefs alias symlinks); core = build master HEAD → /core/latest/ + copy docs/versions.json → /core/versions.json + site-root redirect; go-sdk = repo's own build_all_versions.sh (PAGES_BASE=/go-sdk) → /go-sdk/latest/ + redirect; node-sdk untouched. The core/go "only latest channel listed" limitation (archived tags are release-job-computed, mirroring them = documented follow-up in AGGREGATION.md) is acceptable per ticket, not a scope miss — confirmed go versions.toml ships only the latest channel.

Side-effects / regression: ✅ NONE — every change is additive/scoped to the three switcher fixes. Verified:

• node-sdk — case dispatch + build_node are byte-for-byte unchanged; the new [[ "$gen" != "mkdocs-material" ]] clone-guard still clones node-sdk (gen=docusaurus). Not regressed; CI built it non-empty.
• hub landing / no clobber — hub still built FIRST; the core/go root redirects write public/core/index.html and public/go-sdk/index.html only — neither touches the hub root public/index.html nor other modules.
• redirects resolve — /core/ → /core/latest/ and /go-sdk/ → /go-sdk/latest/; both targets exist (CI verify gate asserts core/latest/index.html + go-sdk/latest/index.html). Confirmed source deps exist: core docs/versions.json+site-root-index.html, go redirect/index.html (@@DEFAULT_PATH@@ placeholder ×5) + build_all_versions.sh (env contract PAGES_BASE/PUBLIC_DIR/REPO_ROOT/MASTER_REF matches the call exactly), python gh-pages branch + versions.json.
• search (Pagefind) — block unchanged; CI Pagefind step succeeded. Indexing the python per-version dirs adds near-duplicate hits (noise, documented in AGGREGATION.md) but does not break search.
• new verify-block — unconditional and fails on any missing manifest/dir; cannot skip silently.

One intended behavior change (not a defect): core and go-sdk now serve under /<module>/latest/ instead of flat /<module>/, matching the standalone site layout — deep links to the old flat paths change, but /<module>/ roots now redirect.

Readiness: ✅ Ready to approve & merge. Suggest filing a lightweight follow-up ticket for "mirror core/go archived tags into the hub" so the AGGREGATION.md follow-up isn't lost (non-blocking).

— Claude Code (automated PR review, 2026-06-26)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud