fix(docs): sync redirects with versioned snapshots

[johnnygreco]

Summary

Fix production tutorial links that redirect from /openshell/latest/tutorials/* to the retired /openshell/latest/get-started/tutorials/* tree and return 404. The docs snapshot sync updates pages and navigation but never synchronizes redirects, so obsolete production rules survive both stable and dev publishes.

Related Issue

No issue required: a localized documentation publishing bug. Searches of open and closed issues and PRs found no existing fix for redirect synchronization. #3713 addresses separate navigation/slug problems (including invalid about/run-an-agent redirect destinations), but does not change this sync path.

Changes

• Synchronize redirects with their owning mutable snapshot, replacing removed rules as well as adding/updating rules. A versioned source takes precedence over its destination when determining ownership; unversioned aliases to a versioned destination follow that version. dev owns shared fallback rules.
• Update latest rules only when stable promotion succeeds, preserving other versions and preventing an older maintenance release from rolling back current routing. Keep version-specific rules before shared wildcards.
• Document channel ownership and manual repair, and update the docs contributor skill.

Audited 115 published navigation URLs, checking both the default unversioned paths and explicit /latest paths. Exactly 10 returned 404: each of the following with and without /latest:

Page	Path below /openshell[/latest]
Tutorials landing	/tutorials
Run Pi with OpenRouter	/tutorials/run-pi-with-openrouter
First Network Policy	/tutorials/first-network-policy
GitHub Push Access	/tutorials/github-push-access
Microsoft Graph Provider Refresh	/tutorials/microsoft-graph-provider-refresh

These also affect 11 authored MDX links: the home Tutorials card; the Pi link in Run Your First Agent; links in provider profiles, sandbox overview, policy overview, network rules, and the first network policy tutorial; and four cards in the currently orphaned tutorials index. The four tutorial sidebar entries are affected too. The canonical versioned Pi URL under /v0.1.1/tutorials/run-pi-with-openrouter returns 200.

After merging, repair production with a latest snapshot sync and publish using the updated automation. Retain the source SHA, release version, display name, and availability recorded on docs-website. Republishing docs-website without syncing will retain the stale redirects. A local replay against the actual production configuration and v0.1.1 source removed all four obsolete rules and installed the correct tutorial aliases without changing the version entries. This PR does not publish production.

Testing

• mise run pre-commit passes.
• Unit regression tests: all 29 docs snapshot tests pass; all three new cases fail against the original implementation. They cover both latest and stable, deleted redirects, repeated syncs, other-version preservation, wildcard ordering, and older maintenance releases.
• mise run test passes (complete Rust, Python, TypeScript, and tooling suite).
• mise run python:typecheck and all 29 docs tests pass after the final type annotation correction.
• mise run docs: zero errors, three warnings.
• Fern validation of the locally repaired production configuration: zero errors, six warnings.
• Live HTTP audit and production snapshot replay described above.
• Full mise run ci: the final rerun failed in unchanged Go SDK test TestExecInteractive_ServerError (expected permission denied, got: EOF). An earlier rerun hit the unchanged SBOM request-spacing timing test (44.8 ms vs. a 45 ms minimum), which passed on retry. The Go failure also reproduces in an isolated five-run invocation. No Go or SBOM files changed in this PR.
• E2E sandbox tests are not applicable to docs publishing.

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).
• Architecture docs updated.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

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

[johnnygreco]

/ok to test cf4520f

[purp]

gator-agent

PR Review Status

This focused docs-publishing fix is project-valid, but the initial review found one blocking redirect-ownership edge case.

Action required: make redirect source the stable rule identity when channel ownership changes, and add the cross-owner regression test described inline.

Blocking findings:

• GATOR-cf4520fc-01: moving an unversioned source between channel owners can retain the old rule alongside the replacement.

Carried findings:

• None

Non-blocking suggestions:

• None

Gator metadata

• Validation: Maintainer-authored, concentrated documentation publishing bug fix with clear production impact and no duplicate work found
• Docs: Fern operations documentation and the contributor skill are updated
• Checks: Current-head required checks are green
• E2E: N/A; this changes documentation snapshot publishing, not sandbox runtime behavior
• Head SHA: cf4520fc16f5700c78be8a07f83dbe47a334130a
• Base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
• Merge base SHA: c9da461a588f04b4ae1cc9f46aff98e30ca1bf44
• Patch ID: 5607cbb38634ebdfa21e0ba85161c259d74ae1fb
• Gator payload: 9
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[purp]

LGTM 🚢

[purp]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: required checks passed, maintainer approval was present, and the sole Gator warning was explicitly accepted for possible follow-up and its review thread was resolved.

I removed the active gator:* label because there is nothing left for Gator to monitor on this PR.

Gator metadata

• Head SHA: cf4520fc16f5700c78be8a07f83dbe47a334130a
• Gator payload: 9
• Previous state: gator:in-review
• Final state: merged