# Official release notes
## Where they appear
On the first launch of a released version that reaches the Mission Control welcome screen, official notes appear below the rabbit. They introduce new features with directions for using them, followed by brief fixes and changes.
Start `magi-code` in an interactive terminal without an initial prompt to reach the welcome screen. Notes are tracked as seen globally for the current application home (`MC_HOME`, otherwise `~/.magi-code`), not per repository or session. A version is marked seen only after its welcome notes are actually rendered. Subsequent launches do not automatically repeat that version's notes.
Ordinary resumed conversations and launches with an initial prompt do not consume the notice. 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.
A version is marked seen only after all notes have reached a successful, uncovered terminal draw. Resizing the notes viewport restarts scrolling from the beginning. Opening a side conversation does not count the covered notes as viewed. The local seen-state write finishes during shutdown after terminal restoration; partial reading leaves the version unseen.
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 `docs/features/release-notes/<VERSION>.md`, where `<VERSION>` exactly matches the Cargo package version, without a `v` prefix. The same approved file supplies the GitHub release body. The application does not fetch notes from GitHub or generate them from the changelog.
A missing approved file means no release-notes display. This is acceptable for development builds; there is no fallback to another version or to the template. Do not invent current-version notes or bump the version just to populate the welcome screen.
## Writing and approval
Use [TEMPLATE.md](release-notes/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. Record the proposal and user agreement in the release record; approval metadata does not belong in the displayed body.
Write for someone who has just installed the release:
1. **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.
2. **Fixes:** briefly state the user-visible problem corrected.
3. **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](../release.md) 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.