Changelog — user-facing "What's new"

Every template app keeps a CHANGELOG.md of user-facing changes that renders in-app via the command menu (Cmd+K → "What's new") and on the settings page. The flow mirrors changesets so it survives many agents working in parallel: each change drops a small pending entry file, the in-app surface reads pending files plus CHANGELOG.md, and a later release can roll those pending files into dated CHANGELOG.md sections.

When to add an entry

Add an entry whenever you ship something a user of that app would notice:

• a new capability or surface,
• a visible improvement (speed, layout, copy, defaults),
• a bug fix that affects behavior they'd see.

Do not add entries for refactors, internal tooling, tests, dependency bumps, or anything invisible to the end user. The changelog is product notes, not a commit log — write it the way you'd describe the change to a customer.

How to add an entry

From the app directory (the template you changed):

agent-native changelog add "Recordings can be trimmed before sharing" --type added
agent-native changelog add "Faster transcript search" --type improved
agent-native changelog add "Fixed a crash when opening an empty folder" --type fixed

--type is one of added, improved, fixed, changed, removed, security (aliases like feature, bugfix, enhancement are accepted). This writes changelog/<date>-<slug>.md — one file per change, so parallel work never conflicts. You can also hand-write that file; the frontmatter is just:

---
type: added
date: 2026-06-23
---
Recordings can be trimmed before sharing.

Writing good entries

• One user-facing sentence, present tense, no internal jargon or file names.
• Lead with the benefit ("Recordings can be trimmed…"), not the mechanism.
• Markdown is allowed (bold, links) but keep it short — it renders as a bullet.

Releasing

release stamps every pending entry into CHANGELOG.md under a dated ## <date> section (grouped by type) and deletes the pending files:

agent-native changelog release            # uses today's date
agent-native changelog list               # preview pending + released

Releasing is usually done at deploy/merge time to keep the source tree tidy. The in-app surface imports CHANGELOG.md?raw, and the core Vite plugin merges adjacent changelog/*.md pending entries into that raw markdown at dev/build time, so product notes become visible without waiting for a manual rollup.

Wiring the in-app surface (once per template)

Templates already get the rendering for free from @agent-native/core. To expose it in an app:

1. Command menu — pass the app's own changelog to CommandMenu:

   import changelog from "../CHANGELOG.md?raw";
   // ...
   <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen} changelog={changelog}>
     {/* existing groups */}
   </CommandMenu>

   This adds a "What's new" entry with an unseen-release dot and an in-app dialog — no other wiring needed.

2. Settings (optional) — drop the card on the settings page:

   import { ChangelogSettingsCard } from "@agent-native/core/client/changelog";
   import changelog from "../CHANGELOG.md?raw";
   // ...
   <ChangelogSettingsCard markdown={changelog} />

CHANGELOG.md?raw is inlined by Vite at build time, so this works on every host with no server route or runtime file access.

Checklist

• Shipped a user-visible change? Run agent-native changelog add "…".
• New template UI? Pass changelog to its CommandMenu and seed a CHANGELOG.md.
• Releasing/deploying? Optional: agent-native changelog release rolls pending → dated sections and deletes the pending files.