feat(migrate): harvest migration-learnings from #10

[Hermsi1337]

What & why

Harvests the verified findings from migration-learnings issue #10 into the mittwald-migrate skill. Every claimed trap was checked against the live mw CLI (1.18.0) and the mittwald developer docs before being included; unverified or already-covered claims were dropped or redirected (see "Triage" below).

Changes

Headline — mirror the source engine by default (database-engines.md)
An autonomous migration should reproduce the source faithfully. New principle: a MariaDB source → mariadb container (matching major), never managed MySQL unless the operator explicitly opts into the engine swap. MariaDB ≠ MySQL (auth plugins, collations, system tables, JSON, sequences, virtual columns can break only in prod). Applied consistently at the decision and action sites:

• discover-source.md §7b (DB-engines self-check) + inventory example gets a MariaDB row
• migrate-mysql.md §0 recap
• provision-target.md §7 (Managed MySQL guard)

App ↔ container DB networking (database-engines.md, pitfalls.md #16)
Documents that apps and container stacks share the project network — a managed/runtime app can reach a container DB by service name (DB_HOST=<service-name>). Source: mittwald containers docs. This makes "managed/runtime app + container MariaDB" a first-class shape and directly supports the mirror-source default above.

Deployer/Capistrano source layouts (discover-source.md)
Recognize release-rotation layouts (current/ -> releases/<ts>/, shared/); migrate the active state only, dereferencing symlinks with tar -h, instead of copying the whole releases/ history or shipping broken links.

SSH ControlMaster trap (ssh-modes.md)
Local SSH connection-sharing (ControlMaster auto) makes mStudio connections fail with a misleading could not connect to project. Fix: -o ControlMaster=no -o ControlPath=none. (Independently hit by two people.)

CLI doc fixes (mittwald-surfaces.md)

• mw project get takes the project as a positional arg — the documented -p form is wrong (verified against mw project get --help).
• mw project backup* / mw project backupschedule* are deprecated → mw backup* / mw backup schedule* (the CLI prints the deprecation).
• Added the ingress path-update endpoint PATCH /v2/ingresses/{ingressId}/paths (resource-scoped, API-only — no CLI command yet).

Triage of #10 (for reviewers)

Finding	Disposition
Mirror MariaDB → container (not managed MySQL)	✅ harvested (headline)
App ↔ container networking	✅ harvested
Deployer/Capistrano layout	✅ harvested
SSH ControlMaster	✅ harvested
mw project get -p, mw project backup*	✅ fixed
PHP runtime version not settable on mw app create	→ mittwald/cli#1951 (CLI gap, not a skill workaround)
Ingress path update missing in CLI	→ mittwald/cli#1952 (+ API endpoint documented here)
PHP app auto-provisions managed MySQL	❌ dropped — API/CLI create no DB

Testing

Repo CI gates, locally:

• markdownlint-cli2 "**/*.md" → 0 errors
• lychee --offline (Docker, as CI) → 0 errors

Closes #10.

🤖 Generated with Claude Code

[gandie]

lgtm, nice learnings!

One thought for meditation: Documenting sensible defaults and explaining mstudio behavior via pitfalls is a very good idea, but i am wondering how it will scale in the future. The error space of agent work is infinite and we can't document infinity ( yet ). Besides such regular learning harvests, maybe we need another ritual for consolidation to keep skills and playbooks tight? Just a thought to chew on i wanted to throw into the ring.