Define and satisfy the v19 migration guide requirements

[flyingrobots]

Hill

Make the v19 migration documentation and command sufficient for an operator who has a real v18 repository, no prior Wesley knowledge, multiple possible graph namespaces, and a finite disk budget. The user must be able to discover the right graph, understand code-generation versus retained-data migration, preview cost and mutations, confirm deliberately, observe progress, recover safely, and verify success without reading implementation source.

Requirements learned from the live migration review

Preflight and discovery

• Validate --repo as a Git repository and report an invalid/missing path distinctly from a missing git executable; never collapse either into spawn git ENOENT.
• Treat graph names as user-selected namespaces, never as a hard-coded or privileged events graph.
• When a requested graph is absent, say Graph not found and list discovered graphs.
• For every discovered graph, show ref/writer counts and whether it is current, requires v18-to-v19 migration, or has an unsupported marker.
• Preserve multiple independent git-warp graphs in one Git repository and scope all work to the selected graph.

Operator control and observability

• Use current Bijou application patterns for tables, alerts, confirmation, and progress.
• Show a read-only plan before work and ask for confirmation before inventory, scratch verification, or apply work.
• Provide explicit noninteractive/automation behavior such as --yes and structured output.
• Display phase and bounded progress for discovery, inventory, rewrite, scratch verification, finalize, and verification.
• Explain expected duration drivers and provide a conservative disk-space estimate before confirmation.

Migration semantics and safety

• Explain exactly what each phase reads and writes, how scratch verification works, where temporary data lives, and when refs can change.
• Explain interruption, cleanup, compare-and-swap, concurrent-writer, backup, and recovery posture.
• Keep legacy v18 implementation out of the v19 runtime; one-time compatibility code belongs under scripts/v18-to-v19/.
• Prove the migration with a deliberately small v18-generated fixture; do not commit a live Think database or hundreds of megabytes/gigabytes of fixture data.
• Make dry-run, apply, repeat-run/idempotency, and post-migration verification behavior explicit.

Application migration

• Explain what Wesley is, why v19 uses generated application users, how to generate them, what files result, and how applications import/use them.
• Distinguish generated application/API migration from the one-time retained-substrate rewrite.
• Provide a small end-to-end application example that does not assume Think-specific knowledge.
• Add a source-anchored Mermaid relationship model to the public API topic, with linear prose carrying the same meaning.

Child slices

• Make v18-to-v19 migration discover graphs before confirmation #806 - graph discovery, confirmation, progress, and multi-graph safety
• Explain Wesley and user generation in the v19 migration guide #807 - Wesley and generated-user guidance
• Add a Mermaid relationship model to the public API topic #808 - public API relationship diagram
• Document v19 migration mechanics and disk-space requirements #809 - migration mechanics and disk-space requirements

Acceptance

A v18 application maintainer unfamiliar with git-warp internals can complete a small rehearsal and then a real migration using the published v19 package and documentation alone. All examples are parameterized, all mutations are previewed and confirmed, progress and capacity needs are visible, and successful verification says which selected graph is now current.

[coderabbitai]

🔗 Related PRs

#105 - Plan v18 release runway [merged]
#788 - Add one-shot v18-to-v19 retained-substrate migration [merged]
#813 - Define streaming indexed recursive WARP architecture [open]
#825 - Make v18-to-v19 migration safe and observable [open]
#829 - Make v19 generation and migration guidance executable [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!