[Feature]: multi-repo, versioned Antora documentation aggregation site

[michalharakal]

🧠 D: DOCUMENT — Problem & Opportunity

Summary (1–2 sentences):

SKaiNET is one component among several repos, yet its docs publish as a single, version-less site that tracks only the latest release. We want one aggregation site that hosts docs per release version (/0.36/, /latest/) and can pull from multiple component repos.

• What is missing: The published Antora site uses version: ~ (version-less). There is no version selector, no version segment in URLs, and no way to read the docs for a specific release. There is also no mechanism to combine docs from sibling repos into one site.
• Why now: We are under heavy development and cutting frequent releases. Single-version is acceptable short-term, but as the ecosystem grows to multiple repos, readers need version-pinned, cross-component docs.
• Who benefits: Library users (can read docs for the exact version they depend on), contributors (clear per-repo/per-version structure), maintainers (one canonical docs home).
• High-level goal: A dedicated docs aggregation target — its own repo or a dedicated gh-pages/docs branch — whose Antora playbook pulls each component repo by release tag, producing a multi-version, multi-component site with a version picker.

Already shipped (out of scope here):

• Publish the single current-release site on release: published (branch feature/docs-fork-comment-and-release-deploy). The live site now tracks the last released version.
• Fix fork-PR doc-preview comment failures (read-only GITHUB_TOKEN).

---

🔍 A: ASSESS — Feasibility & Impact

✔️ Feasibility

• Antora natively supports multi-version (component version: per git ref) and multi-repo (playbook content.sources listing several repos). The machinery exists; the work is wiring + a release discipline.
• Key architectural constraint: Antora reads the committed tree for git tags, but operator pages + Dokka API are generated at build time and are gitignored (_generated_). Native "read all tags" would therefore render older versions with missing generated pages.

✔️ Expected Impact

• Version-pinned docs matching each release; a version selector in the site chrome (today the release version only appears inside dependency code snippets via the hand-bumped {skainet_version} attribute — nowhere in nav/URL/breadcrumb).
• A single home able to host docs for sibling repos.

✔️ Risks / Constraints

• GitHub Pages serves one artifact/site; preserving multiple versions needs either an aggregation branch that keeps sibling version dirs, or a single Antora run that emits all versions.
• Only releases cut after the versioning change can be cleanly versioned; existing tags (0.35.0 and earlier) have no versioned antora.yml.
• skainet_version is currently hand-bumped in docs/antora.yml, independent of the git tag — risk of drift.

✔️ Dependencies

• docs/antora.yml, docs/antora-playbook.yml, docs.yml workflow, the shared skainet-docs-ui bundle (version-picker support), and the Gradle generateDocs/dokkaGenerate/bundleDokkaIntoSite tasks.

---

📚 R: RESEARCH — What Must Be Understood First?

Research Tasks

• Decide aggregation home: dedicated docs repo vs. dedicated gh-pages/docs branch in this repo ("Architecture B").
• Resolve the generated-content-in-tags constraint — choose between: (a) a release-prep step that commits _generated_ into each release commit, or (b) build-per-tag that runs the Gradle toolchain at each tag and merges outputs under /<version>/.
• Confirm the skainet-docs-ui bundle renders the version selector for a versioned component.
• Decide how latest is aliased (redirect vs. Antora latest version).
• Review how other Antora multi-repo sites structure playbooks pulling several component repos.

Open Questions

• Do we version by full patch (0.36.0) or minor (0.36)?
• How should develop docs surface — a dev/snapshot prerelease version, PR-artifact only, or not at all?
• Should skainet_version be derived from the release tag automatically?

---

🛠️ C: CODE — Implementation Plan

Development Tasks

• Move docs/antora.yml off version: ~ to a real per-release version.
• Update the playbook content.sources to list release tags (and optionally develop as a prerelease), plus sibling repos when they onboard.
• Implement the chosen generated-content strategy (release-prep commit or build-per-tag merge).
• Stand up the aggregation target (repo or branch) and point deploy at it.
• Wire the version picker in the UI and a latest alias.
• Optionally derive skainet_version from the release tag.
• Update docs.yml / add an aggregation workflow accordingly.

Acceptance Criteria

• Site shows a version selector; each release is reachable at its own path.
• Generated operator pages + Dokka API render correctly for each versioned release.
• latest resolves to the newest release.
• At least one sibling repo's docs can be aggregated (or a clear path to add them).
• No regression to the current single-version-on-release publishing.

---

💬 Additional Notes

Related: #494 (docs-to-Antora migration). Follows the DARC workflow (docs/modules/ROOT/pages/contributing/darc-workflow.adoc).