From 6ed1323c1f4f209b5f017d9114940faaec35be52 Mon Sep 17 00:00:00 2001
From: Nahiyan Khan <nahiyan@squareup.com>
Date: Fri, 5 Jun 2026 10:06:53 -0400
Subject: [PATCH] docs: clarify release flow

---
 .changeset/README.md |  6 +++++-
 README.md            | 15 +++++++++++----
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/.changeset/README.md b/.changeset/README.md
index e7dcf28..a45235f 100644
--- a/.changeset/README.md
+++ b/.changeset/README.md
@@ -3,7 +3,11 @@
 This folder is managed by `@changesets/cli`. Use it to record release notes,
 version `@anarchitecture/madrigal`, and publish the package to npm.
 
-Common workflow:
+For release-bearing PRs, add a changeset and let the generated
+`chore: version packages` PR update `package.json` and `CHANGELOG.md`. Do not
+manually bump versions for normal releases.
+
+Common workflow for local testing:
 
 ```bash
 pnpm changeset
diff --git a/README.md b/README.md
index 35bb4aa..08c63c5 100644
--- a/README.md
+++ b/README.md
@@ -319,16 +319,23 @@ ln -sf "$(pwd)/skills/{skill-name}/SKILL.md" ~/.claude/skills/{skill-name}/SKILL
 Madrigal uses [Changesets](https://github.com/changesets/changesets) for
 versioning and npm publishing.
 
-For a release-bearing change, run:
+For a release-bearing change, include a changeset in the feature or fix PR:
 
 ```bash
 pnpm changeset
 ```
 
 After the change lands on `main`, the `Release` GitHub Actions workflow creates
-a version PR when changesets are pending. When that version PR lands, the same
-workflow builds Madrigal and publishes it to npm with provenance. The workflow
-expects the npm automation token in `MADRIGAL_NPM_PUBLISH_TOKEN`.
+a `chore: version packages` PR when changesets are pending. When that generated
+version PR lands, the same workflow builds Madrigal and publishes it to npm with
+provenance. For normal releases, do not edit `package.json` versions or
+`CHANGELOG.md` directly; let the generated version PR own those updates.
+
+The direct publish from PR #21 was a bootstrap correction: `0.1.0` was already
+checked in but unpublished under the corrected `@anarchitecture/madrigal` name.
+Future releases should go through a pending changeset and the generated version
+PR. The workflow expects the npm automation token in
+`MADRIGAL_NPM_PUBLISH_TOKEN`.
 
 Manual release commands are also available: