feat(docs): publish versioned release snapshots

[pimlock]

Summary

Publish versioned Fern docs from the generated docs-website branch for development and stable releases. Development releases update the mutable dev snapshot. Stable tags create an immutable vX.Y.Z snapshot and update latest only when the release is not older than the current Latest version.

The reusable workflow records source provenance, validates the complete generated site, commits the branch once, and makes one serialized Fern production publish attempt after the other release publication jobs succeed.

Related Issue

Related to #1296. This automates dev, immutable tagged versions, and SemVer-safe latest promotion. Prerelease qualification previews and documentation feature filtering remain follow-up work tied to RFC 0014.

Changes

• Add optional Fern availability metadata and preserve it for snapshots that are not being refreshed.
• Label development docs as Dev (vX.Y.Z.devN) with Beta availability.
• Record each managed snapshot's source commit and release version on docs-website.
• Reject stale development updates and conflicting identities for the same development version.
• Create an immutable vX.Y.Z snapshot for each stable tag.
• Promote latest only when the stable tag is not older than the recorded Latest version, preventing N-1 maintenance releases from moving Latest backward.
• Mark qualified releases starting with v0.1.0 as Stable while leaving current v0.0.x releases unlabelled.
• Keep shared Fern configuration, components, assets, and CSS owned by the development snapshot so an older release tag cannot rewind the site shell.
• Queue docs operations under the shared docs-website concurrency group instead of replacing pending runs.
• Wait for the other release publication jobs before publishing docs.
• Keep an explicit manual rollback input for an authorized mutable-channel rollback.
• Upgrade the Fern CLI to 5.112.0.
• Document the automated and manual publishing paths.

Testing

• mise run pre-commit
• mise run test:docs-website with 19 tests
• mise run test completed the Python, TypeScript, docs publishing, SBOM, install, packaging, build environment, and release-range suites successfully
• The Rust portion of mise run test cannot link locally because the system Z3 library is not installed
• E2E tests added or updated, not applicable

The docs tests cover stable snapshot creation, SemVer promotion, N-1 maintenance behavior, migration from the existing metadata-free generated branch, stale development runs, immutable source collisions, shared Fern ownership, queue configuration, and release workflow dependencies.

Checklist

• Follows Conventional Commits
• Commits are signed off for DCO
• Architecture docs updated

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3149.docs.buildwithfern.com/openshell

[pimlock]

gator-agent

PR Review Status

This is valid work for accepted issue #1296, but two correctness problems in snapshot identity and promotion need changes before pipeline handoff. Thanks @pimlock—I also checked your note about the queue concurrency attribute against the intended workflow behavior and did not add it as a Gator finding.

Action required: bind immutable snapshots to resolved commit SHAs and ensure stable promotion replaces the complete pages-latest tree, with regression coverage for both paths.

Blocking findings:

• GATOR-4c72d173-01: A movable source ref can overwrite an immutable version snapshot.
• GATOR-4c72d173-02: Stable promotion can retain stale release-local components in latest.

Carried findings:

• None

Non-blocking suggestions:

• None

Gator metadata

• Validation: Project-valid implementation of accepted issue #1296 by a maintainer-author.
• Docs: Architecture publishing documentation is updated; no additional Fern navigation change is required for this automation path.
• Checks: Current-head required GitHub checks are green, but review blockers remain.
• E2E: No additional E2E label is required for docs publication automation; current E2E gate statuses are green.
• Head SHA: 4c72d1735bee7f28f596ff4159de1d4da917a8c6
• Base SHA: e64b0352e8965bec7e5683cb231ca38f9d4760ce
• Merge base SHA: e64b0352e8965bec7e5683cb231ca38f9d4760ce
• Patch ID: e22230adb408de936d389dc31a41e71ad6f48eb7
• Gator payload: 8
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[pimlock]

gator-agent

PR Review Status

Thanks @pimlock. The current head resolves both prior snapshot correctness findings: immutable identity is now bound to the checked-out commit SHA for stable and version channels, and stable promotion replaces the complete pages-latest tree while leaving the shared Fern shell dev-owned. The added regression cases cover both paths, the publishing workflow is now documented in fern/README.md, and no blocking findings remain in the follow-up delta.

Blocking findings:

• No blocking findings remain

Carried findings:

• None; GATOR-4c72d173-01 and GATOR-4c72d173-02 are resolved on this head

Gator metadata

• Validation: Project-valid implementation of accepted issue #1296 by a maintainer-author.
• Docs: The versioned publishing model and operator workflow are documented in fern/README.md, with contributor and architecture links updated; no Fern site-navigation change is required.
• Checks: Required Branch Checks are queued or running and Helm Lint is successful for the current head.
• E2E: No additional E2E label is required for docs publication automation; current E2E gate statuses are successful.
• Head SHA: 6734f1f7eb42b322168662b3903a50a8797053d8
• Base SHA: e64b0352e8965bec7e5683cb231ca38f9d4760ce
• Merge base SHA: e64b0352e8965bec7e5683cb231ca38f9d4760ce
• Patch ID: 50bc1ac4611daa445306b664e7e68e3e26ab7250
• Gator payload: 8
• Review mode: follow_up
• Previous reviewed SHA: 4c72d1735bee7f28f596ff4159de1d4da917a8c6
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:watch-pipeline