docs(migration): add Sprint 2 Phase A — CLI flag mapping + fleet.yaml schema diff

[suzuke]

Summary

Establishes the canonical migration reference at docs/migration-to-agend-terminal.md (+ zh-TW pair) for moving an existing @suzuke/agend (TS) install to agend-terminal (Rust). Built incrementally per Sprint 2 plan — Phase A lands the 7-section skeleton plus full content for Sections 2 (CLI flag mapping) and 3 (fleet.yaml schema diff), the highest-friction surfaces for operators porting an existing config.

Sections 1, 4, 5, 6, 7 carry (Phase B) / (Phase C) placeholders so subsequent phases stack without merge conflict. Stable anchors placed ({#cli-flag-mapping}, {#fleet-yaml-schema-diff}, etc.) so Phase C link-backs land on stable IDs.

This PR is the ts-team Sprint 2 Phase A response to dev-lead's cross-team docs scope dependency for agend-terminal Sprint 24.

Cross-team source of truth

dev-impl-2 (Rust hot context) provided the canonical Rust-side facts via single-hop query:

• Rust CLI tree: src/main.rs:165-337 (clap definitions; single flat enum)
• Rust fleet.yaml schema: src/fleet.rs:7-183 (FleetConfig + InstanceConfig + ChannelConfig; serde defaults; snake_case)
• user_allowlist three-state semantics + outbound drop log: src/channel/mod.rs:240-260 — drop line at L254
• group_id i64 round-trip tests: src/fleet.rs:725-826

High-friction items (per dev-lead)

#1 — user_allowlist is fail-closed by default (PR #216)

• Field is top-level channel.user_allowlist, NOT nested under access (Rust has no access sub-key on channel).
• Three-state semantics documented:
  • key absent → legacy open mode + deprecation warning
  • [] → lockdown (reject all)
  • [ids] → allowlist
• Exact daemon.log line cited: outbound notify dropped — channel not authorised (fail-closed; configure user_allowlist to opt in) (src/channel/mod.rs:254).
• Migration action with concrete YAML.
• Debugging checklist for the silent-bot-on-Rust failure mode.

#2 — group_id is strict i64, bare int only

Reverses the TS migration guidance. On Rust, the field is strictly typed i64 and serde rejects quoted-string form at startup with expected i64. Operators who quoted group_id per the @suzuke/agend workaround must un-quote when porting. Same caveat noted for topic_id (also strict Option<i32>).

What's leaner on Rust (covered in the guide, summarised here)

CLI commands removed: init, restart, reload, install/uninstall, web, export/import, export-chat, logs, attach (kept), fleet logs/history/activity/cleanup/restart, backend trust, all of topic/access/schedule. Each marked Removed with the operator migration action (read log files, edit fleet.yaml, use MCP tools, OS-native services).

Fleet.yaml fields removed: tags, general_topic, restart_policy, context_guardian, log_level, tool_set, lightweight, systemPrompt, skipPermissions, model_failover, cost_guard, workflow, startup_timeout_ms, agent_mode, plus top-level project_roots, profiles, health_port, stt. Each row in the diff table documents the Rust alternative (env var, backend preset, per-backend instruction file, or simply N/A).

Two TS fields kept via serde alias on Rust: description → role, worktree_source → git_branch.

Reviewer dispatch plan

This PR is dispatched to two reviewers in parallel per ts-lead's directive:

1. ts-reviewer — TS-side fact accuracy (every TS field/command cited from src/types.ts / src/cli.ts), writing quality, skeleton structure (anchors, Phase markers, banner alignment with PR docs: add deprecation banner to user-facing docs (Sprint 1 Track 1) #61). Standard TS-team Reviewer Contract v1.1.

2. dev-reviewer-2 (cross-team) — Rust API correctness only. Boundary: zero TS context, audit only the Rust-side claims and the source pointers (src/main.rs, src/fleet.rs, src/channel/mod.rs). They confirm whether the Rust facts cited match the actual code at those paths.

Verdicts must both reach ts-lead before merge gate.

Stats

• 2 files changed, 486 insertions(+) — pure docs PR.
• No code, no tests, no typecheck (operator-authorized for docs).

Files

• docs/migration-to-agend-terminal.md (244 lines)
• docs/migration-to-agend-terminal.zh-TW.md (242 lines)

🤖 Generated with Claude Code