# 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.
Resumed conversations and launches with an initial prompt do not consume the notice. If they bypass welcome, the notes remain eligible for the next launch that renders welcome. Seen state is local display state, not conversation history or provider input.
Normal launches remain eligible even though the CLI creates a session. Explicit resume and continuation of an existing session are excluded, including empty sessions.
Notes wrap within a viewport up to 72 columns wide below the rabbit. Use **Page Down** and **Page Up** (without modifiers) to read long notes; the footer shows the visible row range. These keys leave the prompt unchanged and keep their usual behavior while a modal or other overlay is open. A viewport needs at least 12 text columns and one notes row below the welcome area; smaller terminals must be enlarged.
A version is marked seen only after every page has reached a successful, uncovered terminal draw. Resizing the notes viewport restarts paging from the beginning while unread. 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.