@@ -24,16 +24,15 @@
 ## Release note
 
 <!--
-  One or two sentences for people using the package: what's new or fixed, and
-  how to use it. Its first paragraph becomes this PR's line in the release
-  notes, as written, so leave how it works to the rest of the description.
-
-  Into alpha or beta: optional. Leave it empty for a change that only matters
-  while a feature is being built; it's left out of the release notes.
-  Into main: required for feat, fix and perf PRs ("None" if users won't
-  notice). Breaking changes: always required; say what to change.
-  On a promotion PR: the summary at the top of the release.
-
-  Example: Add `squircle-pill-ease-*` to stretch a pill's easing along its
-  straight edges.
+  This PR's line in the alpha and beta release notes, which are generated
+  from the PRs since the last one. Without a note, the PR's title is used.
+  One or two sentences for someone trying the prerelease: what changed and
+  what to use. Write "None" to leave the PR out.
+
+  Optional on PRs into alpha and beta. Required on feat, fix and perf PRs
+  into main, which are released straight away ("None" will do), and on
+  breaking changes anywhere (say what to change).
+
+  A promotion into main instead carries the stable release's notes, written
+  by hand under "## Release notes". See AGENTS.md.
 -->
@@ -0,0 +1,64 @@
+# Notes for agents
+
+## Pull requests
+
+PRs are squash-merged, so the title becomes the commit subject and the description becomes its body. Both feed the release.
+
+### Title
+
+[Conventional Commits](https://www.conventionalcommits.org), checked in CI: `type(scope): description`, with `feat`, `fix`, `perf`, `docs`, `chore`, `test`, `ci`, `style` or `revert` (`refactor` and `build` are rejected). The type sets the next version: `feat` is a minor release, `fix` and `perf` a patch, and `!` after the type a major. Mark a change `!` only if it breaks something in the last stable release.
+
+A `feat`, `fix` or `perf` title is also the PR's line in the alpha and beta release notes when it has no release note, so write it to read well there.
+
+### Description
+
+Keep it short: what changed and why, then a test plan. Detail for reviewers goes here, not in the release notes.
+
+Don't start a line with `BREAKING CHANGE:` unless the PR is one. The description is the squashed commit's body, and that line alone makes the next release a major.
+
+## Release notes
+
+Both kinds are read from PR descriptions when the release is made (`release/notes.mjs`), so they can still be fixed after merging.
+
+### Alpha and beta releases: generated, one line per PR
+
+Each `feat`, `fix` and `perf` PR since the previous alpha or beta gets a line, breaking changes first. The line is the first paragraph of the PR's `## Release note`, or its title without one. Write the note for someone trying the prerelease: what changed and what to use, in one or two sentences (at most 300 characters, no list).
+
+- **Into alpha or beta:** a note is optional. Write one when the title alone wouldn't tell a tester what changed. `None` leaves the PR out, for changes nobody using the package would notice, like the demos and site.
+- **Into main** (released straight away): `feat`, `fix` and `perf` PRs need a note; `None` will do.
+- **Breaking changes**, into any branch: a real note, saying what changed and what to do about it.
+
+### Stable releases: written by hand on the promotion PR
+
+A promotion into main (from alpha or beta) carries the stable release's notes under `## Release notes`, published as written. Promoting is blocked until they're there.
+
+**Write them against the last stable release, not the last alpha or beta.** Someone upgrading from it never saw the prereleases in between.
+
+```sh
+gh release list --exclude-pre-releases --limit 1
+git describe --tags --abbrev=0 --exclude='*-*' origin/main
+```
+
+- Cover what's new or different since that release: one entry per change a user would notice, however many PRs it took.
+- Leave out what only mattered while building it: fixes to bugs no stable release had, and renames or tweaks to options that never shipped. Leave out changes to the demos and site too. To tell whether something shipped, look at the tag: `git grep <name> <tag>`, `git show <tag>:<path>`.
+- Open with a sentence or two on what the release is about, then `### Breaking changes` (with what to do), `### Features` and `### Fixes` as needed, as short bullets. Name the utility, option or export to use; leave how it works to the docs.
+- The section ends at the next `##` heading or a `---` line, so put anything else, like a footer, after one.
+- The PR's "Release notes preview" comment shows the version, warns when it's a major, lists every change since the last stable release to write from, and shows the notes exactly as they'll be published.
+
+```md
+## Release notes
+
+Pills now animate between sizes, and work in Panda as well as Tailwind.
+
+### Fixes
+
+- Borders no longer clip on pills under 24px tall.
+
+---
+```
+
+## Branches and merging
+
+- Branch names need a folder (`claude/…`, `fix/…`); the repo rejects branches without one.
+- Feature work goes into `alpha` and is squash-merged.
+- Promotions (alpha → beta → main) and syncs back down are merged by adding the `promote` label, never the merge button (a required check keeps it shut). After each release, the release workflow merges main into beta and alpha by itself.
@@ -0,0 +1 @@
+@AGENTS.md
@@ -2,34 +2,31 @@
  * semantic-release plugin that writes the release notes, in place of
  * @semantic-release/release-notes-generator.
  *
- * A feature, fix or performance change gets one line when its PR has a
- * release note (the paragraph under `## Release note`, see release-note.mjs),
- * read from the PR as it is now, so a note can still be added or edited after
- * merging; failing that, from its squashed commit. A PR without one is left
- * out: on alpha and beta that's a change that only mattered while a feature
- * was being built. Breaking changes come first, whatever their type, and are
- * never left out; without a note, their title stands in. A promotion PR's own
- * release note becomes the summary at the top of the release it makes.
- * Everything else (chores, docs, CI, the bot's merges) is left out too.
+ * A stable release made by promoting alpha or beta into main publishes the
+ * promotion PR's `## Release notes` as written. Someone wrote them by hand,
+ * against the last stable release (see AGENTS.md), so a feature built over
+ * several PRs reads as one change, and what only mattered while building it
+ * is left out.
+ *
+ * Every other release (alpha and beta, or a fix straight into main) is
+ * generated: one line per feature, fix and performance change since the last
+ * release on that branch, breaking changes first. A line is the PR's
+ * `## Release note`, read from the PR as it is now so it can be fixed after
+ * merging; failing that, the note in its squashed commit; failing that, its
+ * title. "None" leaves a PR out, and so do chores, docs, CI and the bot's
+ * merges.
  */
 import {
   SECTIONS,
   extractReleaseNote,
+  extractReleaseNotes,
   isNone,
   normalizeNote,
   parseCommit,
 } from "./release-note.mjs";
 
-/** The bot's merge commit for a promotion PR (.github/scripts/promote.sh). */
-const PROMOTION = /^Merge (?:alpha|beta) into (?:beta|main) \(#(\d+)\)$/;
-
-/** "#40", "#38 and #40", "#1, #2 and abc1234": PR numbers and short hashes as prose. */
-export function refList(refs) {
-  const names = refs.map((ref) => (typeof ref === "number" ? `#${ref}` : ref));
-  return names.length > 1
-    ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`
-    : (names[0] ?? "");
-}
+/** The bot's merge commit for a promotion into main (.github/scripts/promote.sh). */
+const STABLE_PROMOTION = /^Merge (?:alpha|beta) into main \(#(\d+)\)$/;
 
 /** `owner/repo` on GitHub, from Actions' environment or the repository URL. */
 export function repoSlug(repositoryUrl, env = process.env) {
@@ -58,9 +55,7 @@ export function prBodyFetcher({ slug, token, logger = console }) {
           })
           .then((pr) => pr.body ?? "")
           .catch((error) => {
-            logger.warn(
-              `Couldn't read PR #${number}, so its note comes from its commit: ${error.message}`,
-            );
+            logger.warn(`Couldn't read PR #${number}: ${error.message}`);
             return null;
           }),
       );
@@ -69,73 +64,80 @@ export function prBodyFetcher({ slug, token, logger = console }) {
   };
 }
 
+/** The title line: the version, linked to the comparison with the last release. */
+export function releaseTitle({ version, previousTag, tag, date, slug }) {
+  return slug && previousTag
+    ? `## [${version}](https://github.com/${slug}/compare/${previousTag}...${tag}) (${date})`
+    : `## ${version} (${date})`;
+}
+
 /**
- * The release notes for `commits` (`{ message, hash }`, as git log lists them).
- * Returns the Markdown; `leftOut`, the features, fixes and performance changes
- * with no release note; and `untitled`, the breaking changes whose title
- * stood in for a note. Each is a PR number, or a short hash without a PR.
+ * Generated notes for `commits` (`{ message, hash }`, as git log lists them):
+ * the `###` sections, joined, or "" when no commit makes a line.
  */
-export async function renderNotes({ version, previousTag, tag, date, slug, commits, fetchPrBody }) {
+export async function generateSections({ commits, fetchPrBody, slug }) {
   const repoUrl = slug ? `https://github.com/${slug}` : null;
-  const summary = [];
   const breaking = [];
   const sections = new Map(SECTIONS.map(([type]) => [type, []]));
-  const leftOut = [];
-  const untitled = [];
 
   for (const { message, hash } of commits) {
-    const promotion = PROMOTION.exec(message.split("\n")[0]);
-    if (promotion) {
-      const note = extractReleaseNote(await fetchPrBody(Number(promotion[1])));
-      if (note && !isNone(note)) summary.push(normalizeNote(note));
-      continue;
-    }
-
     const commit = parseCommit(message);
     const list = commit.breaking ? breaking : sections.get(commit.type);
     if (!list) continue;
 
-    const ref = commit.pr ?? hash.slice(0, 7);
     const prBody = commit.pr ? await fetchPrBody(commit.pr) : null;
     let note = extractReleaseNote(prBody) || extractReleaseNote(commit.body);
     if (note && isNone(note)) {
       if (!commit.breaking) continue;
       note = null;
     }
-    if (!note) {
-      if (!commit.breaking) {
-        leftOut.push(ref);
-        continue;
-      }
-      note = commit.subject;
-      untitled.push(ref);
-    }
 
     const link = commit.pr
       ? `[#${commit.pr}](${repoUrl}/pull/${commit.pr})`
       : `[${hash.slice(0, 7)}](${repoUrl}/commit/${hash})`;
-    list.push(`- ${normalizeNote(note)}${repoUrl ? ` (${link})` : ""}`);
+    list.push(`- ${normalizeNote(note || commit.subject)}${repoUrl ? ` (${link})` : ""}`);
   }
 
-  const title =
-    repoUrl && previousTag
-      ? `## [${version}](${repoUrl}/compare/${previousTag}...${tag}) (${date})`
-      : `## ${version} (${date})`;
-  const blocks = [title, ...summary];
+  const blocks = [];
   if (breaking.length) blocks.push(`### Breaking changes\n\n${breaking.join("\n")}`);
   for (const [type, heading] of SECTIONS) {
     const lines = sections.get(type);
     if (lines.length) blocks.push(`### ${heading}\n\n${lines.join("\n")}`);
   }
-  if (blocks.length === 1) blocks.push("No user-facing changes.");
-  return { markdown: `${blocks.join("\n\n")}\n`, leftOut, untitled };
+  return blocks.join("\n\n");
+}
+
+/**
+ * The release notes. On a stable release with a promotion PR whose
+ * `## Release notes` are written, those; otherwise generated ones. Returns
+ * the Markdown, whether it was `written`, and the promotion PR, if any.
+ */
+export async function renderNotes({ stable, commits, fetchPrBody, slug, ...release }) {
+  const title = releaseTitle({ slug, ...release });
+  let promotion = null;
+  if (stable) {
+    for (const { message } of commits) {
+      const match = STABLE_PROMOTION.exec(message.split("\n")[0]);
+      if (!match) continue;
+      promotion = Number(match[1]);
+      const written = extractReleaseNotes(await fetchPrBody(promotion));
+      if (written) return { markdown: `${title}\n\n${written}\n`, written: true, promotion };
+    }
+  }
+  const sections = await generateSections({ commits, fetchPrBody, slug });
+  return {
+    markdown: `${title}\n\n${sections || "No user-facing changes."}\n`,
+    written: false,
+    promotion,
+  };
 }
 
 /** semantic-release's generateNotes step. */
 export async function generateNotes(_pluginConfig, context) {
-  const { commits, lastRelease, nextRelease, options, env, logger } = context;
+  const { branch, commits, lastRelease, nextRelease, options, env, logger } = context;
   const slug = repoSlug(options.repositoryUrl, env);
-  const { markdown, leftOut, untitled } = await renderNotes({
+  const { markdown, written, promotion } = await renderNotes({
+    stable: branch.type !== "prerelease",
     version: nextRelease.version,
     previousTag: lastRelease?.gitTag,
     tag: nextRelease.gitTag,
@@ -144,10 +146,11 @@ export async function generateNotes(_pluginConfig, context) {
     commits: commits.map(({ message, hash }) => ({ message, hash })),
     fetchPrBody: prBodyFetcher({ slug, token: env.GITHUB_TOKEN || env.GH_TOKEN, logger }),
   });
-  if (leftOut.length) logger.log(`Left out, with no release note: ${refList(leftOut)}.`);
-  if (untitled.length) {
+  if (written) {
+    logger.log(`Release notes written on #${promotion}.`);
+  } else if (promotion) {
     logger.warn(
-      `Breaking changes with no release note, so their titles stand in: ${refList(untitled)}.`,
+      `#${promotion} has no "## Release notes" to publish, so they're generated instead.`,
     );
   }
   return markdown;