docs: document SysML v1 migration on the API, guide and roadmap

[devin-ai-integration]

What and why

sysml -convert migrates a SysML v1 model (UML XMI, Eclipse UML2 .uml, .mdzip) to v2, and docs/reference/sysml-v1-migration.md states the mapping — but the other surfaces that reach it did not say so. ConvertRequest.from_format listed only the notation and RDF names, ConvertResponse.experimental said "either format is RDF", and neither wire-contract.md, api.md nor the Python convert docstrings mentioned XMI; there was no worked example of a migration; and the roadmap had no entry for the follow-ups the reference names.

• API and clients. sysml.proto comments on from_format, to_format and experimental (Go and Java stubs regenerated with make proto-buf); a Conversion: Convert section in wire-contract.md (source oneof, all nine format names, extension inference, canonical xmi/sysml/ttl in the response, the experimental fields, that the report is CLI-only, and which refusals are Connect-level vs in-body); api.md, python-api.md, guide chapter 9 and the Python docstrings say the same. The Go client gains opensysml.FormatXMI, the format a Conversion answers when ConvertFile read a v1 source, so the Go documentation can name it; Conversion.Experimental is documented as set for a migration too.
• Walkthrough. New guide chapter 11 docs/guide/11-migrating-from-sysml-v1.md: the .xmi/.uml/.mdzip/-from invocations, -migration-report in text and JSON, the four verdicts with the fixture's real report, the placeholder comments in the notation, how to finish units (ISQ/SI), behaviors, operations and opaque expressions by hand, checking the result with -eval, the gRPC/client path, and that v2 → v1 is refused. Linked from the guide index, chapter 7, chapter 9 and mkdocs.yml.
• Roadmap. D13 under Track D: behaviors; operations and receptions; units and quantity kinds (after L5); the report over gRPC and in the clients; stable identity for a re-migration (after D3); then measuring and lifting the experimental notice. Threaded into the labels note and both open-items summaries.

One thing the walkthrough surfaces rather than hides: the migrated fixture warns End feature must have multiplicity 1 on end driver : Driver[0..1] — the mapping writes a v1 association end's multiplicity after the type rather than before the name (end [0..1] driver : Driver). The chapter shows the warning as it is; fixing the mapping is a separate change.

How it was verified

• python3 scripts/check-doc-links.py (0 broken), python3 scripts/check-doc-ids.py, python -m mkdocs build --strict, python3 scripts/changelog.py check — all pass.
• make proto-lint, make proto-buf, make proto-ts, make proto-rust; the regenerated Go, Java, TypeScript and Rust stubs and the Rust descriptor are committed (comment-only changes).
• go build ./..., go vet ./..., gofmt -l . (empty); go test ./client/opensysml ./internal/grpc/... pass, including the new TestConvertFileMigratesSysMLv1 (a .xmi migrates through the Go client, answers FormatXMI, is Experimental with the migration notice, and FormatXMI as an output is CodeInvalidArgument).
• Every command and output quoted in chapter 11 was run against bin/sysml on internal/core/migrate/testdata/xmi/vehicle.xmi; the ISQ::MassValue / [SI::kg] form the units bullet recommends was checked to evaluate.

Checklist

• make test and make lint pass locally (targeted packages and the docs/proto gates; the full make test was not run for a docs change)
• Tests added or updated for the change
• Documentation extended where it already covers the surface (see CONTRIBUTING.md)
• Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
• baselines regenerated and make docs-counts run if a gate count moved (the test-suite figure moved by one for the new Go client test)
• No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.