[AAASM-3753] ✨ (aggregate): Mirror core & go-sdk archived versions into hub switcher

[Chisanan232]

Description

Make the docs-hub version switcher list the full archived version set for core (agent-assembly mdBook) and go-sdk (Hugo) — matching python-sdk's full breadth. Previously the hub listed only the latest channel for core/go while python listed its entire history.

Source/approach chosen: rebuild from git tags in the aggregator (Option C-style logic, aggregator-only — no per-repo deploy change). Neither core nor go-sdk has a persistent gh-pages branch (only python does), so Option A is impossible. Option B (mirror the live deployed Pages site) was rejected as fragile — the core deploy itself abandoned live-site mirroring (wget -r) in AAASM-2827 because it silently lost versions, switching to "git is the source of truth". So the hub now does exactly what each module's deploy job does:

• core (build_core): rebuild every v*.*.* git tag's mdBook into /core/<tag>/ (worktree per tag), then compute /core/versions.json via the core repo's own docs/ci/build_versions.py — archived[] seeded from the rebuilt tags (self-healing from git), moving pre-release/stable pointers seeded from the live deployed manifest.
• go-sdk (build_go): recompute website/data/versions.toml from git tags (replicating docs-site.yml via the repo's own versions_channels.py) before build_all_versions.sh, so the build-time-baked Hugo dropdown lists every /go-sdk/<tag>/.
• search: Pagefind scoped to each module's default channel (archived dirs moved aside during indexing, restored via an EXIT trap) to avoid N near-duplicate hits per page.
• verify: build now asserts ≥1 /<tag>/ snapshot under both core/ and go-sdk/.

No per-repo PR was needed — the hub reuses each repo's existing build scripts.

Type of Change

• ✨ New section or feature documentation
• 🔧 Configuration / CI change (aggregation build script)

Related Issues

• Related Jira ticket: AAASM-3753 (follow-up to AAASM-3752 / [AAASM-3752] 🐛 (aggregate): Restore per-module version switcher in docs hub #41)

Closes AAASM-3753

How to verify

Ran bash docs/scripts/aggregate.sh locally (all toolchains present). Results:

• core: 13 archived tag dirs produced (v0.0.1-alpha.1…beta.4) + latest; versions.json archived[] = all 13.
• go-sdk: 8 archived tag dirs produced (v0.0.1-alpha.1…beta.3) + latest + pre-release.
• Browser (headless Chromium): the core switcher (runtime, from versions.json) lists latest + pre-release + all 13 tags; the go-sdk switcher (baked) lists latest + pre-release + all 8 tags; all 23 archived links resolve 200 (zero 404s). node/python switchers + hub landing unaffected.

Documentation Checklist

• aggregate.sh build passes locally with no errors
• All internal cross-links verified (0/23 archived links 404)
• Page registered in docs/src/SUMMARY.md (n/a — aggregation script + contract docs, no new hub page)
• Self-hosted instructions not included (SaaS-only scope)
• Commits follow GitEmoji convention and are small / atomic

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cc1vBBiNxp9qLKQ5Gq85w8

[Chisanan232]

🔎 Claude Code review — hub archived-version mirroring (AAASM-3753)

CI: Green. Aggregate all module docs pass (1m5s — the full end-to-end build that clones all 4 modules, rebuilds 13 core + 8 go tags, scopes Pagefind, and runs the verify gate), SonarCloud pass, Deploy skipped (expected on PR). clone_module does a full clone (not --depth 1), so all git tags are present in CI — the per-tag rebuild loop has real input and verify_archived ≥1 passes legitimately, not vacuously.

Scope vs AAASM-3753: Matches exactly. Full archived set via aggregator-only rebuild-from-tags (no per-repo deploy change) — core 13 tags + latest/pre-release/stable via the repos own build_versions.py; go 8 tags + channels via the repos own versions_channels.py + build_all_versions.sh. Pagefind scoped to each modules default channel (the in-scope "minor" search item). Source documented in AGGREGATION.md`. No scope gap.

Side-effects / regression: NONE to existing hub behavior — all additive/scoped.

• Per-tag failure mode: non-fatal skip-with-warning (intended, mirrors docs.yml) — one tag failing under toolchain drift is logged + omitted, build stays green. Soft note: the verify gate asserts ≥1 archived dir, not the full count, so multi-tag drift could silently ship a partial dropdown. Acceptable; a count/floor assertion would harden it (follow-up, not a blocker).
• Pagefind restore-trap: robust. set -euo pipefail + trap restore_pagefind EXIT set immediately after scope_pagefind, explicit restore after indexing, and restore_pagefind is idempotent — archived dirs return to public/ even if Pagefind crashes (the pagefind/ index is written before restore, separate dir). Only a mid-move failure inside scope_pagefind itself (before the trap is armed) could strand dirs — negligible (local mvs).
• node / python / hub untouched: build_node, build_python, hub build unchanged. python-sdk`s served output is unchanged; only its search-index scope narrows to default channel (intended).
• Redirects + /latest/ ([AAASM-3752] 🐛 (aggregate): Restore per-module version switcher in docs hub #41): intact; versions.json/versions.toml now recomputed via each module`s own script (no drift in channel logic).
• Minor: core seeds moving pre-release/stable from a live curl to github.io (non-fatal on failure — drops only moving channels, never archived); the go-sdk TOML serialization is reimplemented inline (channel computation is reused) so could drift from docs-site.yml over time. Both minor.

Readiness: Ready to approve & merge.
Note: build time materially longer (21 tag rebuilds) but well within CI limits (1m5s observed).
— 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