Goal

docs/CHANGELOG.md is a release notes document for humans, not a git log.

Target style (canonical examples: v0.22.236, v0.23.128, v0.23.129):

One user-facing bullet per component + intent cluster (often 3–8 bullets per category, not 50+).
Plain language: what changed and why it matters.
Platform prefixes when helpful: **macOS — Hotkeys (XIP0078 P4)**: or **Linux — Clipboard (XIP0079 P3)**:.
Optional one-line release summary for large ranges (e.g. "Broad reliability release aggregating v0.23.27 onward").
--- horizontal rule between version sections.
File opens with a # Changelog preamble (intro + semver legend), then newest versions.
No commit hashes in bullets (version heading links to the tag when it exists).

The helper script produces a draft. An agent must rewrite that draft into release-note prose before publishing.

update-changelog