User-facing v1 to v2 schema migration guide #189

Is your feature request related to a problem? Please describe.

Consumers migrating from the legacy v1 output to canonical schema v2 have no guide. The comparison report (docs/design/notes/l1-v1-v2-comparison.md) is a point-in-time measurement for maintainers — it answers "did we lose anything?", not "my code read symbol_table[path].type_declarations[fqn].callable_declarations[sig].code, what do I write now?". Those are different audiences with different lifecycles: the measurement is deliberately frozen, a guide must stay current as the schema evolves.

Describe the solution you'd like

• Field-by-field old → new mapping table (type_declarations → types, callable_declarations → callables, code → source[body_span.bytes], call_sites → body call nodes, flat is_* booleans → kind, annotations → structured decorators, thrown_exceptions → error_channel, …)
• Before/after access examples for the common reads, including get_method_body
• The semantic shifts consumers can trip on: symbol_table keys become relative, types are keyed by simple name and nested rather than flat by FQN, identity is the can:// id rather than the signature, and edges are identity-only
• The CLI surface (--schema, -c/--cache-dir, --eager) and which levels each covers
• Where it lives in the published docs, and how it is kept current as levels land

Describe alternatives you've considered

Not stated in the original issue.

Additional context

Scope boundary

A user-facing migration guide only. Not the comparison report (already committed, stays development-oriented), and not SDK code changes (python-sdk#310).

Deliberately deferred until there is a migratable surface: v2 covers L1 only today, with no call_graph (#181), no Neo4j projection (#182), and no migrated SDK (python-sdk#310). Writing it earlier would document a shape that #181/#182 change.

Caveats and known risks

• Must be revised as codeanalyzer-java: L2 v2 call_graph (identity edges + external_symbols) #181/codeanalyzer-java: Neo4j v2 projection — L4 SDG overlay (after L4; base+L3 landed via #198) #182 land; write it late enough that it is not immediately stale.
• The keystone defines get_method_body as module.source[callable.span.bytes], which is not v1's body-only code semantics — the guide must document body_span and flag the upstream discrepancy.

Definition of done

• A consumer can migrate a v1 read to its v2 equivalent using only the guide.
• Every mapping is verified against a real emitted payload, not against prose.