docs: align sync/snapshot AGENTS docs, README, and changelog for v1.0.0

[fullstackjam]

What does this PR do?

Aligns the last stale docs with the current CLI ahead of cutting v1.0.0: fixes internal/sync/AGENTS.md (referenced a nonexistent openboot sync command and cli/sync.go), updates internal/snapshot/AGENTS.md (8→12 capture steps; dock.go/loginitems.go and the real JSON field names were missing), adds --pick to the README options list, and retitles the CHANGELOG section to v1.0.0 with two bullets for the #160 behavior changes (interactive dry-run, --update help correction).

Why?

A project review found these as the remaining doc-drift items after #157. They are the last in-repo blockers before tagging v1.0.0 — the v1.0 spec in CHANGELOG.md is otherwise fully implemented.

Testing

• go vet ./... passes
• Relevant tests added or updated — docs-only change, no test delta
• go test ./internal/archtest/... passes (agent-config topology untouched); full L1 ran via pre-push hook

Cross-repo checklist

• Does this need a docs/content update in openboot.dev? — No: CLI-internal docs; README --pick line documents an existing flag
• Does this change the CLI ↔ server API contract? — No

Notes for reviewer

Content claims were verified against the code before writing: capture steps enumerated from captureSteps in internal/snapshot/capture.go, snapshot JSON keys from struct tags in internal/snapshot/snapshot.go, and the additive-only sync note from buildInstallPlan in internal/cli/sync_helpers.go. A separate session is handling the required-checks.txt / MERGE_POLICY alignment — deliberately not touched here.

[fullstackjam]

@claude please review this PR — it is docs-only (AGENTS docs, README, CHANGELOG). Focus on factual accuracy against the current code: the 12 capture steps, the snapshot JSON field names, the sync flow description (additive-only, no openboot sync command), and whether the CHANGELOG v1.0.0 bullets accurately describe the #160 behavior changes.

[claude]

Claude finished @fullstackjam's task in 2m 13s —— View job

---

Review: docs/AGENTS accuracy check

• Gather context (diff, changed files, referenced source code)
• Verify 12 capture steps in internal/snapshot/AGENTS.md against internal/snapshot/capture.go
• Verify snapshot JSON field names in internal/snapshot/AGENTS.md against internal/snapshot/snapshot.go
• Verify sync flow description in internal/sync/AGENTS.md against internal/cli/install.go / sync_helpers.go
• Verify CHANGELOG v1.0.0 bullets against refactor(tui): remove legacy install selectors #160 behavior changes
• Check README --pick addition
• Post review findings

Checked every factual claim in the diff against the current code (not just the doc's own internal consistency).

Confirmed accurate:

• 12 capture steps (internal/snapshot/AGENTS.md:20-31) — the order and names match captureSteps in internal/snapshot/capture.go:55-126 exactly (Formulae → Casks → Taps → NPM → Bun → Prefs → Dock Apps → Login Items → Git → Dotfiles → Dev Tools → Shell).
• Snapshot JSON field names (internal/snapshot/AGENTS.md:44-65) — every key (packages, macos_prefs, shell, git, dotfiles, dev_tools, matched_preset, catalog_match, dock_apps, login_items, health.failed_steps/health.partial) matches the struct tags in internal/snapshot/snapshot.go 1:1.
• File tables — line counts (capture.go 562, dock.go 268, loginitems.go 60, snapshot.go 202, source.go 102, diff.go 280, plan.go 212) and "6 source files" for the snapshot package all match wc -l.
• Sync flow (internal/sync/AGENTS.md:16-27) — openboot install (no args) → runSyncInstall in cli/install.go:388, the 3-way install / customize / cancel prompt (cli/install.go:442-469), and ExecuteContext(ctx, plan, dryRun) (sync/plan.go:99) are all real and match. buildInstallPlan (cli/sync_helpers.go:107) is confirmed additive-only — comment at line 106 states "Uninstall fields are never populated." ToSet (sync/diff.go:261) does delegate to internal/diff.ToSet.
• CHANGELOG bullets for refactor(tui): remove legacy install selectors #160: the "interactive dry-run" claim matches wizardMode() (cli/install.go:184-188, which deliberately excludes DryRun from the check, per its own comment) plus the [DRY-RUN MODE - No changes will be made] banner in installer.go. The --update bullet matches — the flag's registered help string is now "update Homebrew and exit" (cli/install.go:80), and the code path returns before touching any install source (cli/install.go:110-111).

Issue found — stale line adjacent to this PR's own edit:

• README.md:190 still reads --update Update Homebrew before installing, two lines below the --pick line this PR just added. That description is the exact misconception the new CHANGELOG bullet says was just corrected in the flag's own --help text ("previously implying it combines with an install"). Since this PR is specifically about doc/CLI accuracy for refactor(tui): remove legacy install selectors #160, this line should be updated too, e.g. to Update Homebrew and exit. Fix this →

Minor, not introduced by this PR:

• internal/snapshot/AGENTS.md:82 (unchanged by this diff) says "update totalSteps" when adding a capture step, but no totalSteps identifier exists anywhere in internal/snapshot — the real code just uses len(captureSteps). Since this PR already reworded the pipeline section above to reference captureSteps by name, this one leftover line in "WHEN MODIFYING" is now the only stale reference left in the file. Worth a follow-up, not blocking.

Everything else in the diff (README --pick wording, CHANGELOG retitle to v1.0.0, sync AGENTS.md restructuring) checks out against the current code.

[fullstackjam]

@claude the two findings are addressed in f7dca23 (README --update description, stale totalSteps reference). Please re-review the delta.

[claude]

Claude finished @fullstackjam's task in 25s —— View job

---

Re-review: delta from f7dca23

• Fetch latest commit and diff
• Verify README --update description fix
• Verify totalSteps reference fix in snapshot AGENTS.md
• Post final verdict

Both findings from the prior review are correctly addressed in f7dca23.

1. README --update description (README.md:190)
Now reads --update Update Homebrew and exit, which matches the flag's actual registered help string in internal/cli/install.go:80: "update Homebrew and exit". Verbatim match — no longer implies it combines with an install.

2. Stale totalSteps reference (internal/snapshot/AGENTS.md:82)
Now reads Adding capture step: Add an entry to captureSteps in capture.go, add to Snapshot struct. Confirmed captureSteps is the real identifier (internal/snapshot/capture.go:55), and totalSteps no longer appears anywhere in the file — the loop at capture.go:205-218 derives the total via len(captureSteps), consistent with the corrected doc text.

No new issues introduced by this follow-up commit. LGTM.