docs: migration page

[ocots]

Summary

Full rewrite of docs/src/migration.md (was a 4-line stub) per docs/reports/10-migration.md Part 2 — the last content page in the docs rewrite (PR 12 of the split; PR 13 will drop docs/attic/ once this merges).

• ## Start here: Flow needs an integrator — the single most common first failure
• ## What was renamed — old→new spelling table
• ## What changed shape — the flow call convention, constrained flows, augment= → variable_costate=, the is_ keyword prefix
• ## What changed meaning silently — three !!! warnings: Lift(f::Function) no longer isa AbstractHamiltonian, OpenLoop wrong-arity failing only at run time, and a genuine silent argument-position misread on the old 4-positional flow call against an OptimalControlFlow
• ## What you get instead of an error — every src/deprecated.jl shim's actual PreconditionError message
• ## What could not be shimmed, and why — the 5 spellings that can't be intercepted, with the real current failure mode for each
• ## Legacy initial guesses — harvested from docs/attic/manual-initial-guess.md
• ## v1.x → v2.0 — pointer into BREAKING.md, not a copy

Every quoted error message and every "silent" behavior claim was live-verified against the current package rather than transcribed. That turned up two stale claims, both fixed in this PR:

• BREAKING.md itself said a missing integrator gives a bare MethodError — it's actually a clean ExtensionError naming the missing package.
• The spec's "NamedTuple form dropped from attic/manual-initial-guess.md" turned out to mean dropped from the docs, not the code — init=(state=..., control=...) still works fine, it's just undocumented since @init became the recommended path.

Adds the two still-missing outbound links (geometry/lift.md, flows/simulation.md) to satisfy the acceptance criterion — geometry/overview.md, geometry/ad.md, and results/solution.md already linked here from earlier PRs.

Page is deliberately non-executing (plain fences, not @example) since it exists to show spellings that error — stated at the top.

Test plan

• julia --project=docs docs/make.jl runs clean end to end (exit 0, zero unresolved @refs in any file this PR touches)
• Every shim message quoted on the page live-verified against src/deprecated.jl's actual output, not just re-read from source
• The three "silent" hazards live-reproduced, not just cited

🤖 Generated with Claude Code