Official release notes
Where they appear
On the first eligible Mission Control launch after an update, official notes appear below the rabbit. If you skipped releases, available approved notes appear oldest first, with a version heading for each release.
Start magi-code in an interactive terminal without an initial prompt to reach the welcome screen. Reading progress is global for the current application home (MC_HOME, otherwise ~/.magi-code), not per repository or session. A fresh installation shows only current-version notes. When migrating existing settings, the highest recorded seen version no newer than the running version supplies the baseline.
Mission Control initializes the unread baseline separately from acknowledgement, including ordinary resumed conversations and launches with an initial prompt. Those launches do not consume notes. The unread range survives skipped releases, partial reading, dismissal, and relaunch. Downgrades do not move the unread baseline backwards or display future notes. Normal launches remain eligible even though the CLI creates a session; explicit resume and continuation are excluded, including empty sessions.
After /update, the relaunch preserves the exact session and uses an internal --update-restart marker. Unseen bundled notes temporarily replace the conversation view, without changing the restored history or provider input. Press Esc to reveal the conversation, or submit a prompt to dismiss the notes and continue. Dismissing partially read notes leaves the version unseen. Already-seen or missing notes leave the restored conversation visible. An initial --prompt still skips notes, even with the restart marker.
Notes fill the available width and height below the rabbit, with a bordered container and scrollbar. The hotkey and command help and “Type a prompt below to begin” invitation are hidden while notes are shown. Scroll with the mouse wheel over the notes or Alt+Up / Alt+Down. Page Up and Page Down do not scroll release notes. Scrolling leaves the prompt unchanged and does not intercept controls while a modal or overlay is open. The container needs at least 12 text columns and one text row; smaller terminals must be enlarged.
The entire selected range is acknowledged only after all its notes have reached a successful, uncovered terminal draw. Resizing the notes viewport restarts scrolling from the beginning. Opening a side conversation does not count covered notes as viewed. The local settings write finishes during shutdown after terminal restoration; partial reading leaves the whole range unread for the next eligible launch.
The Diff page hides welcome notes. Page Up and Page Down keep their Diff behavior there, and Diff draws do not mark notes as viewed.
Source and version selection
Official notes are bundled from versioned docs/features/release-notes/<VERSION>.md files, without a v prefix, through the Cargo package version. Versions are sorted numerically using semantic version order, not filename order. Each file is limited to 16 KiB and the complete bundle to 1 MiB; exceeding either limit fails the build rather than silently dropping notes. Future versions and the template are excluded. The same approved current-version file supplies the GitHub release body. The application does not fetch notes from GitHub or generate them from the changelog.
Missing approved files are omitted. Missing current-version notes do not block available intermediate notes when an older baseline exists; a fresh installation without current notes shows none. This is acceptable for development builds. There is no fallback to the template or invented notes. Do not bump the version just to populate the welcome screen.
Writing and approval
Use TEMPLATE.md to draft a proposal. Keep proposals outside the versioned bundle path until the user explicitly agrees on the complete text for the exact version. A request to release, a generated summary, changelog review, or silence does not approve notes. Keep the proposal and user agreement in the conversation; no separate release record is required. Approval metadata does not belong in the displayed body.
Write for someone who has just installed the release:
- New features: explain what changed and exactly how to access and use it. Include the command or slash command, setting name and value, or ordered workflow steps. State prerequisites, availability limits, and the expected result where needed. For automatic behavior, explain when it happens and whether setup is needed.
- Fixes: briefly state the user-visible problem corrected.
- Other changes: briefly state changed behavior and any action the user must take.
Use only verified shipped behavior. Keep directions self-contained; links can add detail but must not replace essential steps. Remove placeholders and empty sections. Avoid internal implementation inventories and unsupported claims.
Release requirements
Follow the authoritative release procedure for commands and authorization. Before release gates or packaging, obtain agreement and save the approved text at the exact-version path. The release gate requires matching, nonempty approved notes; whitespace, a template, or a proposal does not qualify.
Inspect the package archive to confirm it contains that same file with identical contents. Reuse it for GitHub with --notes-file; never silently substitute generated notes. Once published, the notes are immutable. Restore a mismatched GitHub body from the bundled file; put corrections to the official text in a later release.