docs: user-facing v1 to v2 schema migration guide

[sinha108]

Problem

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.

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.

Goals

• 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

Caveats and known risks

• Must be revised as codeanalyzer-java: L2 v2 call_graph (identity edges + external_symbols) #181/codeanalyzer-java: Neo4j v2 projection — consolidated base relabel + L3/L4 overlays (after L4) #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.