Update Changelog

Gate

The changelog is written once per release, by the maintainer, as one story. changelog/ stays untouched by every other task; a fix or a merged PR lands without a changelog line. Proceed only when the current message asks to update the changelog.

Write changelog/unreleased.md and nothing else. Generation is not your job: oc-dev create-release turns the file into changelog/<version>.md with the date and renders packages/vscode/CHANGELOG.md and changelog/index.json from it. CHANGELOG.md at the root is a legacy copy for older installs. Never run the generator or touch any of these files. bun run changelog:check only validates the shape of what you wrote and writes nothing; changelog/README.md describes the format.

unreleased.md opens with a title: front matter line (see The title) and holds two sections:

• ## App — Web, Desktop, Mobile/PWA, shared UI.
• ## VS Code — the extension only, written separately (see below).

The shape of a release

Every release section is grouped. Under the version header come, in this order and only when non-empty:

### New
- **VS Code: comments on code.** Select lines, click the `+` in the gutter ... (thanks to @felipegenef)
- Project actions in worktrees: a session in a worktree can use the parent project's saved actions (thanks to @mattv8).

### Improvements
- Chat: Markdown tables are readable again, columns take the width their content needs (thanks to @ChangeHow).

### Fixes
- Chat: huge patches in tool cards open without freezing the page (thanks to @karimodm).

### SDK
- Actions: use `mode: "background"` to handle a message action without opening a panel.

### Misc
- Bundled OpenCode updated to 1.19.

Where a change goes:

• New — something the user could not do before: a feature, a surface, a language.
• Improvements — something they could do works better or reads clearer now.
• Fixes — something was broken and showed a wrong result; the bullet names the symptom.
• SDK — capabilities and API changes for extension authors, under ## App, after Fixes and before Misc. Name the API and what an author can build with it. User-visible extension features and fixes stay in the regular groups.
• Misc — bundled tool versions, packaging, platform support, retirements. Rarely more than a few lines.

The maintainer's calls on the borderline cases:

• A rework of something that already existed (multi-run moved into the composer) is an Improvement, however large.
• Something that made the app hang or stutter (tooltips or menus jolting the whole window) is a Fix, named by that symptom.
• Minor polish (a dialog laid out in two columns, quieter metadata text) gets no bullet at all.

The generator emits the groups in this order whatever order the source lists them and drops empty ones; version, date, and headers are its concern, not yours.

The title

Every release carries a one-line title: in its front matter. The website lists it beside the version and uses it as the heading of the release page, so it is the one line most people read. It answers "what would a user remember this release for":

• Two to six words naming the change most users will notice. For a fix-only patch, name what works again: Terminal works again on Windows, Faster session switching.
• Plain words, sentence case; product names keep their casing. No area prefix with a colon, no trailing period, no version number, no credit.
• Never a category alone (Fixes, Stability, Improvements, Polish) and never a bare area (Git, Chat): the title has to teach the reader something.
• Two headliners at most, joined with and, and only when the release really has two.

oc-dev create-release refuses a release without a title. In unreleased.md it sits at the top:

---
title: Comments on code in VS Code
---

## App

The bullet

The reader is a user of the app. They never opened the code, they will not open the PR, and they give a bullet about five seconds. Write for that reader:

• One sentence, two at most. A bold highlight may take three. Under about 200 characters for a regular bullet.
• Name what they see or do. The screen, the button, the gesture, the outcome. When a fix removed a symptom, name the symptom in plain words ("froze the page", "sent the comment by accident", "stopped at the first page").
• Plain words only. Anything a user would have to look up is out: store, cache, route, payload, reconcile, authoritative, lifecycle, runtime, listing, revision, PTY, bridge. Internal component names are out unless the user sees them on screen.
• State the new behaviour directly. Say what happens now. Framing it against the old way ("X, not Y", "instead of Y", "rather than Y") is the tell of machine-written notes; drop the second half and let the sentence stand.
• Area prefix, then the fact. Chat:, Settings/Providers:, Git:, Mobile:, Server:, CLI:, VS Code: in the main file. A highlight bolds its prefix: - **Project actions:** ....
• Details stay in the PR. No commit hashes, file paths, numbers that do not change what the user does, or mechanism. One concrete number is fine when it is the whole point ("more than 200 sessions").

Worked example, same change:

Weak: a saved action counts as running exactly while its command runs. When the command exits, the stop icon goes away even if the terminal tab stays open, and a second client can start the action again. Every client shows the same run, and the sidebar marks a directory that has one. Sessions in a linked worktree can use the parent project's actions; they run in the worktree by default.

Good: the running state of a saved action is reliable now. It shows as running only while the command is really running, every device sees the same state, and the sidebar shows which project has something running. Worktrees can use the parent project's actions.

The weak version is accurate and lost the reader at the first comma. The good version keeps the three things a user notices and drops the mechanics that explain them.

SDK bullets address extension authors: use exact API names in backticks and state how to use the new capability. Keep the same short bullet format; implementation internals still belong in the PR.

Load .agents/skills/communication-style/SKILL.md and run its pattern scan over the finished sections; its rules on em dashes, hedging, and puffery apply here unchanged.