docs: publish the installation-route upgrade contract

.ai-context/COMMANDS.md

@@ -32,6 +32,11 @@ the v1.x compatibility window; new automation should use `--debug-wrapper`.
   environment and optional project artifacts. Project `--dry-run` previews run
   through Base's interpreter and work before the project virtualenv exists,
   without creating or recreating that environment.
+- `basectl update [project]` - update Base by default, or the named consumer
+  project. Current Homebrew updates always reconcile setup; ordinary Git
+  updates do so only when the revision changes. Stable Base source checkouts
+  can use `--release <tag>`. Consult `docs/upgrading.md` for version availability,
+  older-version fallback, explicit setup, trust, and recovery.
 - `basectl check [project]` - check Base readiness only by default; pass a
   project name or `--manifest` to also check manifest-declared project
   requirements. It does not install or repair prerequisites, modify project

CHANGELOG.md

@@ -18,9 +18,13 @@ numeric next development line is tracked in `DEVELOPMENT_VERSION`.
 - Stability compatibility: publish workspace-test JSON schema version 2 so
   automation can distinguish trust-blocked and not-run projects from tests
   that actually executed.
+- Reconcile pinned Base runtime requirements after Homebrew upgrades even when
+  the formula version is unchanged, using the newly linked executable.
 
 ### Added
 
+- Upgrade clean, detached Base source checkouts to a reviewed later stable tag
+  with `basectl update --release <tag>`, including a preview and setup recovery.
 - Stability compatibility: enroll the new `basectl gh review fetch` and
   `basectl gh review prune` command contracts, including the migration path
   from ordinary local `pr-*` branches to namespaced detached review refs.

FAQ.md

@@ -259,6 +259,20 @@ route.
 
 ## Setup, Profile, And Diagnostics
 
+### How Do I Upgrade An Existing Base Installation?
+
+Use the [Upgrade Contract](docs/upgrading.md). Homebrew and mutable default-branch
+source installs use `basectl update`. A stable detached source checkout uses
+`basectl update --release <tag>` when that option is available; older versions
+use the documented pinned-checkout procedure. Confirm the active executable
+with `command -v basectl` and `type -a basectl` before choosing a route.
+
+Omitting the project updates Base itself. `basectl update example` updates the
+consumer project instead. Direct Homebrew or Git operations need an explicit
+setup step. `update-profile` refreshes shell integration and does not upgrade
+Base. The upgrade guide distinguishes current-main features from v1.10.5 and
+explains runtime verification and trust re-review.
+
 ### What is the difference between basectl setup and basectl update-profile?
 
 `basectl setup` prepares Base and project prerequisites: Homebrew artifacts,

README.md

@@ -33,6 +33,8 @@ inventory -> prepare -> verify -> trust -> onboard -> hand off
 
 For the canonical source-checkout install commands, see the
 [source checkout install recipe](docs/bootstrap.md#source-checkout-install-recipe).
+For an existing installation, use the [Upgrade Contract](docs/upgrading.md)
+to select the Homebrew, mutable-source, or stable-tag procedure.
 For the complete install-to-verified-project-PR journey, see the
 [adopter golden path](docs/adopter-golden-path.md).
 Then run the trust-conscious project proof:

docs/README.md

@@ -8,6 +8,9 @@ the documentation map.
 For contribution workflow, branch naming, tests, and PR expectations, see
 [CONTRIBUTING.md](../CONTRIBUTING.md).
 
+For an existing installation, see [Upgrading Base](upgrading.md), including
+Homebrew, mutable source, stable tags, and recovery after setup failures.
+
 For the public support front door, discussion categories, response target, and
 discussion-to-issue workflow, see [Community Support](community-support.md).
 

docs/bootstrap.md

@@ -285,29 +285,10 @@ basectl update-profile
 exec "$SHELL" -l
 ```
 
-For upgrades, prefer `basectl update`, which runs the Homebrew upgrade and then
-reconciles the managed Base environment. If Homebrew is run directly, follow
-it with setup through the newly linked executable; `brew upgrade` alone does
-not reconcile an existing managed environment:
-
-```bash
-brew upgrade basefoundry/base/base
-env \
-  -u BASE_HOME -u BASE_BIN_DIR -u BASE_CLI_DIR -u BASE_BASH_DIR \
-  -u BASE_BASH_COMMANDS_DIR -u BASE_LIB_DIR -u BASE_BASH_LIB_DIR \
-  -u BASE_SHELL_DIR -u BASE_OS -u BASE_HOST -u BASE_SHELL \
-  -u BASE_PLATFORM_TOOLS_HOME -u BASE_PLATFORM_TOOLS_BIN_DIR \
-  -u BASE_PROJECT -u BASE_PROJECT_ROOT -u BASE_PROJECT_MANIFEST \
-  -u BASE_PROJECT_VENV_DIR \
-  "$(brew --prefix base)/libexec/bin/basectl" setup
-```
-
-Verify the result before running project tests:
-
-```bash
-basectl check base --verify-project-runtime
-basectl test base
-```
+For existing installations, use the [Upgrade Contract](upgrading.md#homebrew).
+It covers `basectl update`, direct Homebrew upgrade plus explicit setup,
+version availability, trust review, and readiness verification. A package
+upgrade alone does not reconcile an existing managed Base environment.
 
 ### Stable Source Install Recipe
 
@@ -322,7 +303,9 @@ exec "$SHELL" -l
 ```
 
 The stable checkout reports `basectl 1.10.5`. For future releases, replace the
-release version and tag with the intended published release.
+release version and tag with the intended published release. To upgrade an
+existing stable checkout, follow [Stable Tagged Source Checkouts](upgrading.md#stable-tagged-source-checkouts),
+including the fallback for versions without `update --release`.
 
 ### Source Checkout Install Recipe
 

docs/command-reference.md

@@ -57,7 +57,7 @@ full compatibility contract.
 |---|---|---|
 | `basectl setup [project]` | Install or reconcile Base and optional project artifacts. Project-originated IDE app, extension, and user-setting mutations require separate approval. | `--project <name>`, `--ci`, `--format <text\|json>`, `--profile <dev,sre,ai>`, `--dry-run`, `--manifest <path>`, `--yes`, `--allow-project-ide-mutations`, `--recreate-venv`, `--upgrade-pip`, `--notify`, `--no-notify` |
 | `basectl update-profile` | Create, refresh, or remove Base-managed Bash and Zsh startup snippets, backing up existing dotfiles before changes. | `--defaults`, `--no-defaults`, `--remove`, `--dry-run` |
-| `basectl update [project]` | Update a Base-managed project checkout through Git, or update Base through Homebrew when Base is Homebrew-managed, then run setup for the selected project. | `--project <name>`, `--release <tag>`, `--dry-run` |
+| `basectl update [project]` | Update Base or a selected project through its installation route. Ordinary Git updates run setup only when the revision changes; current Homebrew updates always reconcile setup. Stable Base source tags use `--release`. See [Upgrading Base](upgrading.md) for version availability and recovery. | `--project <name>`, `--release <tag>`, `--dry-run` |
 | `basectl onboard [project]` | Guide first-run setup through check, setup, shell profile, doctor, project discovery, and read-only manifest trust status. Defaults to `base`. | `--project <name>`, `--profile <list>`, `--dry-run`, `--yes`, `--allow-project-ide-mutations`, `--no-profile` |
 | `basectl version` | Show the installed Base version. | `--all`, `--json` |
 

docs/contracts.md

@@ -29,7 +29,7 @@ before treating the fix as complete.
 | Read-only inspection JSON | [Inspection JSON](inspection-json.md), [Command Quick Reference](command-reference.md) | `cli/bash/commands/basectl/tests/inspection-json.bats`, `cli/python/base_release/tests/test_engine.py`, [`base-cli/tests/test_inspection.py`](https://github.com/basefoundry/base-cli/blob/main/tests/test_inspection.py), `tests/test_stability_tiers_docs.py` | A scoped command emits prose or invalid JSON, changes the v1 envelope, loses finding/error semantics, or diverges from text-mode exit policy | CLI |
 | Project metadata defaults | `.github/base-project.yml`, [GitHub Workflow](github-workflow.md), [Repository Baseline](repo-baseline.md) | `cli/python/base_github_projects/tests/`, `cli/bash/commands/basectl/tests/gh.bats`, `cli/bash/commands/basectl/tests/repo.bats` | Issue defaults, Project field options, or repo-visible Project configuration drift from the Base Project schema | Product |
 | Canonical positioning documentation | [Product Requirements](product-requirements.md), [Product Assessment](product-assessment.md), [Why Base](why-base.md), and the canonical introduction surfaces | `tests/test_contract_hardening.py` | A canonical newcomer, contributor, or agent surface reintroduces retired product positioning or drops the accepted local-operating-contract thesis and outcome loop | Product |
-| Adopter golden path | [Base Adopter Golden Path](adopter-golden-path.md), [First-Mile Bootstrap](bootstrap.md), [Manifest Command Trust](manifest-command-trust.md), and [GitHub Workflow](github-workflow.md) | `tests/test_adopter_golden_path_docs.py` | The install-to-first-verified-project-PR journey becomes ambiguous, hides trust or platform boundaries, or loses actionable recovery guidance | Adoption |
+| Adopter golden path | [Base Adopter Golden Path](adopter-golden-path.md), [First-Mile Bootstrap](bootstrap.md), [Upgrading Base](upgrading.md), [Manifest Command Trust](manifest-command-trust.md), and [GitHub Workflow](github-workflow.md) | `tests/test_adopter_golden_path_docs.py`, `cli/bash/commands/basectl/tests/update.bats` (upgrade behavior; prose completeness still needs review) | Installation, upgrade, or the first verified project PR becomes ambiguous, hides trust or platform boundaries, or loses actionable recovery guidance | Adoption |
 | Native Windows support boundary | [Native Windows Support Contract](windows-support.md), `README.md`, canonical product/context docs, and `.github/workflows/windows-contract.yml` | `tests/test_windows_support_docs.py` | A public surface or release note claims native Windows support before the launcher, command subset, and clean-install gates exist | Platform |
 
 ## Contract Check Runner

docs/homebrew-upgrade-rehearsal.md

@@ -8,6 +8,11 @@ separate from the tap update checklist: the tap checklist proves the formula can
 be published, while this rehearsal proves an existing user can upgrade without
 losing local Base state.
 
+Use [Upgrading Base](upgrading.md) for the consumer command matrix, runtime
+reconciliation, version availability, and recovery. This rehearsal exercises
+the direct Homebrew route plus explicit setup; it does not replace the
+`basectl update` route described there.
+
 ## Preconditions
 
 - Run on a macOS machine or test account that can install Homebrew packages.

docs/shell-startup.md

@@ -45,32 +45,17 @@ run `basectl update-profile --no-defaults` to disable them again. Plain
 `BASE_PROFILE_VERSION` records the schema version of this Base-managed file. It
 is reserved for future migrations and is not intended to be edited by users.
 
-Update Base or a Base-managed project checkout with:
-
-```bash
-basectl update
-basectl update bankbuddy
-```
-
-Omitting the project is equivalent to `basectl update base`. This command is
-intentionally conservative. In a source checkout, it only runs from the selected
-project repository's default branch, requires tracked project files to be clean,
-pulls the latest changes through Git, and runs `basectl setup <project>` only
-when the pull changes the checked-out revision. Untracked files do not block the
-update; Git still stops the pull if an incoming tracked file would overwrite
-them.
-
-In a Homebrew-managed install, the Base update path remains Base-only:
-`basectl update` runs the Base package upgrade,
-`brew upgrade basefoundry/base/base`, and runs `basectl setup base` with
-inherited Base environment variables cleared only when the installed Base version
-changes. `basectl update --dry-run` prints the Git or Homebrew handoff it would
-perform without changing files or packages.
-For manual Homebrew upgrades outside `basectl update`, prefer
-`brew upgrade --no-ask basefoundry/base/base` so Homebrew skips the preview
-prompt path on already-current installs. If Homebrew refuses to load
-`basefoundry/base/base-bash-libs` from an untrusted tap, run
-`brew trust basefoundry/base` once and retry the upgrade.
+For Base and consumer-project upgrades, follow the [Upgrade Contract](upgrading.md).
+It distinguishes Homebrew, mutable default-branch source checkouts, and stable
+source tags. Current Homebrew updates reconcile setup even when the formula
+version is unchanged; ordinary Git updates run setup only when the revision
+changes. Stable Base source upgrades use `update --release` when supported by
+the installed version.
+
+`basectl update-profile` only refreshes managed shell integration. Run it when
+the selected installation path or shell configuration changes, then open a
+fresh shell and confirm the active `basectl`. It does not replace upgrading
+Base or reconciling its runtime with setup.
 
 Base also reads `~/.baserc` when it exists. Unlike `profile.conf`, `~/.baserc`
 is user-managed and may be hand-edited. It is intended for simple,