Document the normal release path and recovery cases

[shiny-code-bot]

Objective

Update release documentation so the normal ship path is obvious and exceptional paths are clearly labeled.

Finish Line

Release docs identify the normal workflow, channel meanings, validation evidence, and recovery paths.

Current Status

State: Active
Next action: Update docs after workflow behavior is chosen.
Blocked by: Release orchestration and notarization workflow decisions.
Waiting for: Implementation shape from related sub-issues.
Last verified: 2026-05-28.

Scope

• In: docs/release.md, any repo metadata needed for release gate expectations.
• Out: Marketing release notes and App Store listing copy.

Acceptance Criteria

• Docs identify the one normal release workflow.
• Docs explain GitHub Release vs App Store Connect upload vs optional TestFlight beta distribution vs App Store review submission.
• Docs state that TestFlight beta testing is not required for App Store review and is skipped by default for now.
• Docs state when notarization is required.
• Docs include post-release evidence checks.
• Docs include recovery guidance for GitHub-only success, App Store Connect upload-only success, optional TestFlight failure, notarization failure, and App Store review submission follow-up.

Relationships

Part of the release hardening parent plan. Blocked by the workflow design until the final command names and inputs are known.

Validation

• Follow the docs against a dry run or actual release and verify no missing steps.

Decisions

• 2026-05-28: The normal Apple path is App Store Connect upload followed by manual App Store review selection/submission. TestFlight beta distribution is optional and skipped by default for now.

Open Questions

• Should release evidence be copied into GitHub release notes, workflow summaries, or both?