v2 docs: rewrite end-user documentation after product reset

[shpoont]

Problem

The current draft end-user manual documents the previous product model. It should not be patched incrementally until the revised sync-first model is reflected in the spec and implementation.

Scope

Rewrite the production end-user documentation after the v2 reset work defines the final nouns, workflows, and CLI behavior.

Inputs

• The reusable documentation quality acceptance criteria in shpoont/ai-work-common-assets.
• The revised product concept and vocabulary.
• The final status/diff/sync UX and command behavior.
• The recipe catalog/tap model.
• The new-computer bootstrap flow.

Acceptance criteria

• Documentation starts by explaining what the tool does, where settings are stored, and how live app settings relate to stored settings.
• The happy path is sync-first: status, diff, sync in the needed direction.
• Docs cover many-app workflows, one-app workflows, partial sync, smart sync, conflict handling, remote catalogs, and new-computer setup.
• Docs do not present backup/restore, v1 migration, users, or a mandatory Git repo as core concepts.
• The recipe format is explained with real examples and a clear path for advanced users to add unsupported apps.
• The docs include copy/pasteable commands, expected output excerpts, safety notes, troubleshooting, glossary, and examples.
• The rewrite is reviewed against the shared documentation acceptance criteria before a production docs PR is opened.

#219 audit follow-up

Source: #219 audit merged in #220 (docs/internal/project/v2-reset-audit-issue-219.md).

Additional acceptance criteria and blockers:

• Do not start the production rewrite until v2 reset: revise product concept and vocabulary around settings storage #210-v2 reset: define new-computer bootstrap flow #215 and their required split/design issues produce accepted behavior and examples.
• Treat current prototype docs as prototype/current-behavior material until rewritten; do not copy-edit them into production docs without removing reset conflicts.
• Rewrite around status/diff/sync, settings storage folder, supported apps, conflicts, catalogs, bootstrap, and advanced recipe authoring.
• Remove backup/restore, v1 migration, legacy v1 workflows, mandatory Git repo, and first-class user-account concepts from the core docs.
• Review the rewrite against the shared documentation acceptance criteria in shpoont/ai-work-common-assets before opening a production docs PR.

Project Execution Standards alignment

Latest standard read for this update: /Users/shpoont/Work/shpoont/project-execution-standards/project-execution-standard.md, last-updated 2026-06-29.

Project record / source of truth: #209 plus docs/internal/project/v2-reset-execution-record.md; this issue owns production end-user documentation rewrite.

Risk tier: Tier 1.
Reason: production end-user documentation is a user-facing surface and must not describe unverified behavior as final.

Delivery type: production documentation rewrite after accepted behavior/examples exist.

Documentation-first rule:

• Draft end-user documentation is a pre-implementation/user-comprehension test surface for future feature work.
• Production docs for implemented behavior must be reconciled against real CLI behavior before publication, handoff, acceptance, or closure.

Dependencies:

• Use accepted behavior/examples from v2 catalogs: implement official catalog discovery baseline #228/v2 catalogs: implement official and remote catalog management with write gates #229 catalog work and v2 bootstrap: specify new-computer UX and output #230/v2 bootstrap: implement apply-from-storage flow after sync model #231 bootstrap work.
• Use the shared documentation quality acceptance criteria in shpoont/ai-work-common-assets.

Real-result verification required:

• Commands and examples in production docs must be runnable or mechanically checked where practical.
• Any behavior not verified against the real CLI must be labeled draft, experimental, future, or out of scope.

Change rule:

• Changes to documentation scope, publication readiness, accepted behavior claims, or verification requirements are managed changes requiring Project Owner decision.

No-go actions:

• Do not copy-edit current user docs into production docs while preserving reset conflicts.
• Do not present backup/restore, v1 migration, mandatory Git repo, users, internal pseudo-app targets, or unavailable catalog lifecycle commands as core happy-path concepts.

Acceptance rule / closure rule:

• Project Owner acceptance is required before closing.
• Closure must record docs review against the reusable documentation criteria, real-command verification evidence or explicit limitations, and any follow-up issues for deferred or draft areas.