# D20. Format versions migrate; renaming is a command (6 Oct 2026)

Testers' projects must never break when the core evolves. The format version is in `course.json`; every format change ships with a migration (a pure step on the raw files, in `@elabora/core`) and a fixture course in the older version. Elabora reads an older course migrated in memory (validation and builds work at once) and writes the migration only when asked (`elabora migrate`), when an edit goes through Elabora, when the app opens the course or when the library imports it: always as one `system` change after a backup version, so it can be undone, and never mixed into AI work. A migration edits values in the text of each file, keeping the author's formatting (agents and people write compact JSON, one block per line), so a migrated course differs by its migrated values only. A newer format is refused rather than half-read. Ids stay permanent; renaming one is a command that rewrites every reference and carries the learner-state key, rather than a free edit that would orphan progress.
*Revisit if:* a migration needs to change binary files or to ask the author (then an interactive migration in the app, with the same journal entry).