docs(release): make tag-push the canonical release path

.release/RELEASE-FLOW.md

@@ -42,10 +42,15 @@ Fully automated via GitHub Actions `release.yml` workflow dispatch.
 
 ## Publish
 
-- **Trigger**: `gh workflow run release.yml -f version=X.Y.Z`
-- **Dry run**: `gh workflow run release.yml` (no version input)
-- **Flow**: prepare (bump+commit+tag) → version-gate → build-napi (7 targets) →
-  stage+verify → publish-crates → publish-npm → github-release
+- **Trigger (working path — tag-push)**: bump on `main` via PR, then
+  `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`. The tag fires
+  `release.yml`; `prepare` is skipped and build+publish run from the tag.
+- **Dry run**: `gh workflow run release.yml` (no version input) — build + A3 gate,
+  publishes nothing.
+- **BLOCKED**: `gh workflow run release.yml -f version=X.Y.Z` fails GH006 (prepare
+  can't push to protected `main`) — see #127. Do not rely on it yet.
+- **Flow (tag-push)**: version-gate → build-napi (7 targets) → stage+verify →
+  publish-crates → publish-npm → github-release (prepare skipped)
 - **Critical gate**: A3 name↔loader verification (`scripts/verify-napi-names.mjs`)
 
 ## Post-release

CLAUDE.md

@@ -13,15 +13,24 @@ npm test --workspaces --if-present
 
 ## Release
 
-All packages ship as a single coordinated release at the same version. One command:
+All packages ship as a single coordinated release at the same version, driven by
+`release.yml`. **Release via tag-push** (the `workflow_dispatch -f version=` path is
+currently blocked by branch protection — see #127):
 
 ```bash
-gh workflow run release.yml -f version=X.Y.Z
+node scripts/bump-version.mjs X.Y.Z   # bump all manifests + stamp CHANGELOG
+# land the bump on main via PR (CI-gated), then:
+git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z
 ```
 
-This bumps all manifests, stamps CHANGELOG, commits, tags, builds 7 native targets + WASM, publishes to crates.io and npm (with provenance), and creates a GitHub Release. Without the version input it runs a dry-run.
+Pushing the `vX.Y.Z` tag triggers `release.yml` (prepare is skipped): build 7 native
+targets + WASM, A3 name-gate, publish to crates.io and npm (with provenance), create a
+GitHub Release. Run `gh workflow run release.yml` (no version) first for a dry-run that
+validates the build + A3 gate and publishes nothing.
 
-Manual alternative: `node scripts/bump-version.mjs X.Y.Z`, commit, `git tag vX.Y.Z`, push.
+> The `workflow_dispatch -f version=X.Y.Z` "one command" path is **currently broken**
+> (#127): its prepare job can't push the release commit to protected `main` (GH006),
+> so it leaves an orphaned tag and publishes nothing. Use tag-push until #127 is fixed.
 
 See @RELEASING.md for the full runbook.
 

RELEASING.md

@@ -82,28 +82,34 @@ runtime on the affected platform. Do not proceed past a failing gate.
 
 ## Release
 
-### Automated (recommended)
+### Tag-push (current working path)
 
-One command does everything: bumps all versions, stamps the CHANGELOG, commits,
-tags, and publishes:
-
-```bash
-gh workflow run release.yml -f version=X.Y.Z
-```
-
-The `prepare` job bumps all Cargo.toml and package.json files, stamps the
-CHANGELOG, commits to `main`, creates the `vX.Y.Z` tag, and pushes. The
-remaining jobs then build and publish.
-
-### Manual (alternative)
+The release is driven by pushing a `vX.Y.Z` tag. This is how v0.1.0–v0.3.0 shipped.
 
 1. **Bump versions:** `node scripts/bump-version.mjs X.Y.Z` (updates all
-   manifests and stamps the CHANGELOG). Commit and push to `main`.
-2. **Tag and push:**
+   manifests and stamps the CHANGELOG, opening a fresh `[Unreleased]`).
+2. **Land the bump on `main`:** open a PR (CI-gated). `main` is protected and the
+   sole code-owner can't self-approve, so the merge needs an admin override
+   (`enforce_admins=false` permits it). Squash-merge to keep linear history.
+3. **Tag the merged commit and push:**
    ```bash
-   git tag vX.Y.Z
+   git tag -a vX.Y.Z -m vX.Y.Z
    git push origin vX.Y.Z
    ```
+   The tag push triggers `release.yml`; the `prepare` job is skipped and the
+   build+publish jobs run from the tag.
+
+### Automated `workflow_dispatch` — currently BLOCKED (#127)
+
+```bash
+gh workflow run release.yml -f version=X.Y.Z   # DOES NOT WORK YET — see #127
+```
+
+Intended to do everything in one command, but its `prepare` job pushes the release
+commit directly to protected `main`, which branch protection rejects for the Actions
+bot (`GH006`). It leaves an orphaned tag and publishes nothing. Re-enable it by giving
+a release PAT/GitHub App branch-protection bypass, or by having `prepare` open a PR
+instead of pushing to `main` (#127). Until then, use tag-push above.
 
 ### What happens after tagging