fix(ci): build the extension's release notes from its changelog

Review caught that the migration note this PR moves into a changeset never
reaches anyone. `release-vscode-extension.yml` created its GitHub Release with
`--generate-notes` and a static body, ignoring `vscode-extension/CHANGELOG.md`
entirely — so the curated, per-PR voice that Changesets assembles was written and
then discarded. The library and standalone tracks have always fed
`extract-changelog.mjs` into `--notes-file`; the extension now does the same, and
`npm-publishing.md` stops claiming that every track already did.

Full history is fetched for it, because the script recovers each entry's
Conventional Commit type from the SHA in the changelog line to group the notes.
An empty section falls back to `--generate-notes`, as elsewhere.

The contributor guide told authors to skip changesets for VS Code-only work,
which the new flow depends on them writing. It also promised the library is never
dragged up by a standalone bump — a `fixed` group drags every member, which is
what one product number costs. Both corrected.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: FelixTJDietrich

.github/workflows/release-vscode-extension.yml

@@ -216,6 +216,9 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ github.sha }}
+          # Full history so extract-changelog.mjs can resolve each changelog
+          # entry's commit type (feat/fix/...) to group the release notes.
+          fetch-depth: 0
 
       - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
         with:
@@ -242,18 +245,34 @@ jobs:
             exit 1
           fi
           VSIX="${files[0]}"
-          gh release create "$TAG" \
-            --title "$TAG" \
-            --target "$GITHUB_SHA" \
-            --verify-tag \
-            --latest=false \
-            --generate-notes \
-            --notes "VS Code extension \`tumaet.apollon-vscode@${VERSION}\`.
 
+          # Body = the Changesets-owned CHANGELOG section (curated per-PR voice),
+          # regrouped by category (Features/Bug Fixes/...) from each entry's
+          # commit type, plus an install footer. Fall back to GitHub's
+          # --generate-notes only when there is no changelog section for this
+          # version (e.g. a release that carried no changeset).
+          CHANGELOG=$(node scripts/extract-changelog.mjs "$VERSION" vscode-extension)
+          {
+            if [ -n "$CHANGELOG" ]; then printf '%s\n\n' "$CHANGELOG"; fi
+            cat <<EOF
           Install:
-          \`\`\`
+
+          \`\`\`sh
           code --install-extension tumaet.apollon-vscode
           \`\`\`
 
-          Published to [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=tumaet.apollon-vscode) and [Open VSX](https://open-vsx.org/extension/tumaet/apollon-vscode). VSIX attached for sideloading." \
+          Published to [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=tumaet.apollon-vscode) and [Open VSX](https://open-vsx.org/extension/tumaet/apollon-vscode). VSIX attached for sideloading.
+          EOF
+          } > release-notes.md
+
+          GENERATE=()
+          [ -z "$CHANGELOG" ] && GENERATE=(--generate-notes)
+
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --target "$GITHUB_SHA" \
+            --verify-tag \
+            --latest=false \
+            "${GENERATE[@]}" \
+            --notes-file release-notes.md \
             "$VSIX"

docs/contributor/deployment/npm-publishing.md

@@ -25,7 +25,7 @@ The cost of that group is worth naming: a changeset touching only the extension
 The per-PR side is Changesets: authors run `pnpm changeset` on every user-visible PR to record a changelog entry with its bump type (see [Release notes](/contributor/development/release-notes)). On every push to `main`, `release.yml` runs [`changesets/action`](https://github.com/changesets/action) in **version-only** mode (no `publish` input — the bespoke `release-*.yml` workflows own publishing) and opens or updates a single **Version Packages** PR. That PR runs `pnpm changeset:version`, which:
 
 - consumes the accumulated `.changeset/*.md` files and bumps `@tumaet/apollon` and the paired `@tumaet/webapp` + `@tumaet/server` from the **declared** bump types — no human picks a bump;
-- keeps the standalone app's bump **at least as large as the library's**: a library minor → standalone minor, a library major → standalone major (via `scripts/cascade-standalone-bump.mjs`, which runs first and raises a floor only — the standalone can still bump higher on its own app-only changes, and the library is never dragged up). So a library change always ships to npm **and** as a comparable Docker release from the same merge;
+- bumps `@tumaet/apollon`, the standalone pair and `apollon-vscode` to one shared version, taking the largest bump any of them earned. `scripts/cascade-standalone-bump.mjs` still runs first and raises the standalone's floor to the library's bump; inside a `fixed` group that floor is already met, so it is a safety net rather than the mechanism. Because the group is fixed, a bump earned by **any** member raises all of them — a standalone-only or extension-only change does drag the library up, which is the price of one product number. So a library change always ships to npm **and** as a comparable Docker release **and** as a Marketplace release from the same merge;
 - regenerates every `CHANGELOG.md`, rewrites the pinned `@tumaet/apollon@X.Y.Z` CDN URLs (via `scripts/sync-library-version.mjs`), and refreshes the lockfile.
 
 The GitHub Release body for each track is built from that `CHANGELOG.md` section (via `scripts/extract-changelog.mjs`), **regrouped by category** — Features, Bug Fixes, Performance, … — from each entry's Conventional Commit type (resolved from the commit SHA via git; full history is checked out for this, falling back to the semver bump when git can't resolve it) instead of the raw `### Minor/Patch Changes` bump headings (see [Release notes](/contributor/development/release-notes#how-your-change-gets-grouped)); it falls back to GitHub's auto-generated notes only when a version carried no changeset. PR Health Checks also run `sync-library-version.mjs --check`, so a CDN-URL drift can never merge — run `pnpm sync:version` locally to fix one.

docs/contributor/development/release-notes.md

@@ -8,17 +8,17 @@ description: How to write the changeset that becomes a changelog entry — voice
 
 User-facing release notes come from [Changesets](https://github.com/changesets/changesets). One changeset per user-visible PR; its summary becomes the changelog entry verbatim.
 
-Three release lines carry changesets: `@tumaet/apollon` on npm, and `@tumaet/webapp` + `@tumaet/server` as paired `ghcr.io` Docker images. The VS Code extension, the docs site, and the webview sub-packages are excluded in `.changeset/config.json#ignore` — they have their own (or no) release flow, and without the exclusion a routine library bump would version them too, since every package depends on `@tumaet/apollon` via `workspace:*`.
+Four release lines carry changesets: `@tumaet/apollon` on npm, `@tumaet/webapp` + `@tumaet/server` as paired `ghcr.io` Docker images, and `apollon-vscode` on the VS Marketplace. All four share one version — they sit in a single `fixed` group in `.changeset/config.json`, so a release advances them together. The docs site and the extension's webview sub-package are excluded in `#ignore`: they have no release flow of their own, and without the exclusion a routine library bump would version them too, since every package depends on `@tumaet/apollon` via `workspace:*`.
 
 :::note
 The pipeline that consumes changesets is live: `release.yml` opens a **Version Packages** PR that runs `changeset version` → regenerates `CHANGELOG.md` → triggers the release on merge. Write the changeset and the rest is automatic — don't hand-edit `CHANGELOG.md`. See [Releases](/contributor/deployment/npm-publishing).
 :::
 
 ## When do you need one?
 
-Add a changeset whenever a **user, embedder, or operator would notice** a change to `@tumaet/apollon`, `@tumaet/webapp`, or `@tumaet/server` — a new feature, a bug fix, a changed API, or a new deployment step.
+Add a changeset whenever a **user, embedder, or operator would notice** a change to `@tumaet/apollon`, `@tumaet/webapp`, `@tumaet/server`, or `apollon-vscode` — a new feature, a bug fix, a changed API, or a new deployment step. A VS Code-only change needs one too: it is what gives the extension its version bump and its Marketplace release notes.
 
-Skip it when nothing downstream is affected: docs, CI, tests, refactors, and formatting — plus anything touching only the VS Code extension or the docs site (both excluded above). When unsure, add one; an extra changelog line beats a silent gap. The advisory **Verify changesets** check on each PR reminds you.
+Skip it when nothing downstream is affected: docs, CI, tests, refactors, and formatting — plus anything touching only the docs site (excluded above). When unsure, add one; an extra changelog line beats a silent gap. The advisory **Verify changesets** check on each PR reminds you.
 
 ## What you write per PR