[#1005] docs(install-mac): Update macOS installation for the current QuadWork release

[realproject7]

Closes #1005

Summary

Docs-only. Reconciles docs/install-mac.md with the current CLI, SetupWizard, README, and package metadata (v2.7.0), removing stale v1.14.5-era wording and correcting commands that no longer match the code. Scope: docs/install-mac.md only.

Changes

• Verify step: quadwork --version is not a real subcommand — it falls through to the usage help (bin/quadwork.js dispatch: init/start/stop/add-project/cleanup/doctor/migrate-agent-slugs/ac-restore, else usage). Replaced with npm list -g quadwork, and updated the example version 1.14.5 → 2.7.0 (package.json).
• Dashboard URL: server binds loopback (server/index.js:2324 → server.listen(PORT, "127.0.0.1"), logging QuadWork server listening on http://127.0.0.1:${PORT}) and the CLI auto-opens http://127.0.0.1:${port} (bin/quadwork.js:928). Corrected localhost → 127.0.0.1, dropped the unverified QuadWork dashboard: … stdout example, and documented the auto-open behavior.
• First-run setup / per-role models: documented the Agent Models step — per-role CLI backend (Claude Code / Codex / Gemini CLI, SetupWizard.tsx:188-192) plus optional per-role model selection (src/lib/agentModels.ts — Claude opus/sonnet/…, Codex gpt-5.4/gpt-5.6-*, Gemini gemini-2.5-pro/-flash, (CLI default)). Corrected the seed-files note to AGENTS.md and CLAUDE.md per worktree (SetupWizard.tsx:81).
• Trust prompt: removed the stale "QuadWork v1.14.5+ automatically pre-trusts …" claim and the claude -p "echo ok" manual workaround — [#S9] De-block the event loop (file-chat busy-wait, butler/setup execFileSync) #975 dropped that synchronous pre-trust. Described the current behavior: an onData trust-listener on each agent PTY auto-answers the prompt at startup (server/index.js:1114-1119, :1182).

EPIC Alignment

• Batch 24 ticket docs(install-mac): Update macOS installation for the current QuadWork release #1005 owns only docs/install-mac.md. This diff touches exactly that file.
• Shared invariant (document current behavior only when verified): every changed claim is tied to a current source line cited above.
• Out of scope, untouched: runtime code, package versions, tests, legacy cleanup/migration implementation, and all other docs.

Self-Verification

• Version/metadata: package.json → name: quadwork, version: 2.7.0, engines: {node: ">=20"}.
• Subcommands: bin/quadwork.js:1352-1400 — no --version; unknown args print usage. init/start/stop all present and used as documented.
• Loopback bind + auto-open: server/index.js:2324; bin/quadwork.js:928 (dashboardUrl = http://127.0.0.1:${port}).
• Port default 8400 / server.pid / caffeinate: bin/quadwork.js:253,864,911,947; server/index.js:311 — unchanged doc claims re-confirmed accurate.
• Backends + per-role models: src/components/SetupWizard.tsx:188-192, src/lib/agentModels.ts:10-45.
• Trust listener: server/index.js:1114-1119 (old pre-trust dropped), :1182-1185 (auto-answer within first ~10s).
• Worktree naming: bin/quadwork.js:630-631 — project-head/, project-re1/, project-re2/, project-dev/.
• Residual-stale scan: rg -n "1\.14|localhost|claude -p|quadwork --version" docs/install-mac.md → only the legitimate node/git/gh --version prereq lines remain.
• Scope: git diff --stat → docs/install-mac.md only.
• CI: pending on push.

Acceptance criteria

• Stale v1.14.5-era version language removed
• Only commands verified against the current project retained
• CLI install, authentication, first-run setup, per-role model selection, worktree creation, start/stop behavior distinguished
• Optional bridge guidance kept accurate
• No runtime code changes

[project7-interns]

Verdict: REQUEST CHANGES

Epic Alignment: FAIL

#1005 requires every command and prerequisite claim to be verified against current sources; the PR's verification evidence misidentifies a source location.

Checked (evidence)

• Scope: live gh pr diff 1013 → only docs/install-mac.md.
• Installation/model/trust content: current head confirms package version 2.7.0, CLI dispatch, model catalog, and trust listener.
• Riskiest part of this diff: lifecycle/network guidance; its body evidence is incorrect as detailed below.
• Kill-list: scanned all new diff ranges — documentation-evidence hit listed in Findings.
• CI: gh pr checks 1013 → test pass (50s).

Findings

• [blocking] Dashboard-bind citation is incorrect.
  • File: server/index.js:270
  • Why it fails: The PR's ## Self-Verification cites this as the dashboard loopback bind, but it is only the checkPort probe. The documentation claim is supported by the actual server listener at server/index.js:2324; #1005 requires honest, source-verified guidance.
  • Do instead: Change the PR body's loopback-bind citation from server/index.js:270 to server/index.js:2324, then request re-review. No documentation diff is required for this correction.

Decision

The guide’s changed prose otherwise matches the current implementation, but the required verification record is inaccurate and must be corrected before approval.

[realproject7]

@re2 Independent Review — APPROVE ✅ (head 6a44dc5)

Checked (evidence)

• quadwork --version is not a subcommand — the CLI dispatch switch (command) (bin/quadwork.js:1351) handles init/start/stop/add-project/cleanup/doctor/migrate-agent-slugs/ac-restore only; --version falls through to usage. Doc's switch to npm list -g quadwork is correct; version 2.7.0 matches package.json. ✓
• Dashboard URL http://127.0.0.1:8400 — server binds loopback: srv.listen(port, "127.0.0.1") (server/index.js:270), default port 8400; CLI auto-opens http://127.0.0.1:${port} (bin/quadwork.js). Old localhost wording corrected. ✓
• Agent Models step / per-role backends — BACKENDS (src/components/SetupWizard.tsx:188-191): claude→"Claude Code", codex→"Codex", gemini→"Gemini CLI"; "Agent Models" step label at :34; optional per-role model selection via src/lib/agentModels.ts. ✓
• Seed files — doc's "AGENTS.md and CLAUDE.md per worktree" matches current seeding (consistent with docs: Remove stale AgentChattr claims from repository guidance and README credits #1004). ✓
• Trust prompt rewrite ([#S9] De-block the event loop (file-chat busy-wait, butler/setup execFileSync) #975) — comment at server/index.js:1114-1118 confirms [#S9] De-block the event loop (file-chat busy-wait, butler/setup execFileSync) #975 dropped the synchronous claude -p "echo ok" pre-trust; the onData trust-listener at :1182-1190 auto-answers the prompt (safeWrite(term, "1\\r")). Removing the stale v1.14.5 pre-trust wording + manual workaround is accurate. ✓
• Scope — diff is docs/install-mac.md only (+20/−24); no runtime/tests/package/other-docs changes (git diff --name-only origin/main → single file). ✓
• CI — gh pr checks 1013 → test pass (50s). ✓

Non-blocking nit: doc says the trust prompt is confirmed "within the first few seconds" while the code window is 10s (:1182) — immaterial, not a blocker.

Verdict: APPROVE on 6a44dc5. (Recorded as a comment; shared bot account cannot self-approve on GitHub.)

[project7-interns]

Verdict: APPROVE

Epic Alignment: PASS

The unchanged one-file guide remains aligned with #1005; the corrected verification record now accurately supports its loopback lifecycle guidance.

Checked (evidence)

• Re-review scope: same current head 6a44dc5; only the PR body changed after my review.
• Prior finding resolved: PR ## Changes and ## Self-Verification now cite server/index.js:2324, the actual server.listen(PORT, "127.0.0.1", …) listener, instead of the checkPort probe at :270.
• No diff re-review required: live PR remains docs/install-mac.md only; prior command, model, worktree, bridge, and trust-listener checks stand.
• Riskiest part of this diff: loopback dashboard guidance; its code citation now matches the running server implementation.
• Kill-list: no new ranges since my last review — clean.
• CI: gh pr checks 1013 → test pass (50s).

Findings

• None.

Decision

The sole blocking evidence error is corrected without a code change; the current head satisfies #1005 and has a passing live check.

[realproject7]

@re2 Corrected Verdict — APPROVE ✅ (head 6a44dc5)

Correcting my prior evidence: the dashboard-server loopback bind is server.listen(PORT, "127.0.0.1", …) at server/index.js:2324 (logs QuadWork server listening on http://127.0.0.1:${PORT}). My earlier :270 citation was the throwaway port-availability probe inside checkPort() (net.createServer().listen(port, "127.0.0.1")), not the dashboard listener. The doc's http://127.0.0.1:8400 claim remains correct; only my line reference was wrong.

Checked (evidence)

• Dashboard URL http://127.0.0.1:8400 — dashboard server binds loopback at server/index.js:2324 (server.listen(PORT, "127.0.0.1", …)); default port 8400; CLI auto-opens http://127.0.0.1:${port} (bin/quadwork.js). Old localhost wording corrected. ✓
• quadwork --version is not a subcommand — dispatch switch (command) (bin/quadwork.js:1351) handles init/start/stop/add-project/cleanup/doctor/migrate-agent-slugs/ac-restore only; --version falls through to usage. npm list -g quadwork fix correct; version 2.7.0 matches package.json. ✓
• Agent Models step / per-role backends — BACKENDS (src/components/SetupWizard.tsx:188-191): claude→"Claude Code", codex→"Codex", gemini→"Gemini CLI"; "Agent Models" step label at :34; per-role model selection via src/lib/agentModels.ts. ✓
• Trust prompt rewrite ([#S9] De-block the event loop (file-chat busy-wait, butler/setup execFileSync) #975) — server/index.js:1114-1118 confirms [#S9] De-block the event loop (file-chat busy-wait, butler/setup execFileSync) #975 dropped the synchronous claude -p "echo ok" pre-trust; the onData trust-listener at :1182-1190 auto-answers (safeWrite(term, "1\\r")). ✓
• Scope — docs/install-mac.md only (+20/−24); git diff --name-only origin/main → single file. ✓
• CI — gh pr checks 1013 → test pass (50s). ✓

Verdict: APPROVE on 6a44dc5. (Recorded as a comment; shared bot account cannot self-approve on GitHub.)