/release-notes

name: release-notes
description: Maintainer-only. Rewrites a version's GAIA CHANGELOG entries as plain-language public release notes for the marketing site (gaiaharness.com), writing a release-data `.ts` file under `../website/src/pages/changelog/releases/` plus an editorial-decisions report for human review. Use when the maintainer wants the public notes for a version ("write release notes", "what's new on the site for v1.5.0"), right after cutting a release, or to backfill a historical `## [x.y.z]` block. Not for editing `CHANGELOG.md` or cutting a release (`/gaia-release`).

release-notes

Rewrite one version's CHANGELOG entries as adopter-facing release notes. The CHANGELOG is written for engineers (mechanics, file paths, flags, exact steps); the website is a marketing page. A visitor skims it to learn what GAIA now does for _their_ project, in plain language, and follows a docs link when they want the detail.

Contents: Pre-flight: Worktree check; Inputs; Output (a): the release data file; Output (b): the editorial-decisions report; The rewriting rules; Worked exemplars; Workflow; See.

It pairs with `/gaia-release` but runs independently: point it at the `[Unreleased]` block while cutting a release, or at any historical `## [x.y.z]` block to backfill the website.

**It never edits `CHANGELOG.md`; it only reads it.**

Pre-flight: Worktree check

This skill writes into the sibling website checkout, so run this first; it refuses in a linked worktree and names the main checkout:

. .gaia/scripts/main-only-lib.sh
gaia_refuse_if_worktree "/release-notes" || exit 1

Inputs

Invocation carries a target version, e.g. `release-notes 1.4.0` (no leading `v`). Resolve which CHANGELOG block to rewrite, and where the date comes from, by that version:

• **Released / historical**: `CHANGELOG.md` contains `## [<version>] - <YYYY-MM-DD>`. Rewrite that block. Take `version` and `date` **verbatim from the header**. The release already happened on that date; the shell clock is irrelevant.
• **Live cut**: the version isn't released yet; its entries live under `## [Unreleased]`. Rewrite that block. `version` is the argument (the maintainer is cutting it now). `date` is **today from the shell clock** (`date +%F`).
• **Review pass**: when `<version>.ts` already exists, its text is the maintainer's approved wording. Change a line only to make it true, to meet VOICE.md, or to move it to its bucket. Read the CHANGELOG only to confirm a claim.

If no version was supplied and an `[Unreleased]` block exists, ask the maintainer which version is being cut. The version label has to come from a human, not a guess.

The date is never yours to invent

Whether historical or live, the date comes from the CHANGELOG header or the shell, **never** from your own notion of "today." Models routinely misdate by months; a wrong `date` silently ships a wrong timeline to every visitor.

Output (a): the release data file

Write to `../website/src/pages/changelog/releases/<version>.ts` (version with no leading `v`; `mkdir -p` the directory if it's missing). The changelog page discovers every file in that directory through `import.meta.glob`, so there is no index or import list to update.

**The schema lives in `../website/src/pages/changelog/types.ts` (the `Release` type); read it as the source of truth for the fields.** For the serialization, mirror the newest `releases/*.ts` exactly, since export style and key order have drifted before, but never copy a `preamble`. Omit any optional key with no content. Today's form, for illustration:

export default {
  added: ['...'],
  date: '2026-06-02',
  fixed: ['...'],
  headline: 'A short title or one plain sentence.',
  improved: ['...'],
  version: '1.4.0',
};

• `added` → "New" (capabilities that didn't exist before). `improved` → "Improved" (changed/enhanced behavior). `fixed` → "Fixed".
• `headline`, **required for any bucketed release** (one or more `added`/`improved`/`fixed` items). A short title or one plain sentence, leading with the release's reason to exist. The buckets render with no title of their own, so a bucketed card with no `headline` ships titleless. A grab-bag with no single story still gets a `headline`: use a descriptive umbrella line naming the two or three biggest items ("Built-in a11y testing, dead-code detection, and stories as tests"), never nothing. The only way to omit `headline` is to let a `summary` carry the lead instead (see below). For a newly shipped capability, carry rule 3's `now` into the headline too, "GAIA apps now ship with a CSP", not "ship with". Rule 17 governs tone.
• `summary` vs buckets, **mutually exclusive.** The renderer shows `summary` as a single paragraph _instead of_ the `added`/`improved`/`fixed` lists. The choice is driven by **how many distinct adopter-facing items survive the cut, not by the release's age or whether it's a backfill.** Use **buckets** whenever one or more itemizable adopter-facing changes remain; each lands as its own bullet under New/Improved/Fixed. Reserve `summary` for: (1) an **internal-only** release where every change was dropped as maintainer plumbing, a one-line "no adopter-facing changes" note; (2) a genuine **one-sentence** story; or (3) a broad **inaugural / overview** release where a narrative reads better than a long list (the `1.0.0` entry). Never set both.
• Bullet strings are markdown-lite: inline code in backticks, links as `[text](url)` (rendered as a new-tab link). Docs links carry the detail (rule 15): `https://docs.gaiaharness.com/<section>/<page>/#<anchor>`, verified against `../docs/src/content/docs/` before writing. Link a GitHub issue or pull request only when no docs page covers the subject, with the link on descriptive words.

Output (b): the editorial-decisions report

After writing the file, print a report to the terminal (don't write a file; this is a human gate the maintainer reads before accepting the notes). It makes your editorial judg