docs: add migrated macOS recovery guidance

[codeforester]

Summary

Document a safe recovery path for inherited or migrated macOS accounts with stale shell state, Rosetta/native Homebrew mismatches, Xcode prerequisites, and Homebrew prefix ownership problems. Keep the recovery steps read-only until the user explicitly selects the compatible install path, and direct users to the source-checkout path when the Homebrew prefix cannot be repaired safely.

Scope

This PR documents the first-mile recovery path. It does not change bootstrap behavior or automatically repair Homebrew ownership; any future read-only bootstrap preflight should remain a separately reviewed change.

Validation

• 7 focused documentation/bootstrap/troubleshooting tests
• git diff --check

Fixes #2389

[codeforester]

Automated review findings

1. Violates this same file's own documented convention: the new "Inherited Or Migrated macOS Accounts" section repeats the exact canonical install command sequence (brew trust, brew install, basectl setup, basectl update-profile, exec "$SHELL" -l) instead of linking to it. docs/bootstrap.md itself states elsewhere: "These are the canonical direct-install command sequences. Other Base documentation should link here rather than repeat them." The new copy has already drifted from the canonical version too (adds a PATH export and an extra basectl setup --dry-run step) - exactly the kind of divergence the "link, don't repeat" rule exists to prevent, since a future edit to the canonical recipe can silently miss this copy.

2. Ordering issue in the diagnostic steps: a manual diagnostic block calls bare brew --prefix (ambient PATH) before the doc has told the reader to fix their PATH. On the exact scenario this section addresses (a stale /usr/local/bin/brew shadowing /opt/homebrew/bin/brew on PATH), this resolves to the wrong (Intel) prefix, not the native one the user believes they "selected" from the earlier candidate loop - the PATH export that would fix this doesn't appear until later in the same section. If brew isn't resolvable at all yet, brew_prefix is empty and the constructed path becomes a literal system path, so the ownership check silently reports on the wrong directory instead of failing cleanly.

Posted via Claude Code