ruact 0.0.11 → 0.0.12

data/CONTRIBUTING.md

@@ -0,0 +1,233 @@
+# Contributing to ruact
+
+Thanks for wanting to change something here. This guide takes you from a fresh clone to an open pull
+request, and everything it asks you to run, you can run — with this repository and nothing else.
+
+## What this repository is
+
+`luizcg/ruact` is one repository holding three things that ship together:
+
+| Directory | What lives there |
+|---|---|
+| `lib/` | the Ruby library — the ERB preprocessor, the render pipeline, the Flight wire format, the Rails integration, the generators and the Rake tasks |
+| `vendor/javascript/vite-plugin-ruact/` | the Vite plugin — it scans for `"use client"`, emits the client manifest, and generates the typed server-function accessors |
+| `vendor/javascript/ruact-server-functions-runtime/` | the browser-side runtime those generated accessors call |
+
+The two JavaScript packages are **bundled, not published**. A host app never installs them from npm:
+`rails generate ruact:install` writes a `vite.config.js` that imports the plugin by absolute path off the
+installed gem. That has one consequence worth stating up front, because it is what makes the rest of this
+document short — **pointing a Rails app at your checkout of the gem points it at your checkout of the Vite
+plugin too.** There is nothing to link separately, and nothing else to clone. This repository has no
+submodules.
+
+## Prerequisites
+
+| Tool | Version | Why |
+|---|---|---|
+| Ruby | >= 3.2 | the floor in `ruact.gemspec`; CI runs 3.2 and 3.3 |
+| Node.js | 20 | the JavaScript suite and the asset build only — ruact runs no Node process in production |
+| Bundler | any recent | `gem install bundler` |
+
+You do not need a Rails **app** to work on this gem, and you do not install Rails by hand: the `Gemfile`
+pins it to `RAILS_VERSION`, defaulting to 8.0, so `bundle install` brings it. What keeps the suite fast is
+that `spec/support/rails_stub.rb` loads only Rails' core and adds test-only writers on top — the request
+cycle (`action_controller`, `action_view`) is loaded by the handful of specs that actually need it, and by
+nothing else.
+
+## Setup
+
+```bash
+git clone https://github.com/luizcg/ruact.git
+cd ruact
+bundle install
+```
+
+That is the whole setup for a Ruby-side change. If you are touching the Vite plugin or the browser
+runtime, install their dependencies too:
+
+```bash
+cd vendor/javascript/ruact-server-functions-runtime && npm install
+cd ../vite-plugin-ruact && npm ci
+```
+
+The first install is not decoration: the plugin's test run reaches into the runtime package, which keeps
+`react` in its own dependencies.
+
+## Running the checks
+
+These are the jobs in [`.github/workflows/ci.yml`](.github/workflows/ci.yml), which runs on every push and
+every pull request. Running them locally first is the difference between one round and four.
+
+<!-- ci-jobs:begin -->
+
+| CI job | What it checks |
+|---|---|
+| `rspec` | the Ruby suite, on Ruby 3.2/3.3 × Rails 7.0/7.1/7.2/8.0 — eight cells |
+| `rubocop` | style, plus the three custom cops below |
+| `yard` | every public method carries YARD documentation |
+| `js` | the Vite plugin's vitest suite, including its Ruby↔JS byte-parity cases, and a type-level test over the generated accessors |
+| `benchmark` | render-pipeline allocations against a recorded baseline |
+| `name-propagation` | greps the tree for names retired before v0.1.0 |
+| `gate` | that `CHANGELOG.md` gained something if this branch changed what the published gem contains, and that a version bump is one legal semver step to a version nothing has released |
+
+<!-- ci-jobs:end -->
+
+There is one more job, `release`, which publishes to RubyGems. It never runs on a pull request, and on a
+push to `main` it publishes only when `lib/ruact/version.rb` names a version that carries no tag — which is
+a thing a maintainer does deliberately, in a pull request of its own. See [RELEASING.md](RELEASING.md) for
+the release process itself — this document deliberately describes none of it, so the two cannot drift apart.
+
+Locally:
+
+```bash
+bundle exec rspec
+bundle exec rubocop --format github
+rm -rf .yardoc doc && bundle exec yard --fail-on-warning
+bundle exec rake benchmark:memory
+bin/release-gate origin/main HEAD
+```
+
+and, for the `js` job:
+
+```bash
+cd vendor/javascript/vite-plugin-ruact
+npm test
+npm run typecheck
+```
+
+To reproduce one matrix cell other than the default — `RAILS_VERSION` is what the eight `rspec` cells vary,
+and unset means 8.0:
+
+```bash
+RAILS_VERSION=7.2 bundle install && bundle exec rspec
+```
+
+## Trying your working tree in a real app
+
+The suite is fast and the gates are strict, and neither tells you whether your change works in a Rails
+app. This does, in about two minutes. `RUACT` is the absolute path to your clone.
+
+```bash
+export RUACT=/absolute/path/to/your/ruact
+
+rails new myapp --skip-javascript
+cd myapp
+printf '\ngem "ruact", path: "%s"\n' "$RUACT" >> Gemfile
+bundle install
+bin/rails generate ruact:install
+bin/dev
+```
+
+No published gem and no published npm package take part: the `path:` source points Bundler at your
+checkout, and the generated `vite.config.js` imports the Vite plugin from inside it. Both halves of your
+change are live.
+
+Give it something to render — a component in `app/javascript/components/`:
+
+```jsx
+"use client";
+import { useState } from "react";
+
+export function LikeButton({ likes }) {
+  const [count, setCount] = useState(likes);
+  return <button onClick={() => setCount(count + 1)}>{count} likes</button>;
+}
+```
+
+a controller action, and a view that uses the component by name:
+
+```erb
+<h1>Home</h1>
+<LikeButton likes={@likes} />
+```
+
+`bin/dev` runs Rails and Vite together. Load the page and the button counts up.
+
+## Four gates that fail for reasons your diff does not show
+
+Most of CI fails where you expect. These four do not, so they are worth knowing before they surprise you.
+
+1. **`spec/readme_spec.rb`** — `README.md` is pinned **byte for byte** in places: the quick-start block and
+   the demo image reference are compared against literals in the spec, the file is allowed exactly one raw
+   `<img>`, and a `path:` gem source is forbidden there because a reader who copies one installs nothing.
+   Edit the README casually and this goes red.
+
+   ⚠️ **One of its assertions is repository-wide despite living in a README spec.** It runs `git ls-files`
+   over the whole repository and fails if any tracked file is a `.gif`, `.mp4`, `.webm` or `.webp` — media
+   committed here would ship inside every built `.gem` and stay in the clone history forever. So **no
+   document in this repository can carry an image**, including this one. Media lives with the documentation
+   site and is referenced by absolute URL.
+
+   ⚠️ **YARD reads `README.md`.** Curly braces in its prose — `{@likes}`, `{Foo#bar}` — are link macros to
+   YARD, and an unresolvable one turns the `yard` job red for a README edit. Write them as `&#123;` and
+   `&#125;` there.
+
+2. **`spec/readme_demo_message_spec.rb`** — the second half of that pin, covering the demo's message.
+
+3. **`spec/benchmarks/render_pipeline_benchmark_spec.rb`** — an **allocation** baseline at ×1.20 tolerance
+   against `spec/benchmarks/baseline.json`, shared by matrix cells that legitimately differ by around 9%.
+   When it fails, read the header comment at the top of that file before doing anything: it explains how to
+   tell a real regression from accumulated drift, and how to regenerate the baseline if it is drift.
+
+4. **Three custom RuboCop cops**, in `lib/rubocop/cop/ruact/` and enabled in `.rubocop.yml` —
+   `Ruact/NoSharedState`, `Ruact/NoIoInFlight` and `Ruact/NoExtendSelf`. Between them they say that data
+   flows through explicit arguments rather than shared mutable state, that `lib/ruact/flight/**` stays a
+   pure value transformation, and that modules expose explicit class methods.
+
+   Custom cops are the least discoverable failure a newcomer can hit, which is why they are named here —
+   but **the cop source is the authority for what each one actually detects**, and each detects a subset of
+   the rule it is named for rather than the rule entire. `Ruact/NoExtendSelf` also rejects a bare
+   `module_function`, which its name does not suggest. Read the file before assuming a pattern is either
+   caught or allowed.
+
+And one habit rather than a gate: run `yard` after `rm -rf .yardoc doc`, as the block above does. A warm
+cache hides warnings that CI, which checks out fresh, still reports.
+
+## Where a change goes
+
+Every destination below is one you can reach.
+
+| Change | Where |
+|---|---|
+| anything under `lib/`, `app/`, `exe/`, `sig/`, `spec/` | **here** — `luizcg/ruact` |
+| a typo in `README.md`, `CHANGELOG.md` or this file | **here** |
+| the Vite plugin | **here**, at `vendor/javascript/vite-plugin-ruact/` — see the note below |
+| the browser runtime for server functions | **here**, at `vendor/javascript/ruact-server-functions-runtime/` |
+| the documentation site at `ruact.dev` | not in this repository — [open an issue](https://github.com/luizcg/ruact/issues) |
+| roadmap, architecture decisions, design | not in this repository — [open an issue](https://github.com/luizcg/ruact/issues) or a discussion |
+
+**About the Vite plugin.** There is a `vite-plugin-ruact` package on npm. It is **superseded**: nothing in
+ruact installs it, and the plugin that actually runs is the vendored one in this repository. Send plugin
+changes here.
+
+## Where the design work happens
+
+Roadmap, architecture decisions and story planning live in a private repository, so the reasoning behind a
+change is not always visible from here. That does not gate anything: open an issue or a discussion, and the
+outcome of that thinking comes back to you in the thread — you do not need access to propose a change,
+argue for one, or land one.
+
+## Opening the pull request
+
+Branch off `main`, keep one topic per pull request, and open it against `luizcg/ruact`. Before you do:
+
+- [ ] `bundle exec rspec` passes.
+- [ ] `bundle exec rubocop --format github` is clean.
+- [ ] `rm -rf .yardoc doc && bundle exec yard --fail-on-warning` passes, and every new public method has a
+      YARD comment with `@param` and `@return`.
+- [ ] `# frozen_string_literal: true` is the first line of every new Ruby file.
+- [ ] Nothing you added lives in `Ruact::`'s way: gem code stays under `Ruact::`, wire-format code under
+      `Ruact::Flight::`, and no Ruby or Rails core class is reopened.
+- [ ] No `extend self` and no bare `module_function` — explicit class methods or a class instead.
+- [ ] If you touched the Vite plugin or the runtime, `npm test` and `npm run typecheck` pass in
+      `vendor/javascript/vite-plugin-ruact`.
+- [ ] `bin/release-gate origin/main HEAD` passes. If your branch changes anything that goes inside the
+      published gem, it asks [CHANGELOG.md](CHANGELOG.md) for a new bullet under `[Unreleased]` — written
+      for a reader who did not see the diff.
+
+Describe what the change does and why in the pull request body. If it fixes a reported bug, link the issue.
+
+Security issues do **not** go in a pull request — see [SECURITY.md](SECURITY.md) for private reporting.
+
+By contributing you agree that your contribution is licensed under the MIT license in
+[LICENSE.txt](LICENSE.txt).

data/README.md

@@ -58,7 +58,9 @@ export function PostCard({ post, author }) {
 }
 ```
 
-Rails serializes `@post` and `@author` as Ruby values, sends the component tree as a [Flight](https://ruact.dev/docs/concepts/flight-wire-format) payload, and React hydrates it in the browser. No JSON ceremony, no duplicate routes, no Node.js in production.
+Capitalized tag means React. Lowercase stays HTML. `"use client"` is the only directive you need to learn.
+
+Your ERB view renders on the server the way it always did, and ruact sends the result to the browser as a React tree — in the same [wire format](https://ruact.dev/docs/concepts/flight-wire-format) React uses for Server Components, implemented in Ruby. The data the view needs is inlined in the page, so React renders immediately, without a fetch. Node builds the bundle with Vite and is needed nowhere else.
 
 ## Call Rails from React
 
@@ -86,12 +88,12 @@ The verb decides — there is no per-action DSL and no second endpoint. The expo
 
 ## What you get
 
-Every item below is shipped in this gem at v0.0.9:
+Every item below is shipped in this gem at v0.0.11:
 
 - **ERB as server components** — `include Ruact::Controller`, then use your components by name in the views you already have: capitalized is React, lowercase stays HTML. [Docs](https://ruact.dev/docs/concepts/erb-as-server-components)
 - **`"use client"`** — the one directive that marks a file as client-side. The bundled Vite plugin scans for it and writes the manifest. [Docs](https://ruact.dev/docs/concepts/use-client)
-- **Server functions and queries** — `include Ruact::Server` and `Ruact::Query` + `useQuery`, both reachable through a typed module generated from your route table. [Docs](https://ruact.dev/docs/api/server-actions)
-- **Props are an allowlist** — `include Ruact::Serializable` + `ruact_props :id, :title`; other columns never cross. [Docs](https://ruact.dev/docs/api/serializable)
+- **Server functions and queries** — `include Ruact::Server` and `Ruact::Query` + `useQuery`, both reachable through a module generated from your route table. A query's declared keywords become an exact TypeScript signature; an action's accessor is typed to accept an object or a `FormData` and resolve whatever the action answers. [Docs](https://ruact.dev/docs/api/server-actions)
+- **An opt-in allowlist for props** — by default a model prop is serialized with `as_json`, so every attribute crosses and the log says so. `include Ruact::Serializable` + `ruact_props :id, :title` makes it an allowlist, and `strict_serialization` (on in production) turns the permissive path into an error rather than a warning. [Docs](https://ruact.dev/docs/api/serializable)
 - **Validation errors round-trip** — `ruact_errors(record)` hands React `{ title: ["can't be blank"] }` without a serializer. [Docs](https://ruact.dev/docs/api/server-actions)
 - **Signed record references** — `Ruact.signed_global_id(record, for:, expires_in:)` out, `Ruact.locate_signed(token, for:)` back in; a tampered token is a `400`, not a lookup. [Docs](https://ruact.dev/docs/api/server-actions)
 - **Client-side navigation** — link interception, scroll restoration and redirect-after-POST, derived from your Rails routes. [Docs](https://ruact.dev/docs/concepts/navigation)
@@ -112,6 +114,12 @@ That is the whole adaptation, and it holds for any tool that outputs standard Re
 
 For agents driving the app rather than writing one component: `rails generate ruact:install` writes an `AGENTS.md` into your app, [ruact.dev/llms.txt](https://ruact.dev/llms.txt) serves the same context to tools that fetch from the web, and `bin/rails ruact:doctor -- --json` / `bin/rails ruact:routes -- --json` emit machine-readable output (experimental — `schema_version: 0`, and the `--` separator is required).
 
+## Where ruact fits
+
+**A good fit:** a Rails monolith that needs real React on real screens — dashboards, editors, admin tools, anything with interaction that ERB alone makes painful — with one team shipping both sides and no appetite for a second application to keep in sync.
+
+**Not a fit yet:** pages that must render without JavaScript, or content search engines need to read out of the HTML. ruact renders client-side from a payload inlined in the page; there is no server-rendered HTML for the React tree. That is a real gap, not a roadmap wink — if the page is your SEO surface, keep it in ERB (the two coexist in the same app, per-view) or use something that server-renders.
+
 ## Compatibility
 
 | | Version | Where that comes from |
@@ -136,6 +144,8 @@ Everything lives at [ruact.dev](https://ruact.dev):
 
 Bug reports and pull requests are welcome at [github.com/luizcg/ruact/issues](https://github.com/luizcg/ruact/issues).
 
+Setup, the checks a PR runs, and how to try your working tree in a real Rails app: [CONTRIBUTING.md](CONTRIBUTING.md).
+
 Release process: [RELEASING.md](RELEASING.md). Security policy and private reporting: [SECURITY.md](SECURITY.md).
 
 ## License

data/RELEASING.md

@@ -1,209 +1,195 @@
 # Releasing ruact
 
-This document describes the complete release process for `ruact`. Following these steps in order enables any maintainer to cut a release independently.
+A release publishes exactly one artifact: the `ruact` gem, to RubyGems.
 
-The gem and the `vite-plugin-ruact` npm package share the same version number and are **always released together** as a single operation.
+The Vite plugin is not a second artifact. It ships **inside** the gem, under `vendor/javascript/`, together with
+the browser runtime; a generated app imports the plugin by filesystem path off the installed gem. Neither
+bundled package is published, so neither is co-versioned with anything — whatever version number their
+`package.json` files carry is internal to the gem and is not a release. The standalone `vite-plugin-ruact`
+package on npm is a superseded artifact from before the plugin was vendored; no ruact release touches it, and
+nothing this document describes puts anything there.
 
----
+**The pull request is the release.** You write the version into `lib/ruact/version.rb` and stamp the CHANGELOG
+in the same pull request; merging it is what publishes. There is no switch to turn on beforehand and none to
+remember afterwards, and a merge that carries no new version publishes nothing — its content accumulates under
+`[Unreleased]` until somebody decides to cut a release.
+
+That is the whole of this document, and it is why almost every hand step this file used to prescribe has been
+deleted rather than corrected: the workflow builds, uploads and tags, and it writes nothing you would otherwise
+write yourself.
 
-## Pre-Release Checklist
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks that run on every push and pull request and how to run
+them locally — this document deliberately describes none of them, so the two cannot drift apart.
+
+---
 
-Before starting, confirm all of the following:
+## Who owns what
 
-- [ ] All CI jobs are green on `main` (rspec matrix, rubocop, yard, benchmark, e2e)
-- [ ] No open issues or PRs labelled `release-blocker`
-- [ ] `gem/ruact.gemspec` has no TODO placeholder values (`summary`, `homepage_uri`, `source_code_uri`, `allowed_push_host` must all be set to real values before `gem build` will succeed)
-- [ ] You have a RubyGems account with push access to `ruact` and an OTP authenticator configured (MFA is required — `rubygems_mfa_required: true`)
-- [ ] You have an npm account with publish access to `vite-plugin-ruact`
-- [ ] You have GPG or SSH commit signing configured (recommended)
+| | Owner |
+|---|---|
+| Whether this merge publishes | you — by putting a new version in the pull request, or not |
+| The version number | you — typed, in `lib/ruact/version.rb` |
+| What the CHANGELOG entry says | you, in the same pull request |
+| The build, the upload to RubyGems, the tag | the `release` job, on the push to `main` |
+| Anything committed to `main` | nobody but a merge — the job pushes a tag and nothing else |
 
 ---
 
-## Version Decision (SemVer)
+## 1. Decide the version
 
-Given the current version `X.Y.Z`, choose the next version:
+SemVer, against the public API: a breaking change to what consumers call (a renamed public method, a changed
+signature, a removed configuration option, an incompatible change to the Flight wire format) is a major; a
+backwards-compatible feature is a minor; everything else is a patch.
 
-| Change type | Version bump | Example |
-|---|---|---|
-| Breaking change (see below) | Major: `X+1.0.0` | `0.1.0` → `1.0.0` |
-| New feature, backwards-compatible | Minor: `X.Y+1.0` | `0.1.0` → `0.2.0` |
-| Bug fix, patch | Patch: `X.Y.Z+1` | `0.1.0` → `0.1.1` |
+Nothing computes this for you and nothing defaults. That is deliberate: the number used to be derived from a
+default plus a marker in a commit message, which meant a minor could arrive as a side effect of how a merge was
+worded — and the first one would have landed on the version this project has reserved for a milestone it has
+not reached.
 
-**What counts as a breaking change**: any change to the public API that requires consumers to update their code — e.g. renaming a public method, changing method signatures, removing a configuration option, or changing the Flight wire format in a non-backwards-compatible way.
+A minor or a major also moves the supported-versions table in [SECURITY.md](SECURITY.md). Do it in the same
+pull request; nothing checks it.
 
 ---
 
-## Release Steps
-
-### 1. Create a release branch
+## 2. Prepare the release
 
 ```bash
-git checkout -b release/v{X.Y.Z}
+bin/release X.Y.Z
 ```
 
-### 2. Bump the gem version
+It refuses a dirty checkout, and one that is not `main` exactly as the remote has it — a branch is never
+*behind* `main` either, and cutting a release from one would put whatever it carries into the release. It
+refuses a version that is not one step from the current one, and one that is already tagged. Then it writes `lib/ruact/version.rb`, re-resolves `Gemfile.lock` against
+it, moves the accumulated `[Unreleased]` content in [CHANGELOG.md](CHANGELOG.md) under a dated heading, opens a
+fresh empty `[Unreleased]`, rewrites both link references, proves the result against the changelog checks and
+the release gate, commits, pushes, and opens the pull request.
 
-Edit `gem/lib/ruact/version.rb`:
+**The pull-request body it writes is the checklist**, with the version already substituted. There is no
+checklist document in this repository on purpose: a checklist is a second copy of the process in the
+imperative, and it rots the way every other second copy does. This one is generated by the thing that performs
+the process, on every release.
 
-```ruby
-module Ruact
-  VERSION = "{X.Y.Z}"
-end
-```
+You can do all of it by hand — the script performs no step you could not — but then you own the parts it
+proves, and the gate on the pull request is where you find out.
 
-### 3. Bump the npm package version
+CHANGELOG.md deserves one warning of its own, because it has three readers who share no directory: this
+repository, a `.gem` unpacked on somebody's disk, and the generated changelog page on the documentation site.
+An entry may name a file but must not **link** one relatively, because a target that resolves here 404s in the
+other two. Absolute URLs only, or no link at all.
 
-Edit `packages/vite-plugin-ruact/package.json`:
+---
 
-```json
-{
-  "version": "{X.Y.Z}"
-}
-```
+## 3. Merge
 
-### 4. Update `gem/CHANGELOG.md`
+On the resulting push to `main`, the `release` job — which waits on every other job in the workflow — asks one
+question: **does `lib/ruact/version.rb` name a version that has no tag?**
 
-1. Move all items under `## [Unreleased]` into a new section `## [{X.Y.Z}] - {YYYY-MM-DD}`.
-2. Add a new empty `## [Unreleased]` section at the very top (above the new release section).
-3. Add or update the link footer at the bottom:
-   ```
-   [Unreleased]: https://github.com/luizcg/ruact/compare/v{X.Y.Z}...HEAD
-   [{X.Y.Z}]: https://github.com/luizcg/ruact/compare/v{PREV}...v{X.Y.Z}
-   ```
-4. If this release contains breaking changes, ensure the section includes a `[BREAKING]` subsection with a **Migration Guide** (see "Breaking Changes" section below).
+If it does not, the job reports that there is nothing to publish and ends green. That is the ordinary case;
+most merges are not releases.
 
-### 5. Update `packages/vite-plugin-ruact/CHANGELOG.md`
+If it does, the job authenticates to RubyGems through Trusted Publishing (OIDC) — a short-lived credential
+minted for that run, no stored secret, nothing interactive — then builds the gem, uploads it, and **tags last**.
 
-Same format as step 4 for the npm package changelog.
+**Why the tag comes last.** The tag is the record of a publish that finished. An upload that fails leaves no
+tag, so the version is still untagged, so the next green push to `main` tries again — automatically, with
+nothing to unwind and nobody to remember. The cost of that order is a re-run that meets a version already on
+RubyGems, which is why a duplicate-version rejection is treated as *already done* rather than as a failure.
 
-### 6. Commit the release
+**Why a question about state rather than about this push.** A trigger that fired on "the version changed in
+this push" would be lost forever whenever no run is created for a push — which happens, merge commits
+included. The version would then say one thing, RubyGems another, and the next release would skip the number
+entirely. Asking about state instead makes the job idempotent and self-healing: run it twice and the second
+does nothing; miss it once and the next green push repairs it.
 
-```bash
-git add gem/lib/ruact/version.rb \
-        packages/vite-plugin-ruact/package.json \
-        gem/CHANGELOG.md \
-        packages/vite-plugin-ruact/CHANGELOG.md
-git commit -m "Release v{X.Y.Z}"
-```
+---
 
-### 7. Push the release branch and open a PR
+## 4. Verify
 
 ```bash
-git push origin release/v{X.Y.Z}
+curl -s https://rubygems.org/api/v1/versions/ruact/latest.json
 ```
 
-Open a PR from `release/v{X.Y.Z}` → `main`. Wait for CI to go green before continuing.
+Use that endpoint. The other one — `/gems/ruact.json` — is CDN-cached and keeps serving the previous version
+for minutes after a successful publish, which reads exactly like a release that did not happen.
 
-### 8. Merge, verify CI, and tag
-
-Merge the PR. Confirm all CI jobs pass on the merge commit, then tag the verified merge commit:
+---
 
-```bash
-git checkout main
-git pull origin main
-git tag v{X.Y.Z}
-git push origin v{X.Y.Z}
-```
+## 5. When nothing was published and nothing said so
 
-> **Why tag after merge?** Tagging after CI passes on the merge commit ensures the tag always points to a verified, releasable commit. Tagging the branch commit before merge risks tagging code that fails CI after merge.
+From the outside, a release that did not happen and one that did look identical until you check RubyGems. Every
+case below shares one recovery, and it is the reason the trigger has the shape it has: **the version is still
+untagged, so the next green push to `main` publishes it.** Nothing has to be unwound and nothing has to be
+remembered.
 
-### 9. Publish the gem to RubyGems
+**A job the `release` job waits on went red on the push to `main`.** The release job never ran, the merge has
+landed, and no error anywhere says "no release happened". The run that matters is the one on `main`, not the
+one on the pull request:
 
 ```bash
-cd gem
-gem build ruact.gemspec
-gem push ruact-{X.Y.Z}.gem
-# Enter OTP when prompted (MFA is required)
-rm ruact-{X.Y.Z}.gem
+gh run list --branch main -L 3
+gh run rerun <run-id> --failed
 ```
 
-> **Note**: `spec.files` in the gemspec is populated via `git ls-files -z`. The files `CHANGELOG.md`, `RELEASING.md`, and `SECURITY.md` must be committed to git to appear in the gem tarball. Verify with:
-> ```bash
-> gem contents ruact-{X.Y.Z} | grep -E 'CHANGELOG|RELEASING|SECURITY'
-> ```
+**No run was created for the push at all.** Same state, same repair; there is simply no run to re-run. Push
+something green to `main` — the next merge does it on its own.
 
-### 10. Publish the npm package
+**The upload failed, or Trusted Publishing rejected the run.** Nothing was tagged, because the tag is written
+after the upload. Fix the cause and let the next green push reconcile it.
 
-```bash
-cd packages/vite-plugin-ruact
-npm publish
-```
+**The version is on RubyGems but the API still shows the old one.** CDN cache; see §4.
 
-### 11. Create a GitHub Release
+**A release was prepared and should not go out.** If it has not merged, close the pull request — nothing was
+released and nothing has to be undone. If it has, see §6.
 
-1. Go to [Releases](https://github.com/luizcg/ruact/releases/new)
-2. Select tag `v{X.Y.Z}`
-3. Title: `v{X.Y.Z}`
-4. Body: paste the `## [{X.Y.Z}]` section from `gem/CHANGELOG.md`
-5. Publish
+**The suite is red on `main` because the record and the code disagree.** The changelog checks run in a job the
+release job waits on, so once `lib/ruact/version.rb` and `CHANGELOG.md` stop naming the same version, **every**
+later release waits too. The failure names which of the two moved.
 
 ---
 
-## Breaking Changes
-
-When a release contains a breaking change:
+## 6. Stopping a release that has already merged
 
-1. Bump the **major** version (e.g. `0.1.0` → `1.0.0`).
-2. Mark the CHANGELOG entry with `[BREAKING]` and include a **Migration Guide** sub-section:
+Publication is irreversible, so there is a stop — a repository variable, read by the job itself:
 
-   ```markdown
-   ## [1.0.0] - YYYY-MM-DD
+```bash
+gh variable set RUACT_RELEASE_HALT -b stop -R luizcg/ruact
+```
 
-   ### Changed
-   - [BREAKING] `Ruact::Serializable.ruact_props` now rejects non-Symbol arguments at class-load time
+Any non-empty value stops it. Unset — the normal, permanent state — publishes.
 
-   #### Migration Guide
+**A halted run fails red, naming the version it refused.** That is the point of it: the stop is a state
+somebody has to undo, and a stop that produced a quiet, successful-looking run would suppress every later
+release invisibly. This one reddens `main` on the next merge instead, which is a thing you find out about.
 
-   **Before:**
-   ```ruby
-   class Post
-     include Ruact::Serializable
-     ruact_props "id", "title"   # strings silently coerced
-   end
-   ```
-   **After:**
-   ```ruby
-   class Post
-     include Ruact::Serializable
-     ruact_props :id, :title     # must be Symbols
-   end
-   ```
-   ```
+```bash
+gh variable delete RUACT_RELEASE_HALT -R luizcg/ruact
+```
 
-3. Announce the breaking change prominently in the GitHub Release body.
+The version is still untagged while the halt is in place, so clearing it does not require another bump: the
+next green push publishes what was held.
 
 ---
 
-## Rollback
+## 7. Rollback
 
-If a release contains a critical defect and must be pulled:
+If a published version has a critical defect:
 
-**RubyGems** (within 30 days):
 ```bash
-gem yank ruact -v {X.Y.Z}
+gem yank ruact -v X.Y.Z
 ```
 
-**npm** (within 72 hours):
-```bash
-npm unpublish vite-plugin-ruact@{X.Y.Z}
-```
+This is the one RubyGems command still run by a person rather than by the workflow, and it is the one place the
+"nothing interactive" of §3 does not apply: the gem declares `rubygems_mfa_required`, so yanking needs your own
+RubyGems credential and a one-time code. The workflow's OIDC credential is minted for its own run and is no
+help here.
 
-After yanking, cut a patch release (`{X.Y.Z+1}`) with the fix immediately. Do not leave the version yanked without a replacement.
+Then cut a patch release with the fix immediately. A yanked version with no replacement leaves anyone who
+pinned it with nothing to move to. There is nothing to unpublish anywhere else — this process publishes to
+RubyGems only.
 
 ---
 
-## Troubleshooting
-
-**`gem push` fails with "MFA required"**: Run `gem signin` first and ensure your OTP authenticator is set up at https://rubygems.org/settings/edit.
+## Where this ends
 
-**Files missing from gem tarball**: The gemspec uses `git ls-files -z`. Ensure all new files (e.g. `CHANGELOG.md`) are committed to git before running `gem build`.
-
-**CI fails on release branch**: Fix the issue on the release branch and push the fix. Wait for CI to pass before tagging. If you already pushed a tag pointing to a broken commit, delete it and recreate after the fix:
-```bash
-git tag -d v{X.Y.Z}                        # delete local tag
-git push origin :refs/tags/v{X.Y.Z}        # delete remote tag
-# fix the issue, merge, then re-tag from the correct commit
-git checkout main && git pull origin main
-git tag v{X.Y.Z} && git push origin v{X.Y.Z}
-```
-Do not use `git push --force` on tags — force-pushing a tag rewrite history for anyone who has already fetched it.
+The gem is published and verified. The rest of a release — the private planning side — is outside this
+repository and outside this document.