[codeforester]

Summary

Users lack one reliable upgrade procedure across Homebrew, mutable source checkouts, and stable source tags. Add a canonical upgrade matrix and recovery guide, then link installation, shell, FAQ, command, and agent guidance to it.

The guide distinguishes current-main behavior from v1.10.5: update --release and reconciliation after an unchanged Homebrew version were added later. It covers older-version fallback, direct package-manager/Git operations, active-install selection, setup failures after a ref change, runtime verification, and trust re-review.

Issue

Fixes #2597

Related audit corrections are in #2629 / #2628. This PR can be reviewed independently; both are documentation-only and target main.

Validation

• Existing documentation, local-link, contract-hardening, command-reference, and version checks: 80 pytest cases passed.
• bats cli/bash/commands/basectl/tests/update.bats: all 28 cases passed, covering stable-tag upgrade/refusal/recovery, Homebrew reconciliation including unchanged versions, and mutable/project update behavior.
• All 50 local heading links across changed documents resolved. After linking the upgrade contract into the registry, reran contract hardening and documentation links: 15 passed.
• Compared the matrix and failure procedures against update.sh; git diff --check passed.
• No real Homebrew upgrade, source upgrade, setup, or trust mutation was performed.

Design Impact

Documents the implemented update routes and their boundaries. No runtime changes, automatic trust approval, downgrade capability, or new release-verification guarantee is introduced. Remote tag matching is explicitly distinguished from immutable release/BOM evidence.

Docs Impact

docs/upgrading.md is the canonical upgrade procedure. README, FAQ, documentation index, bootstrap recipes, shell-startup guidance, Homebrew rehearsal, command reference, and skills.md now point to it. Duplicate upgrade procedures were consolidated to reduce synchronization risk. The contract registry links the guide to existing update behavior tests while preserving the need for prose review.

AI Context Impact

Add the route-specific update summary and canonical guide reference to .ai-context/COMMANDS.md.

Release Notes

Add the missing Unreleased notes for stable-source --release support and unconditional Homebrew runtime reconciliation. Published release sections remain unchanged.

Demo Impact

None. Existing command and demo behavior is unchanged; upgrade verification and the distinction between Base and consumer-project tests are documented.