Migration scripts live in two layers:

Schema (src/migrations/): code-level state.json transforms, auto-chained by registry
Workflow (~/.maestro/workflows/updates/): version-specific upgrade guides with environment setup

Schema migrations handle the mechanical version bump. Workflow docs handle the smart part — what the user needs to know, configure, or verify for that version. The router runs schema first, then loads the matching workflow doc.

<required_reading> @~/.maestro/workflows/updates/README.md </required_reading>

maestro-update