docs(migration): add Sprint 2 Phase C — Why migrate + Migration steps + Known incompatibilities

[suzuke]

Summary

Phase C completes the migration guide. The 7-section skeleton from Phase A now has full content in every section:

Section	PR	State
§1 Why migrate?	#66 (this PR)	this PR
§2 CLI flag mapping	#63 (Phase A)	merged
§3 fleet.yaml schema diff	#63 (Phase A)	merged
§3.3 outbound_capabilities	#65 (Phase A follow-up)	merged
§4 Backend invocation diff	#64 (Phase B)	merged
§5 MCP tool API diff	#64 (Phase B)	merged
§6 Migration steps	this PR	this PR
§7 Known incompatibilities and deferred parity	this PR	this PR

After merge, the migration guide is a complete, ship-ready document covering the full operator migration journey from @suzuke/agend to agend-terminal.

What this PR adds

§1 Why migrate?

Operator-direct, no marketing pitch. Covers:

• What you gain: native PTY mux, cross-platform (macOS/Linux/Windows), type safety where it matters (group_id/topic_id/outbound_capabilities), async daemon with no per-instance Node process, single source-of-truth BackendPreset table, built-in TUI (agend-terminal app).
• Why @suzuke/agend is being deprecated: JS Number.MAX_SAFE_INTEGER precision (Discord guild IDs especially), tmux multiplexer locking out Windows, process management overhead via wrapper scripts, implicit channel ACLs.
• Should you migrate now?: triage between immediate (heavy fleet, Windows operators, TUI dependency, cost-guard usage) vs defer (single Telegram-bound instance, stable config, no precision-sensitive usage).
• Pre-alpha caveat: pin version, read release notes per upgrade, keep pre-migration backup ≥ 30 days. Cross-links to §6 rollback procedure.

§6 Migration steps

7-stage actionable plan:

1. Pre-migration audit (TS state inventory via agend ls / topic list / access list / schedule list plus fleet.yaml read-through plus AGENTS.md/GEMINI.md gitignore audit).
2. Snapshot data (concrete cp / tar / version-string commands).
3. Choose mode (greenfield recommended unless meaningful historic state; in-place for fleets with non-trivial decision history or template usage).
4. Workflow change: git worktree per branch — encoded in Rust resume strategy (cwd-keyed sessions) and global CLAUDE.md operator policy. Includes the canonical git worktree add ../my-repo.worktrees/<branch> <branch> pattern.
5. Cross-link integrate — applies §2/§3/§4/§5 mappings to fleet.yaml, prompts, and runbooks. Each section linked back via the stable anchor.
6. Post-migration smoke test checklist — 8 items covering daemon start, bot reply, allowlist gate, cross-instance dispatch, set_waiting_on round-trip, cost-guard pre-check, CI watch loop, config reload (with the RUST_LOG=debug reminder for the user_allowlist drop log).
7. Rollback path — stop, restore $AGEND_HOME backup, re-install pinned version, file agend-terminal issue with daemon.log + redacted fleet.yaml + version string. Keep backup ≥ 30 days post-cutover.

§7 Known incompatibilities and deferred parity

Explicit risk register, organised into five subsections:

• TS-only commands removed (recap from §2: 14 commands grouped by area).
• TS-only fleet.yaml fields removed (recap from §3: 14 InstanceConfig fields + 4 top-level keys).
• TS-only access semantics (pairing mode has no Rust analogue; explicit enumeration into channel.user_allowlist required).
• Pending parity (Rust roadmap): outbound_capabilities Sprint 23 hard parse error promotion, PTY transport / signal capability matrix pending markers, AGEND_TOOL_SET profile mechanism, cross-channel architecture (Telegram → Discord/Slack via auth.rs::gate_outbound_for_agent), list_instances tags filter parity.
• Functional limitations during transition: cost_guard not yet per-instance on Rust, Discord un-quote requirement, pairing-mode enumeration.
• Operator caveats: user_allowlist DEBUG-not-WARN log level, pre-alpha schema instability, no archive format, tmux not used on Rust.

Stable anchors preserved

All cross-links use the anchors established in Phase A: {#why-migrate}, {#cli-flag-mapping}, {#fleet-yaml-schema-diff}, {#backend-invocation-diff}, {#mcp-tool-api-diff}, {#migration-steps}, {#known-incompatibilities}.

Stats

• 2 files changed, 386 insertions(+), 6 deletions(-) (3 placeholder lines × 2 sections × 2 files = 6 deletions for the Phase C placeholders)
• 196 EN + 196 zh-TW (1:1 mirror)
• Pure docs, no code

Reviewer dispatch plan

• ts-reviewer — TS-side full_review: writing quality + cross-link integrity + Phase A/B/follow-up summary fidelity + zh-TW parity + readability for a migrating operator.
• dev-reviewer-2 (cross-team) — scope_conformance: §1 Rust value prop accuracy (native PTY mux, cross-platform, type safety claims) + §7 known incompatibilities Rust-side fidelity (outbound_capabilities Sprint 23 timeline, capability matrix pending markers, AGEND_TOOL_SET profile state, cross-channel architecture, list_instances tags parity).

🤖 Generated with Claude Code