Goal
Consolidate the Homebrew and source-checkout install recipes, which are
currently written out three separate times each and have already drifted
out of sync with each other.
Background
A documentation review found:
- The Homebrew install recipe (
brew trust / brew install / basectl setup / ...) is written three separate times: README.md:144-149
("Start Here"), README.md:1433-1441, and FAQ.md:78-84. The copies have
already drifted — the "Start Here" version omits the basectl update-profile and exec "$SHELL" -l steps that both other copies
include, so the "identical" instructions already disagree on completeness.
- The source-checkout install recipe shows the same pattern:
README.md:151-155, README.md:1523-1530, and FAQ.md:98-103 — three
near-duplicate blocks (one shorter) that each require a synchronized edit
if install steps ever change.
- The same Homebrew quick-start is also restated verbatim in
docs/bootstrap.md:163-169 and twice more in
docs/macos-install-validation.md:92-98,109-113, with no "see
bootstrap.md" pointer anywhere.
Scope
README.md
FAQ.md
docs/bootstrap.md
docs/macos-install-validation.md
Acceptance Criteria
Validation
git diff --check; grep for the install command sequence across the repo to
confirm only one full copy remains (plus cross-references).
Non-Goals
- Changing what the install steps actually do — this is a
duplication/drift fix, not a behavior change.
Project Metadata
- Priority: P2
- Size: S
- Area: Docs
- Initiative: Adoption Polish
- Agent Assignment: Copilot candidate after triage (mechanical
de-duplication with a clear canonical source to point to)
Goal
Consolidate the Homebrew and source-checkout install recipes, which are
currently written out three separate times each and have already drifted
out of sync with each other.
Background
A documentation review found:
brew trust/brew install/basectl setup/ ...) is written three separate times:README.md:144-149("Start Here"),
README.md:1433-1441, andFAQ.md:78-84. The copies havealready drifted — the "Start Here" version omits the
basectl update-profileandexec "$SHELL" -lsteps that both other copiesinclude, so the "identical" instructions already disagree on completeness.
README.md:151-155,README.md:1523-1530, andFAQ.md:98-103— threenear-duplicate blocks (one shorter) that each require a synchronized edit
if install steps ever change.
docs/bootstrap.md:163-169and twice more indocs/macos-install-validation.md:92-98,109-113, with no "seebootstrap.md" pointer anywhere.
Scope
README.mdFAQ.mddocs/bootstrap.mddocs/macos-install-validation.mdAcceptance Criteria
copy of the source-checkout recipe exist (a good candidate location is
README.md's "Start Here" section and/ordocs/bootstrap.md).with a short pointer instead of a restated block.
basectl update-profileandexec "$SHELL" -l) so no copy is missingsteps.
Validation
git diff --check; grep for the install command sequence across the repo toconfirm only one full copy remains (plus cross-references).
Non-Goals
duplication/drift fix, not a behavior change.
Project Metadata
de-duplication with a clear canonical source to point to)