(changelog): keep a user-facing changelog, and show What's new after an update

[jbr-sekoia]

Closes #363

What changes

CHANGELOG.md at the root: ## Unreleased, then ## vX.Y.Z — YYYY-MM-DD sections, newest first, each with ### New / ### Changed / ### Fixed. An entry says in one or two sentences what the user sees, with its ref at the end. A --- line closes the last section, and the pointer to GitHub Releases for older versions sits under it.

• Backfilled: v0.0.80, v0.0.81, v0.0.82, v0.0.83, v0.0.84, rewritten from the release notes and the merged PRs. Tests, CI and docs-only work left out: (trace): subagent activity is traced from its single write path, with its source #292, chore(test): cap stage-1 test concurrency instead of taking every core #299, (osc): build the PTY debug lines only when debug logging is on #312, (docs): cover the reloader trap, the packaged build, and where the release flow lives #314, (docs): say that a chain's timeout is one budget, not one per step #315, (test): keep the setting-defaults guard off the generated codemirror bundle #324, (test): check the ~/.claude allowance against a path no host can symlink away #333, (test): drain a capped git instead of killing it, so its repository can be removed on Windows #336. (main): release the viewer-panel file watchers when the window closes #308 is left out as well, because users see nothing of it. v0.0.82's release notes repeated two fixes that shipped in v0.0.81 ((sidebar): size the sidebar to its container, not the window #306, (main): release the viewer-panel file watchers when the window closes #308); they are listed under v0.0.81 only.
• ## Unreleased: (header): give the session header's controls one order and one look #348, (changes): show an untracked file's line counts without opening it #350, (changes): bring the Changes panel and its editor onto the app's look and feel #351, (terminal): define the plain terminal's claude shim without typing it into the shell #352, (sidebar): keep the subagents of an archived parent out of the orphan group #354, and this PR. (docs): rewrite the README and docs/ against the code, one page per area #357 is docs-only, so it has no entry.

The rule, where it is read: docs/changelog.md covers the file, how to write an entry, the CI check and the dialog. It is linked from docs/releasing.md, docs/README.md and CHANGELOG.md itself. .ai/shared-guidelines.md carries one new "When you finish work" step and one orientation row.

Release procedure (docs/releasing.md, .claude/commands/release.md): the bump PR renames ## Unreleased to the version and its date, and opens a new empty one. The publish job's "Fill in release notes" step now writes the body from that section (scripts/changelog-section.js <tag>), followed by the same Full changelog compare link as before. It still fails rather than publish an empty body, now when the section is missing or empty. The commit-subject list is gone. Step 9 of the command no longer prepends a summary: the notes and the app's dialog must say the same thing, so wording is changed in CHANGELOG.md. test/changelog.test.js fails when package.json's version has no section, so a bump without one does not pass CI.

CI check: a changelog job in test.yml, on pull requests only.

• It fails when the PR's diff (HEAD^1..HEAD of the merge commit) touches app code but not CHANGELOG.md.
• App code is what electron-builder ships: the root *.js files except eslint.config.js, public/, workers/ and scripts/claude-sandbox.sh.
• The no-changelog label (created) waives it. The labels are read through the API at run time, so after adding the label a re-run of the failed job passes. labeled events do not re-run the whole test matrix.
• The logic is scripts/check-changelog.js.

What's new dialog:

• Main side (changelog.js, main.js): whats-new-startup compares app.getVersion() with global.lastSeenVersion, whose default null is in SETTING_DEFAULTS.
  • No valid stored version (a fresh install): the running version is recorded and no dialog opens.
  • Same or later version stored: no dialog.
  • Earlier version stored: the dialog opens with every section in (lastSeen, current], newest first, skipped versions included. whats-new-dismissed records the running version when it closes.
  • Missing or unparsable file: [whats-new] warning in the main log, no dialog, nothing recorded.
  • Versions compare numerically: 0.0.100 > 0.0.99.
• CHANGELOG.md is added to build.files and read from __dirname, which is app.asar in a packaged build.
• Help → What's new is a new last menu (window-frame.js). It sends show-whats-new with the running version's section.
• Renderer (public/whats-new.js):
  • A parser for the subset the file uses: ###, - bullets, paragraphs, bold, inline code, links.
  • Every piece of text goes through escapeHtml. Only an http(s) URL with no quote or angle bracket becomes a link, and a click on it goes to openExternal.
  • Built like the Add Project dialog, with the sidebar's thin scrollbar. It closes on ×, on Escape (caught in the capture phase so a terminal behind it does not get it) and on a backdrop click.
  • .whats-new-overlay is in the window strip's no-drag list.

Evidence

Tests written first, each seen red on its assertions against a stub, then green:

File	Tests
test/changelog.test.js	23
test/whats-new.test.js	23
test/check-changelog.test.js	10
test/changelog-section.test.js	5
test/whats-new-wiring.test.js	6
test/window-frame.test.js	+1, and one regex updated

Mutations: each guard was mutated alone and the suite rerun. All 66 are caught.

Area	Caught
Parser and decisions	20/20
CI check	13/13
Renderer (escaping, link scheme, quote breakout, stacking, Escape propagation, focus, CSS scroll and no-drag)	22/22
Menu and main wiring, packaging	8/8

The first pass had four survivors:

• The non-string guard in parseChangelog: split throws anyway, so the guard is removed.
• Three tests that could not see their bug (a quote-breakout input the regex never matched, unescaped section headings, a blank line between paragraphs). Those tests were strengthened.

Live (Playwright, throwaway HOME, one data directory across three launches of this branch):

1. Fresh start: no dialog, lastSeenVersion = 0.0.84.
2. lastSeenVersion seeded to 0.0.81, then relaunched:
   • The dialog lists v0.0.84, v0.0.83, v0.0.82.
   • The body scrolls (overflow-y: auto, scrollHeight 665 > 663) and the dialog stays under 80 vh.
   • The close button has focus, and nothing is recorded before dismissal.
   • With prefers-color-scheme: light emulated, the dialog keeps its colours.
   • Escape closes it and records 0.0.84.
   • Help → What's new, clicked through the real application menu, shows v0.0.84 alone; × closes it.
3. Relaunch: no dialog.

15/15 checks passed.

Gate: eslint . has 0 errors, and its 343 warnings are all pre-existing. The full suite runs through the pre-commit hook.