docs(migrate): harvest CLI, source-SSH & non-interactive learnings

[Hermsi1337]

Harvests operator-reported mittwald-migrate learnings into the skill. Every claim was verified against mw 1.18.0 before writing (per DEVELOPING.md §"Harvesting migration-learnings issues" step 3) — including a live reproduction attempt in a throwaway project for the one bug-shaped claim.

New pitfalls (verified)

• #26 — mw app exec COMMAND is a single positional argument. Pipes/redirects/chaining need bash -c wrapping. Confirmed against mw app exec --help. Wired into migrate-files.md as an alternative to hand-assembling the SSH address.
• #27 — Output flags aren't uniform. -o json on read/list commands, -q on mutations; -o on mw database mysql dump is the output file, not a format. Route by command kind. Wired into mittwald-surfaces.md.

Runbook fix

• mittwald-surfaces.md dump/import Rosetta rows showed shell redirection (> dump.sql / < dump.sql); the CLI actually takes -o/-i file flags (- for std streams), --gzip, and -p = --mysql-password (not project-id). Corrected.

Claim that did NOT survive verification

An operator reported mw database mysql import --temporary-user 404ing while fetching the temp user before import. Reproduced live on mw 1.18.0 in a throwaway managed MySQL DB — it completed cleanly (temp user created + import + temp user removed; data verified via round-trip dump). Documented --temporary-user as working, with a note that the 404 was version-specific — deliberately not baked in as a standing bug (avoids the documentation-rot trap of Pitfall #21).

Filed upstream instead of harvested

The operator also hit an undocumented admin-password complexity policy on mw app install … --admin-pass. Rather than bake a workaround into the skill, this was filed as a CLI issue: mittwald/cli#1968 (document the policy / return a clearer error / optionally add a password-generator flag).

Notes

• No migration-learnings issue backs this (learning came in directly) — nothing to close.
• Markdown lint clean, validate-skills.sh passes.

🤖 Generated with Claude Code

---

Follow-up commits — source-SSH guidance & -i overload

Two small additions beyond the CLI-flag learnings, surfaced while driving the skill programmatically (the huebscher POC) and verified against mw 1.19.0:

• Pitfall #28 — an interactive SSH prompt on the SOURCE stalls an unattended run. Written as guidance, not a recipe: how the source authenticates is the operator's to state; the only rule is to make that access non-interactive for unattended runs (examples: sshpass -e for a password, StrictHostKeyChecking=accept-new on first connect). New "Source-side SSH access" section in ssh-modes.md (the reference was target-only), referenced from the source-pull steps of migrate-files.md / migrate-mysql.md.
• mw SSH env vars — MITTWALD_SSH_IDENTITY_FILE / MITTWALD_SSH_USER (and --ssh-identity-file / --ssh-user) select the key/user for the SSH-tunnelling commands; noted in mittwald-surfaces.md.
• Pitfall #27 — -i overload added (--installation-id on mw app exec vs --input on mw database mysql import/dump).
• SKILL.md pitfalls count 25 → 28.

A first pass also added a non-interactive.md "headless driving contract"; it was removed on review — it prescribed how a caller configures their own harness, which is the skill user's domain, not the skill's. The skill sets a frame; the operator supplies the specifics.

Deliberately left out (verification discipline): the native domain-migration API and a classic-mittwald-source discovery path — both need live two-token / classic-platform verification, so no unverified API claims went in.