diff --git a/CLAUDE.md b/CLAUDE.md
index 64da028c..b60bb8b7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -219,9 +219,17 @@ bunx tsgo        # typecheck (not tsc)
 bun test         # tests
 bun format       # prettier over every dirty file — see the note below before running it
 bun db:push      # apply the schema to Postgres
-bun setup        # runs scripts/setup/officer-setup.sh — IN PROGRESS, sections 1-6 of 10
+bun setup        # runs scripts/install.sh — blank machine to running platform
 ```
 
+`scripts/install.sh` is only an orchestrator — it runs the two halves in order and does nothing itself:
+`setup/machine-setup/machine-setup.sh` (28 sections: packages, tailnet, runtimes, docker, shell) then
+`setup/officer-setup.sh` (11: pre-flight, layout, repository, dependencies, database, environment, secrets,
+schema, build, services, verify). Either runs alone — `--machine-only`, `--officer-only`, or by path — because
+a machine you already trust needs only the second. Both are re-runnable: each records the steps it finished
+and skips them, so stopping halfway costs nothing. **Run it as yourself**; it re-execs through `sudo` when it
+needs to, and on macOS never does, because Homebrew refuses to run as root.
+
 Sidecar control is PM2, not npm scripts: `pm2 restart officer-<name>`, `pm2 logs officer-<name>`.
 See `docs/working-on-officer.md` for which process a given change needs restarted.