docs: author the 0.1.0 upgrade guide

[drew]

Description

Author and publish a consolidated OpenShell 0.1.0 upgrade guide for users, operators, SDK consumers, and extension authors. The guide must enumerate the coordinated breaking changes tracked by #2565 and give readers concrete, tested instructions for moving from the latest supported pre-0.1.0 release or development contract to 0.1.0.

The guide is a release deliverable, not a copy of individual issue descriptions. It should organize changes by the workflow a reader must update and provide before/after examples, required sequencing, validation steps, and rollback considerations.

Context

#2565 requires migration notes that enumerate every breaking change before the public beta compatibility boundary. The planned work currently spans policy behavior, pagination, workspace scoping, typed mutations, sandbox references, idempotency and structured errors, protobuf well-known types, deprecated policy fields, watch/stream behavior, extension negotiation, and the Helm gateway configuration contract.

Upgrade information is currently distributed across issue bodies, reference pages, and component-specific compatibility notes. Without one authoritative guide, users must infer migration requirements and ordering, increasing the chance of policy regressions, incompatible generated clients, broken automation, or failed gateway upgrades.

The guide should treat all child issues under #2565 as a live source inventory rather than hard-coding only the children that exist when this ticket is opened. It must also incorporate relevant 0.1.0 changes merged outside the parent when they affect an externally consumed contract.

Required Content

• Define the supported upgrade starting point(s), prerequisites, compatibility boundary, and whether skipped-version upgrades are supported.
• Provide a migration matrix mapping each breaking change to affected personas, components, old behavior, new behavior, required action, and the issue or documentation that defines the contract.
• Separate sections for gateway/API consumers, CLI automation, each supported SDK, policy authors, Helm/Kubernetes operators, and extension authors.
• For protobuf/API changes, show representative before/after request and response shapes, regeneration requirements, error/status changes, pagination and streaming behavior, and mixed-version constraints.
• For policy changes, explain fail-closed behavior and removal of deprecated fields without weakening the safe default.
• For Helm changes, document the removal of individually templated gateway values, the gatewayConfig YAML-map-to-TOML contract from feat(helm)!: replace mirrored gateway settings with YAML-to-TOML configuration #3060, and an exhaustive old-value-to-new-key mapping.
• Document configuration, credential, persistence, and extension-state migrations. Explicitly state when automatic or in-place migration is unsupported and give the safe operator procedure.
• Include pre-upgrade inventory and backup steps, an ordered upgrade procedure, post-upgrade verification, common failure symptoms, and rollback constraints. Do not claim rollback is safe across an irreversible schema or state migration unless that path is tested and supported.
• Link to canonical reference documentation instead of duplicating complete contract specifications.
• Distinguish required migration steps from optional adoption of new capabilities.

Definition of Done

• A dedicated 0.1.0 upgrade guide is published under docs/ and added to docs/index.yml navigation.
• The guide states the exact supported source and target versions and the public compatibility boundary established by RFC-0014.
• Every breaking or migration-relevant child issue under Stabilize public API, SDK, and extension contracts for 0.1.0 #2565 is represented in a traceable migration matrix, including issues added after this ticket is opened.
• The guide also accounts for externally visible 0.1.0 changes not parented under Stabilize public API, SDK, and extension contracts for 0.1.0 #2565, or explicitly records why none apply.
• Each affected workflow includes concrete before/after examples and an observable verification step.
• Helm migration includes an exhaustive mapping from removed legacy chart values to gatewayConfig TOML tables/keys or retained Kubernetes packaging values.
• API and SDK migration covers generated-code regeneration, supported package versions, request/response changes, error handling, pagination, watches, streams, and mixed-version behavior.
• Policy and extension migrations cover removed fields, new failure semantics, version negotiation, and capability discovery where applicable.
• Preflight, backup, ordered rollout, post-upgrade validation, troubleshooting, and rollback sections are included and technically reviewed.
• All commands and configuration examples are validated against the final 0.1.0 artifacts; placeholders and speculative instructions are removed before release.
• Existing scattered pre-0.1.0 compatibility notes are updated to link to the guide, reconciled with it, or removed when obsolete.
• Relevant release notes link prominently to the upgrade guide.
• Documentation follows docs/CONTRIBUTING.mdx, passes the documentation checks, and has no duplicate body H1.

Dependencies

This ticket depends on the externally observable behavior and migration decisions in #2565 and its child issues being sufficiently final to document. Drafting can proceed earlier, but final validation must use the released or release-candidate 0.1.0 artifacts.