Skip to content

Docs: Homebrew/source-checkout install recipes duplicated 3x and already drifted #1943

Description

@codeforester

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

  • One canonical copy of the Homebrew install recipe and one canonical
    copy of the source-checkout recipe exist (a good candidate location is
    README.md's "Start Here" section and/or docs/bootstrap.md).
  • All other locations either link to the canonical copy or are replaced
    with a short pointer instead of a restated block.
  • The canonical recipe includes the complete step sequence (including
    basectl update-profile and exec "$SHELL" -l) so no copy is missing
    steps.

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)

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

Status
Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions