docs: consolidate Homebrew and source install recipes

FAQ.md

@@ -85,15 +85,8 @@ before Base can continue. It does not clone Base, install Python, create virtual
 environments, or run project setup.
 
 Use Homebrew when you already have Homebrew and Bash and want Base managed like
-an ordinary installed tool:
-
-```bash
-brew trust basefoundry/base
-brew install basefoundry/base/base
-basectl setup
-basectl update-profile
-exec "$SHELL" -l
-```
+an ordinary installed tool. Follow the canonical
+[Homebrew install recipe](docs/bootstrap.md#homebrew-install-recipe).
 
 Use the full formula name `basefoundry/base/base` for installs and upgrades.
 `basefoundry/base` is the tap name, not the formula, and bare `base` can resolve
@@ -105,14 +98,8 @@ that already trust `basefoundry/base`.
 
 Use a source checkout when you are contributing to Base or want to inspect and
 run the repository directly. This is also the preferred active install for a
-Base development machine:
-
-```bash
-git clone https://github.com/basefoundry/base.git ~/work/base
-~/work/base/bin/basectl setup
-~/work/base/bin/basectl update-profile
-exec "$SHELL" -l
-```
+Base development machine; follow the canonical
+[source checkout install recipe](docs/bootstrap.md#source-checkout-install-recipe).
 
 Use `install.sh` when you specifically want the source-install path to clone or
 update Base and then run setup/profile commands as one script.

README.md

@@ -21,12 +21,13 @@ inventory -> prepare -> verify -> trust -> onboard -> hand off
 
 ## Quickstart
 
-For the shortest complete source-checkout path:
+For the canonical source-checkout install commands, see the
+[source checkout install recipe](docs/bootstrap.md#source-checkout-install-recipe).
+Then run the trust-conscious project proof:
 
 ```bash
-git clone https://github.com/basefoundry/base.git ~/work/base
+# After completing the canonical source-checkout install recipe.
 ~/work/base/bin/basectl setup --dry-run
-~/work/base/bin/basectl setup
 ~/work/base/bin/basectl projects list --workspace ~/work
 ~/work/base/bin/basectl trust status base
 ```
@@ -92,14 +93,14 @@ for the command-by-command compatibility contract and non-GitHub Git workflow.
 
 ### Trust-Conscious Proof, No Dotfile Changes
 
-This trust-conscious evaluation path uses a source checkout. It lets you
-inspect the code, run setup explicitly, and prove the local project loop before
-Base touches shell startup files:
+This trust-conscious evaluation path uses a source checkout. First follow the
+[source checkout install recipe](docs/bootstrap.md#source-checkout-install-recipe),
+then inspect the code and prove the local project loop before relying on the
+shell handoff:
 
 ```bash
-git clone https://github.com/basefoundry/base.git ~/work/base
+# After completing the canonical source-checkout install recipe.
 ~/work/base/bin/basectl setup --dry-run
-~/work/base/bin/basectl setup
 ~/work/base/bin/basectl projects list --workspace ~/work
 ~/work/base/bin/basectl trust status base
 ```
@@ -170,18 +171,8 @@ normal Base install paths:
 - Use a source checkout when you want to inspect, contribute to, or dogfood Base
   from the repository.
 
-```bash
-# Homebrew-managed install
-brew trust basefoundry/base
-brew install basefoundry/base/base
-basectl setup
-```
-
-```bash
-# Source checkout install
-git clone https://github.com/basefoundry/base.git ~/work/base
-~/work/base/bin/basectl setup
-```
+See the canonical [Homebrew install recipe](docs/bootstrap.md#homebrew-install-recipe)
+or [source checkout install recipe](docs/bootstrap.md#source-checkout-install-recipe).
 
 For Homebrew installs, Base itself lives under Homebrew's prefix rather than in
 your project workspace. For source checkout installs, Base lives at the clone
@@ -1465,15 +1456,8 @@ prerequisites, a sibling `base-bash-libs` checkout, `basectl setup --dry-run`,
 The focused `bootstrap.sh --ensure-bash --yes` path is intentionally narrower:
 it installs only Bash after a dry-run review.
 
-Base can be installed through its Homebrew tap:
-
-```bash
-brew trust basefoundry/base
-brew install basefoundry/base/base
-basectl setup
-basectl update-profile
-exec "$SHELL" -l
-```
+For the complete Homebrew command sequence, see the canonical
+[Homebrew install recipe](docs/bootstrap.md#homebrew-install-recipe).
 
 Use the full formula name `basefoundry/base/base` for Homebrew installs and
 upgrades. `basefoundry/base` is the tap name, not the formula, and bare `base`
@@ -1555,14 +1539,8 @@ curl -fsSL https://raw.githubusercontent.com/basefoundry/base/HEAD/install.sh |
 Use `--no-profile` to skip shell startup integration and `--dry-run` to print
 planned actions.
 
-The explicit manual bootstrap path is:
-
-```bash
-git clone https://github.com/basefoundry/base.git ~/work/base
-~/work/base/bin/basectl setup
-~/work/base/bin/basectl update-profile
-exec "$SHELL" -l
-```
+For the explicit manual source-checkout command sequence, see the canonical
+[source checkout install recipe](docs/bootstrap.md#source-checkout-install-recipe).
 
 After the shell restarts, Base's managed startup section adds `~/work/base/bin`
 to `PATH`, so `basectl` can be run without spelling out the full path. Use

docs/bootstrap.md

@@ -112,14 +112,12 @@ focused `--ensure-bash --yes` path that installs only Bash.
 
 ## Contributor Path
 
-Contributors should prefer source mode:
+Contributors should first complete the [source checkout install recipe](#source-checkout-install-recipe),
+then add the sibling library checkout and contributor profile:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/basefoundry/base/HEAD/bootstrap.sh | bash -s -- --source
 git clone https://github.com/basefoundry/base-bash-libs.git ~/work/base-bash-libs
 ~/work/base/bin/basectl setup --profile dev
-~/work/base/bin/basectl update-profile
-exec "$SHELL" -l
 ```
 
 The sibling `base-bash-libs` checkout gives the source-tree BATS suite the
@@ -151,14 +149,15 @@ configure accounts, credentials, model access, or organization policy. See
 [Remote Installer Policy](remote-installer-policy.md) for the allowed URLs,
 dry-run behavior, non-interactive behavior, and managed-device guidance.
 
-## Relationship To Other Install Paths
+## Direct Install Recipes
 
-Use `bootstrap.sh` when the machine may not have Homebrew, Git, or a supported
-Bash yet. Homebrew bootstrap follows the remote installer trust model described
-in [Remote Installer Policy](remote-installer-policy.md).
+These are the canonical direct-install command sequences. Other Base
+documentation should link here rather than repeat them.
+
+### Homebrew Install Recipe
 
-Use Homebrew directly when Homebrew is already installed and Base should be
-managed like a normal formula:
+Use this path when Homebrew is already installed and Base should be managed like
+a normal formula:
 
 ```bash
 brew trust basefoundry/base
@@ -168,6 +167,26 @@ basectl update-profile
 exec "$SHELL" -l
 ```
 
+### Source Checkout Install Recipe
+
+Use this path when contributing to Base or running the repository directly:
+
+```bash
+git clone https://github.com/basefoundry/base.git ~/work/base
+~/work/base/bin/basectl setup
+~/work/base/bin/basectl update-profile
+exec "$SHELL" -l
+```
+
+## Relationship To Other Install Paths
+
+Use `bootstrap.sh` when the machine may not have Homebrew, Git, or a supported
+Bash yet. Homebrew bootstrap follows the remote installer trust model described
+in [Remote Installer Policy](remote-installer-policy.md).
+
+For a direct Homebrew install, use the
+[canonical Homebrew install recipe](#homebrew-install-recipe).
+
 Use `install.sh` when you specifically want the source-install script to clone
 or update Base and run setup/profile commands in one path. `bootstrap.sh` is the
 more complete first-mile path for blank machines.

docs/macos-install-validation.md

@@ -87,30 +87,18 @@ Use this path when validating the consumer install experience.
 
 ### Install
 
-For a machine that already has Homebrew:
-
-```bash
-brew trust basefoundry/base
-brew install basefoundry/base/base
-basectl setup
-basectl update-profile
-exec "$SHELL" -l
-```
+For a machine that already has Homebrew, follow the
+[canonical Homebrew install recipe](bootstrap.md#homebrew-install-recipe).
 
 For a first-mile bootstrap run that should choose the Homebrew route:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/basefoundry/base/HEAD/bootstrap.sh | bash -s -- --brew
 ```
 
-Then run the handoff commands printed by `bootstrap.sh`. They should include
-the Homebrew-managed `basectl` setup and profile steps:
-
-```bash
-basectl setup
-basectl update-profile
-exec "$SHELL" -l
-```
+Then run the handoff commands printed by `bootstrap.sh`, using the canonical
+[Homebrew install recipe](bootstrap.md#homebrew-install-recipe) as the expected
+setup and profile sequence.
 
 When validating Homebrew Base from a shell that may already be inside a source
 checkout or Base runtime shell, use the Homebrew-managed `basectl` path and
@@ -213,27 +201,14 @@ For bootstrap source mode:
 curl -fsSL https://raw.githubusercontent.com/basefoundry/base/HEAD/bootstrap.sh | bash -s -- --source
 ```
 
-Then run the handoff commands printed by `bootstrap.sh`. They should point at
-the selected source checkout:
-
-```bash
-<source-checkout>/bin/basectl setup --profile dev
-<source-checkout>/bin/basectl update-profile
-exec "$SHELL" -l
-```
-
-For a manual source clone:
-
-```bash
-git clone https://github.com/basefoundry/base.git <source-checkout>
-<source-checkout>/bin/basectl setup --profile dev
-<source-checkout>/bin/basectl update-profile
-exec "$SHELL" -l
-```
+Then run the handoff commands printed by `bootstrap.sh`, using the canonical
+[source checkout install recipe](bootstrap.md#source-checkout-install-recipe) as
+the expected checkout, setup, profile, and shell handoff sequence. For this
+validation path, use `--profile dev` when the run must validate
+`basectl test base`.
 
 Use plain `basectl setup` instead of `--profile dev` when the run is limited to
-the first-run user path. Use `--profile dev` when the run must validate
-`basectl test base`.
+the first-run user path.
 
 Accept the install when: