docs(maintenance): curate public docs and retain one snapshot per minor

[kevkantes]

Summary

Curate the public documentation site, move historical implementation artifacts to Git history/tags after promoting live architecture, remove the unsupported workshop, and retain one intentional documentation snapshot per supported minor line.

Problem

The public Docusaurus site currently mixes supported product documentation with repository history:

• docs/docs/specs/ contains 569 tracked files (about 4.4 MB) and is included through an autogenerated Specifications sidebar.
• The spec folders use several naming and status conventions, including Draft, Implemented, In-use, Abandoned, and partial. Sixteen tracked tasks.md files still contain unchecked tasks.
• docs/docs/workshop-archive/ is about 6.9 MB. It is absent from the hand-written sidebar but remains part of the built/searchable docs tree.
• The current docs/docs/workshop/ tree is about 12 MB and contains material for retired A2A/supervisor layouts alongside large one-off repair scripts. Its current support status is not documented.
• docs/published-versions.json lists 0.6.0, 0.5.69, and 0.4.18. Every site build checks out release tags into worktrees and generates each snapshot with custom link/MDX repair logic.
• The current retention script allows five patches of the current minor plus the highest patch of two older minors; its own comment estimates another 1–2 GB of Docusaurus heap for every retained version.

This makes the site harder to search, makes old implementation plans look authoritative, and raises build cost. Git tags and history already preserve the implementation record; the public site should optimize for users and current contributors.

Team decision (2026-08-21)

• Public navigation and search contain current user, operator, architecture, contributor, and release/migration documentation.
• Durable architecture decisions are curated into a small ADR/current-architecture index instead of requiring readers to infer truth from historical feature specs.
• Completed/abandoned feature specs, plans, task lists, and workshop archives are removed from the working tree/public build after still-live decisions are promoted; Git history and release tags are the documented recovery path.
• The current/root workshop is unsupported and should be removed rather than repaired.
• Publish latest plus one snapshot per supported minor line. The snapshot is the final/highest supported patch for that line. A concise 0.x selector label may point to that snapshot, but the site must not present 0.5.69 content as literal 0.5.0.

Acceptance criteria

• Record this documentation information architecture and support/version-retention policy in the contributor docs.
• Classify the current specs, workshop, workshop archive, release notes, upgrade guides, and ADR/architecture content against that policy.
• Inventory inbound links before moving or unpublishing content; add redirects for externally useful pages.
• Promote still-valid decisions from historical specs into canonical architecture or component documentation.
• Remove historical specs, task/plan artifacts, and workshop archives from the working tree/public build after the Git history/tag recovery path is documented.
• Remove the unsupported current/root workshop and all live navigation/references to it.
• Reduce published-versions.json and the snapshot generator to latest plus one final snapshot per supported minor; remove repair code that only supports versions no longer published.
• Make supported/EOL versions explicit in the version selector and release/upgrade documentation.
• Resolve or refresh Refactor Docs - Update theme, publish version doc #1352 now that versioned documentation exists and the remaining question is retention rather than initial publication.
• Verify the Docusaurus build, internal links, search index, redirects, and version selector after each staged change.

Related

• Refactor Docs - Update theme, publish version doc #1352
• Discussion Release Management & Versioning Strategy #945

Constraints

• Preserve current release notes and required upgrade/migration guidance for supported versions.
• Do not silently destroy history; Git tags/history must remain a documented recovery path.
• Do not treat an old spec as the canonical explanation for live behavior.

[kevkantes]

Maintainer clarification from the repository simplification review:

• Keep the newest released patch from the latest three minor lines (n, n-1, and n-2).
• At the time of this decision, those snapshots are 0.6.0, 0.5.69, and 0.4.18.
• Display concise selector labels 0.6 (Latest), 0.5, and 0.4; each label remains backed by the actual patch tag.
• Keep development/main clearly identified as Next, not as the latest released documentation.
• Retain all historical release notes and upgrade posts even when their full documentation snapshots fall outside the three-minor window.

Draft PR #2455 implements the snapshot policy; draft #2454 separately removes historical Spec Kit material from the public build.