[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.

Review follow-up

• The README's Homebrew upgrade link now points to the canonical upgrade guide; the install recipe remains the new-install entry point.
• Updated the AI command context and its help-output assertion for the stable-source --release <tag> behavior.
• Added --release <tag> and the guide link to the basectl update row in the technical overview.

For this follow-up revision, git diff --check passed. The broader local test results above were collected before these final edits; hosted checks for the current head are running.

[codeforester]

Duplicate command entry. This PR adds a brand-new basectl update [project] bullet here (describing the upgrade behavior), but an existing bullet for the exact same command signature already exists further down in this same "Current Public Commands" list (line 232: - \basectl update [project]` - update Base or a named project; Homebrew always...). The two entries now use different, non-identical wording for the same command, which creates drift risk (a future edit to one won't update the other) and is confusing for anyone — human or AI agent via basectl export-context— reading the command list top to bottom. Consider removing one of the two entries, or merging them into the single pre-existing slot nearupdate-profile/version`.

[codeforester]

Dropped --no-ask guidance for direct Homebrew upgrades. This section's brew upgrade basefoundry/base/base command omits the --no-ask flag. The paragraph this PR deletes from docs/shell-startup.md specifically recommended brew upgrade --no-ask basefoundry/base/base "so Homebrew skips the preview prompt path on already-current installs," and that detail still survives, unchanged, in docs/release-process.md and docs/homebrew-upgrade-rehearsal.md for the identical action. Since this new file is now the canonical "Upgrade Contract" that README.md, docs/bootstrap.md, skills.md, and docs/shell-startup.md all point readers to, it should carry the --no-ask flag too (or explain why it's no longer needed) — otherwise this consolidation makes the canonical doc less complete than the docs it supersedes, and the sibling docs it did not touch now disagree with it.

[codeforester]

Review finding (not inline — file isn't in this diff): cli/bash/commands/basectl/README.md was left out of the sweep and now contradicts the new canonical upgrade contract.

cli/bash/commands/basectl/README.md (around line 240) still describes basectl update [project] as:

basectl update [project] updates the selected project checkout through Git and then runs basectl setup <project>. Omitting the project selects base; Homebrew-managed Base installs still hand off only the Base package to brew upgrade basefoundry/base/base, then run setup against the newly linked Homebrew executable. If Homebrew is run directly, follow it immediately with basectl setup; the formula upgrade alone does not reconcile the managed runtime or exact base-cli requirement.

This file wasn't touched by this PR (confirmed via git diff main...HEAD -- cli/bash/commands/basectl/README.md, which is empty), yet it disagrees with the newly published docs/upgrading.md and the updated docs/command-reference.md/.ai-context/COMMANDS.md on two points that actually matter per cli/bash/commands/basectl/subcommands/update.sh:

1. It says Git updates "then run basectl setup <project>" unconditionally, but the implementation (lines ~872-879 of update.sh) only runs setup when the revision actually changed — otherwise it's skipped.
2. It never mentions --release <tag>, the stable-tagged-source-checkout upgrade path this PR is specifically documenting everywhere else.

Since this PR's whole purpose is to eliminate exactly this kind of scattered/contradictory basectl update documentation, worth updating this README too (or linking it to docs/upgrading.md) so it doesn't keep drifting from the new canonical contract.

[codeforester]

Re-checked at 84d0ec9 (latest commit). CI is green and the branch is mergeable, but 2 of the 3 findings from the earlier review are still unaddressed, and the third is only partially fixed:

1. Duplicate basectl update [project] bullet — partially fixed. .ai-context/COMMANDS.md:232 now has corrected wording, but the duplicate at line 35 (added by this PR, both under the same ## Current Public Commands list) still uses different phrasing from line 232. No longer factually contradictory, but still a duplicate entry with inconsistent wording in the same list — worth consolidating to one bullet.
2. docs/upgrading.md:65 — still not fixed. The Homebrew upgrade command is still brew upgrade basefoundry/base/base without --no-ask, while docs/release-process.md (lines 296/306) still requires --no-ask for the same operation.
3. cli/bash/commands/basectl/README.md:240 — still not fixed. Still says update [project] unconditionally runs basectl setup <project>, with no mention of --release <tag>, contradicting the now-published docs/upgrading.md / .ai-context/COMMANDS.md:232 description of Git updates only reconciling setup when the revision changes.

Not blocking on CI/mergeability, but these should land before merge to avoid shipping the upgrade docs with an internal inconsistency.