release-notes

name	release-notes
description	Write per-version release notes for nocturnal in the style established by `release-notes/0.9.1.md`. Use when cutting a new release, drafting notes for a tagged commit range, or revising existing notes to match the house format.

Release notes style

Per-version notes live at release-notes/{version}.md in the repo root. They are served at {RELEASE_URL}/release-notes/{version}.md so the agent can fetch them on demand when the user asks "what's new?".

Format

Top-line header with the version and the release date:

# 0.9.1 — 2026-07-11

Section headings, in this order if they apply. Skip any section that has nothing to put under it rather than emitting it empty.

• Breaking Changes — user-visible behavior changes that may require action. Reserved for removals, keybinding changes, removed config keys.
• Features — new user-facing capabilities.
• Changes — default-value changes and other behavior shifts that are neither pure bugfixes nor new features.
• Improvements — UX polish: faster, smoother, prettier, less noise.
• Bug Fixes — things that were broken and now work.
• Performance — measurable latency / throughput wins. Skip if a fix is in Bug Fixes even if it was a perf-driven rewrite.
• Notes — security tightenings, deprecations, migration steps, default-value caveats. Always include when defaults change.

Bullets are sentences. No implementation details, no commit hashes, no file paths, no internal mechanism descriptions. The audience is the user, not a maintainer.

Bold the user-visible noun on the first phrase of the bullet so a scanner sees the topic, not the sentence. Example shapes:

• First-run setup wizard in the TUI and desktop guides you through...
• The model catalog now propagates from the server to all connected clients without a manual refresh.
• OAuth providers (openai-codex, xai-supergrok) no longer appear in the model picker until a token is configured.

Inline code for config keys, file names, command names, key chords, CLI flags. Backticks only, never bold.

Keep Notes paragraphs short. The Notes section is the only place where a default-value warning or migration instruction is acceptable — these are the bullets the user actually has to read.

Process when cutting a release

1. Find the commit range: git log v<prev>..HEAD --oneline (or the previous tag, whichever is the most recent shipped version).
2. Read each commit message body for context, but write for the user. Drop anything that reads as engineering narration ("extracted to server/model_catalog.rs", "serde(flatten) keeps wire format unchanged") unless it directly describes a user-visible behavior change.
3. Categorize. If a fix touches both provider behavior and UI, pick the section the user will look for it under.
4. Draft, then re-read with the question: would a user who never reads the codebase understand every bullet?
5. Drop the file into release-notes/{version}.md and let scripts/pkg-release.sh pick it up on the next release build.