Generate migration guidance from one canonical contract

[flyingrobots]

Why

The v18-to-v19 command, root README, migration guide, and scripts/v18-to-v19/README.md currently repeat graph examples, flag semantics, and execution steps. The published --graph events example already demonstrated how copied guidance can drift from real repositories that host arbitrary, multiple graph namespaces.

Outcome

Define one canonical migration CLI/documentation contract and generate or mechanically verify every repeated command synopsis and example against it.

Acceptance criteria

• One source owns flag names, default behavior, confirmation semantics, and example placeholders.
• Root README, v19 migration guide, script README, and --help cannot disagree unnoticed.
• Examples use explicit placeholders and demonstrate discovered graph names rather than implying events is special.
• Documentation tests execute or snapshot the canonical examples.
• Error examples cover repository-not-found, graph-not-found, empty repository, and upgrade-not-needed states.
• The solution does not keep v18 runtime compatibility code in the v19 application path.

Related work

Follow-up debt from #806 and the migration-guide requirements tracked by #810. It is not a blocker for the immediate v19 correction unless the current fixes add another independently maintained copy.

[coderabbitai]

🔗 Related PRs

#664 - Resolve priority-next runtime boundary batch [merged]
#726 - Move graph exports behind v19 public API boundary [merged]
#788 - Add one-shot v18-to-v19 retained-substrate migration [merged]
#799 - Enforce one generated v19 vocabulary contract [merged]
#801 - Gate v19 on migrated retained-read speed [merged]

---

📝 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!