docs: document the Base upgrade contract across Homebrew and source installs #2597

Goal

Document the complete Base upgrade contract for consumers who installed Base through Homebrew, a mutable source checkout, or a stable tagged source checkout.

Problem

The current documentation describes installation recipes and the basectl update command separately, but it does not give a consumer a single answer to:

I am on Base version N. How do I upgrade to the later Base version?

The gap is especially visible for stable source checkouts. The stable-install recipe uses an immutable release tag, while the general basectl update contract describes updating a repository on its default branch. Users cannot currently tell whether they should use basectl update, git, brew, basectl setup, or a reinstall when moving between releases.

Related runtime issue: #2596.
Related Homebrew matrix coverage: #2562.

Required documentation

Add a canonical upgrade matrix, preferably in a dedicated upgrade document linked from the README, bootstrap/install guidance, and shell-startup documentation. The matrix must cover:

The documentation must also explain:

• the difference between upgrading Base itself and updating a consumer project;
• that basectl update <project> updates that project, while omitted project targets Base;
• when basectl setup <project> is required;
• that basectl update-profile refreshes shell integration and is not the Base upgrade operation;
• Homebrew/source coexistence and how to confirm the active basectl with command -v and type -a;
• --dry-run, --verify-project-runtime, and manifest/test-requirement trust re-review after contract changes;
• failure recovery for dirty, non-default, detached, or mixed installations.

Acceptance Criteria

• A new user can choose the correct upgrade command from one table.
• Homebrew, mutable source, and stable tagged source behavior are stated separately.
• The documented commands match the implemented behavior and do not imply that check mutates state.
• The Base upgrade flow and consumer-project setup/test flow are distinguished.
• README, bootstrap/install, shell-startup, and Homebrew rehearsal links do not contradict the canonical upgrade contract.
• The stable tagged source section either documents the supported one-command implementation from the companion issue or clearly states the current limitation until that issue lands.
• Documentation checks or focused examples protect the command matrix from future drift.

Non-Goals

• Do not implement the stable-tag one-command upgrade here; track that in the companion implementation issue.
• Do not change Homebrew runtime reconciliation behavior; track that in bug: Homebrew Base upgrade can leave a stale base-cli in the managed venv #2596.

Background

The October documentation audit found stale Homebrew guidance in skills.md (D08) and missing unreleased upgrade notes (part of D11). Runtime reconciliation (#2608) and stable-source --release support (#2609) are now merged, so document their current behavior.

Scope

Complete the canonical upgrade matrix and related links described above; reconcile FAQ, command, shell-startup, installation, and agent guidance with current main. Include missing unreleased upgrade notes without changing runtime code.

Validation

Compare each documented route with update.sh and existing upgrade regression tests; run focused update BATS, documentation/command-reference tests, and git diff --check. Do not perform a real package-manager upgrade.

Project Fields

• Status: In Progress
• Priority: P2
• Size: M
• Area: Docs
• Initiative: Contract Hardening
• Milestone: v1.11.0

Agent Assignment

Codex implements in a dedicated issue-backed documentation worktree; codeforester is the accountable maintainer. Open a validated PR for review without merging. Related audit corrections are tracked separately in #2628.