ruact 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ecde11a9eeeaa534f73c9aba3a1c15a1bb44bbe1035467dad11b6f8517085aa
-  data.tar.gz: 7b3077daa2fe5cef2189b40c575df223cc960b49e8ace3ce5cebf8b61afd9e29
+  metadata.gz: f9a45065af0d01daed8548084a9667fb066f9e8c19a685f99b0f101a8e825ca0
+  data.tar.gz: 99206ecd7d61a44b4cdfe52bb5b40b046f66e2938f7bf060e603b98ef17971b8
 SHA512:
-  metadata.gz: 2696f4a816b237e124465604bc04a2d5a54804601d413bf907429376efb8b72d17ff876f013fb4491df47c4b231a696f7213c8e431e5924f4a504e7d2b7a1214
-  data.tar.gz: e1cf6a62a6e0d4e5d061b4dae97fe71d47df9137db0a3cc1581cb1056282a0b757a69eff7d1a7981ae3a419ee9d79be938871cb1f636d612e2a6affd026a809f
+  metadata.gz: d303e5aa55881c70b88a6a7f132450712c8f35adb7b00f0172d3503784dbe82b1373ae7ecc30db05a98832f2c2154134e49bbba43ba403497cdc61b90401b91a
+  data.tar.gz: 8b8fcc40cca7167dece277333fdd56562a62800d150af0be85a50033fc6a2ea3dc8aeebf7650dbb220891f73a843a80d2b0becd1f1d7483b4a2afa6af8a1404e

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.8] - 2026-07-11
+
+### Changed
+
+- **`ManifestError` message is now in English (was Portuguese)** ([Story 15.0](../_bmad-output/implementation-artifacts/15-0-agent-era-hygiene-pass.md)). When the Vite dev server is unreachable AND no `public/react-client-manifest.json` exists on disk, `Ruact::ManifestResolver` now raises `[ruact] Vite dev server unreachable at <url> and no react-client-manifest.json found at <path> — run `bin/dev`.` — same raise site, same `ManifestError` class, same HTTP→file fallback order, same diagnostic content (dev-server URL + manifest path + the `bin/dev` fix); only the language changed. Error messages are prompts — agents (and humans) regex-match them — so the stable tokens (`Vite dev server`, `react-client-manifest.json`, `bin/dev`) are preserved and now spec-pinned.
+
+### Added
+
+- **`ruact_props` now works directly on an ActiveRecord model — loud check deferred from class-load to first serialize for lazy attributes (Story 13.7)** ([Story 13.7](../_bmad-output/implementation-artifacts/13-7-ruact-props-on-activerecord-models.md)). `include Ruact::Serializable; ruact_props :id, :title` on an `ActiveRecord` model used to raise `ArgumentError: method 'title' is not defined` at **class-load**, because ActiveRecord defines its attribute reader methods **lazily** (on first instance access) — so the eager `method_defined?` check fired before the reader existed, even for a real column. The check is now **hybrid**: a **PORO** is still validated eagerly at class-load (byte-identical — a typo still raises immediately), while for a **lazy-attribute (ActiveRecord) class** the not-yet-defined names are recorded and their loud check is **deferred to the first `ruact_serialize`** (via `respond_to?` on the instance, where the DB is up and the reader exists). **The loud-omission guarantee is preserved** (Epic 13.1/13.2 spine): a bogus/typo'd prop still raises the same clean `ArgumentError` — only the *timing* moved for AR (first render of that model instead of boot). No boot-time DB dependency is introduced (`attribute_names`/`column_names` would need a live connection at class-load — rejected), the gem stays **single-dep `nokogiri`** (the ActiveRecord discriminator `defined?(ActiveRecord::Base) && self < ActiveRecord::Base` references the constant only when the host already defined it), and there is **no new config key, no serializer-pipeline change** (an AR model that includes the module already dispatched to `serialize_serializable` → `ruact_serialize`), and **`strict_serialization` is unaffected** (an AR `Serializable` model serializes identically under strict true/false, as a PORO does). This reverses the doc-only guidance shipped in the AGENTS.md/`llms.txt` serialization-contract fix (gem PR #48): `ruact_props` on an AR model is now a first-class pattern again; the manual row hash (`{ id: p.id, title: p.title }`) remains the equivalent for a no-model / partial shape.
+
+- **Auto-revalidate opt-in: one `await` folds a mutation and its in-place refresh into a single call (FR110)** ([Story 15.6](../_bmad-output/implementation-artifacts/15-6-auto-revalidate-opt-in.md)). A mutation whose result is shown *elsewhere* on the page has always needed a manual two-step — `await createPost(fd); await revalidate()` — and the second call is easy to forget, leaving a stale page that reads like a silent bug. There are now two runtime-only, opt-in ways to fold the second call in: an app-wide default via `configureRuactRuntime({ autoRevalidate: true })` (mirrors the existing `defaultHeaders` config), and a per-call `withRefresh(accessor)` wrapper (`await withRefresh(createPost)(fd)`) that forces the refresh for one call and **wins over** the global default. When opted in, a **successful, non-redirecting** mutation `await`s an in-place Flight refresh of the current path (the existing `revalidate()` machinery) **before** the promise resolves, then resolves with the action's JSON result. This is **pure client-side composition** of the two requests that already exist (the POST-JSON mutation + the GET-Flight refresh): **no new wire shape and no inbound Flight deserialization — the serialize-only invariant is untouched.** A `$redirect` response **wins**: the redirect is followed and the refresh is skipped (the destination already re-renders; refreshing the old path would be wrong). A **failed** mutation throws before any refresh runs, so no refresh happens. With no router installed, the descriptive `revalidate()` "wire `setupRouter()`" error surfaces (it is not swallowed) — so a mutation that succeeds but whose refresh rejects **rejects the returned promise**, consistent with `revalidate()`'s loud-by-default stance. Opt-out (default) behavior is **byte-identical** to before, and the generated `.ruact/server-functions.ts` is unchanged — `withRefresh` is imported directly from `ruact/server-functions-runtime` (like `configureRuactRuntime`), so the codegen output and the Ruby↔JS byte-parity fixtures are untouched.
+
+- **Dev-only `[ruact]` log line naming the negotiated response shape per request (FR109)** ([Story 15.5](../_bmad-output/implementation-artifacts/15-5-response-shape-legibility-docs-and-dev-log.md)). The single most confusing thing about a `Ruact::Server` action is that the same action, at the same URL, answers different body shapes depending only on the request's `Accept` header + verb — never on the Ruby. In **development only**, `Ruact::Server` now emits exactly one `[ruact]` line per ruact-negotiated request naming the chosen bucket and the deciding signal — e.g. `[ruact] PostsController#create — Accept: application/json + POST → function-call JSON` — so the dual-bucket negotiation is observable at runtime without a debugger. It covers the function-call-JSON bucket (including its `204` and `$redirect` sub-shapes) and, for a page render on a controller that also includes `Ruact::Controller`, the Flight-page and HTML-shell shapes. Log-only: response body, status, and headers are byte-identical in every environment. It is SILENT outside development and on a plain Rails action on the same controller (a response ruact did not negotiate). Mirrors the F6 warning: a private, dev-gated `after_action` beside it, no new config key. The log vocabulary matches the new canonical caller→shape table in the server-actions docs. Coverage is `Ruact::Server`-only for now — queries (separate `GET /q` dispatch) and page-only controllers are documented in the table but not yet logged (deferred).
+
+- **Public server-side render-assertion helpers: `have_ruact_component` (FR108)** ([Story 15.4](../_bmad-output/implementation-artifacts/15-4-server-side-render-assertion-helpers.md)). A host request/controller spec can now prove a page rendered a given component with given props against the decoded Flight tree — no browser, no brittle string spelunking on the wire bytes. Load it explicitly (`require "ruact/testing"` from your `spec_helper`/`rails_helper` — it is NOT auto-loaded by `require "ruact"`, so a production boot carries no RSpec dependency), then assert `expect(response).to have_ruact_component("PostList")` or `...have_ruact_component("PostList").with_props(a_hash_including("posts" => ...))`. It accepts an ActionDispatch/Rack response (its `.body` is read) or a raw String, in either page shape — a raw `text/x-component` body or the HTML shell embedding `__FLIGHT_DATA`. The component name resolves against the import row the wire actually carries (its export name or module basename); props are asserted in their serialized wire form (string keys, serialized values) via `===`/`hash_including`. Passing a `Ruact::Server` function-call/query response (plain JSON) raises a clear `Ruact::Testing::NotAFlightResponseError` pointing you at `JSON.parse(response.body)` instead. This is a STABLE public matcher that **wraps, not forks**, the internal Story-7.5 structural parser/diff — those were promoted onto the shipped load path as `Ruact::Testing::FlightWireParser` / `Ruact::Testing::FlightStructureDiff`, and the gem's own `Ruact::Spec` matchers now delegate to that single implementation (one source of truth, no drift). New docs "Testing" page covers all three response shapes (pages, function calls, queries).
+
+- **Machine-readable introspection: `ruact:doctor -- --json` and `ruact:routes -- --json` (FR107)** ([Story 15.3](../_bmad-output/implementation-artifacts/15-3-machine-readable-introspection-doctor-routes-json.md)). A coding agent (or CI gate) can now read the two ground-truth surfaces as JSON instead of parsing terminal prose. `ruact:doctor -- --json` emits one document — `schema_version`, an overall `status`, and every health check as `name`/`status`/`message`/`remediation` (a separate, nullable machine-readable fix) — reusing the exact same check results the human path prints (no double-run) and preserving the exit code (0 when all checks pass or warn, 1 on any failure). The new `ruact:routes` task emits the accessor/route table — each entry's `accessor` name, `kind` (action or query), `verb`, `path`, `segments`, and declared `params` (queries from their keyword arguments, actions from their required path segments) — derived from the very same `RouteSource` + `QuerySource` collectors codegen consumes (a shared `Ruact::ServerFunctions.introspect` combine point), so the introspection can never drift from what codegen emits; it writes no bridge or TS file (a CI gate can run it without mutating the tree). Bare `ruact:routes` prints a compact human table. The default human `ruact:doctor` output is unchanged. Both JSON documents are marked EXPERIMENTAL and carry `schema_version: 0` — the shape may change without a major bump while the agent-facing surface is iterated, so parsers should gate on it. The flag is passed after a `--` separator (`bin/rails ruact:doctor -- --json`) so neither Rails nor Rake treats it as an option. The emitted `AGENTS.md`/`llms.txt` "Verify your work" section now references both commands, flagged EXPERIMENTAL.
+
+- **Children inside a component tag now fail loudly at preprocess time instead of degrading silently (FR106)** ([Story 15.2](../_bmad-output/implementation-artifacts/15-2-loud-children-error-in-erb-preprocessor.md)). ruact PascalCase component tags are self-closing only — a component receives a props Hash, never a children element tree — but the #1 predictable JSX-habit mistake, `<Card>Hello</Card>`, used to **degrade silently**: the opening tag became a `__ruact_component__("Card", {})` call with no children while the inner content leaked into the surrounding HTML and the `</Card>` passed through as literal garbage. The ERB preprocessor now raises a dedicated `Ruact::ChildrenNotSupportedError` (a `Ruact::PreprocessorError`, so it flows through the same dev error overlay) naming the component, the template `file:line`, and the exact fix — pass content as a prop, e.g. a self-closing `<Card content={...} />`. Detection keys on a **matching PascalCase closing tag** (`</Card>`), NOT on "opening tag lacks `/>`", so a bare non-self-closing opening with no closing tag (`<Dialog open={true}>`) stays a valid call. It runs **after** Suspense normalization (Step 1), so `<Suspense>...</Suspense>` — the one legitimate paired PascalCase tag, already lowercased to `<ruact-suspense>` — never trips. Output is byte-identical for every valid pattern. The shipped `AGENTS.md`/`llms.txt` trap #1 wording is updated from "fails silently" to "fails loudly" now that the artifact exists.
+
+- **Dev-only `[ruact]` warning when an action registers `ruact_errors` and then renders explicitly on a function-call request (F6)** ([Story 15.0](../_bmad-output/implementation-artifacts/15-0-agent-era-hygiene-pass.md)). The FR98 `errors` injection rides the implicit `default_render`, so an explicit `render json: {...}` on the failed-save branch of a Bucket-2 (function-call) request silently drops the registered validation errors from the JSON body — a legibility trap for agents following the docs literally. In **development only**, `Ruact::Server` now logs exactly one `[ruact]` warning naming the `controller#action`, explaining the opt-out, and pointing at the fix (fall through, bind `errors={ruact_errors}` on a page render, or `redirect_to`). It never fires on the documented-correct patterns: a Bucket-1 `ruact_errors(record); render :new` page render, a `redirect_to` on either bucket, the fall-through itself, or an action that never touches the collector. Log-only — response bodies and statuses are byte-identical in every environment.
+
+- **`rails generate ruact:install` now emits an `AGENTS.md` teaching coding agents the ruact conventions, traps, and verification commands (FR105)** ([Story 15.1](../_bmad-output/implementation-artifacts/15-1-agents-md-install-emission-and-llms-txt.md)). ruact is out-of-distribution for every LLM, so a fresh app now ships the agent context in-repo: the mental model (Rails routes as the single source of truth; ERB as the server component; PascalCase self-closing tags), the verb rule, queries/`useQuery`, the codegen ground truth (`app/javascript/.ruact/server-functions.ts` + `bin/rails ruact:server_functions:generate`), the five traps (children, Ruby-in-braces, Accept-header dual shape, `ruact_errors` fall-through, name derivation), the `ruact_props`/`strict_serialization` allowlist, the SGID helpers, and the verification loop (`bin/rails ruact:doctor`). The emitted content is delimited by `<!-- ruact:begin -->`/`<!-- ruact:end -->` markers and the new `create_agents_md` action is **idempotent and append-aware**: no file → create; a user-authored `AGENTS.md` without markers → the marked section is appended with every pre-existing byte preserved; markers present → skip (re-running install is zero-diff); `--force` refreshes **only** the between-marker content, never user bytes outside it. The same compact reference is served by the docs site at `https://ruact.dev/llms.txt` (kept in sync editorially). New `templates/AGENTS.md.tt` + `:story_15_1` specs (including a ≤160-line template-budget tripwire).
+
+## [0.0.7] - 2026-06-30
+
+### Fixed
+
+- **Boot-race that 500'd the first request in development — the manifest is now resolved from the Vite dev server over HTTP.** On a fresh app the Railtie's `config.to_prepare` read `public/react-client-manifest.json` **once at boot**, but Rails frequently booted (and read the still-missing file) **before** the Vite dev server wrote it — leaving `Ruact.manifest` `nil`. `public/` is not watched, so `to_prepare` never re-fired, and the first request to a view containing a component hit `nil.reference_for` → a cryptic 500. The bundled Vite plugin now **serves the live in-memory manifest at `GET <vite_dev_server>/__ruact/manifest`** (always fresh, reflects HMR rebuilds, internal `_sourceFile` field stripped), and in **development** the gem resolves the manifest through a new `Ruact::ManifestResolver`: it fetches that endpoint over `Net::HTTP` (~1s timeout, once per render/preprocess — not per component), **falls back** to `public/react-client-manifest.json` on disk when the dev server is down, and otherwise raises a **clear, actionable** error (`Vite dev server inacessível … rode bin/dev`) instead of a `NoMethodError`. **Production is untouched** — it still uses the boot-loaded `Ruact.manifest` (raising at boot if the build is missing); the HTTP fetch is dev-only. The Vite plugin continues to **write** `public/react-client-manifest.json` (prod build + the dev fallback). Both render and the FR100 contract validator resolve through the same path (the validator fails open to no-validation when the manifest is unreachable). The three hardcoded `http://localhost:5173` references in `ruact_js_assets` (the react-refresh preamble, `@vite/client`, and the bootstrap `<script src>`) now honor `Ruact.config.vite_dev_server` for consistency.
+
 ## [0.0.6] - 2026-06-30
 
 > **Server functions are route-driven.** A server **mutation** is a normal non-GET
@@ -162,5 +192,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CI matrix** — GitHub Actions: RSpec across Ruby 3.2 × 3.3 × Rails 7.0 × 7.1 × 7.2 × 8.0; RuboCop; YARD docs; memory benchmark; E2E system tests against React 19.0.0 and 19.x (Capybara + Cuprite); non-blocking React@next job with auto-issue on failure.
 - **E2E test app** — `e2e/` Rails app (no DB, in-memory Post model) with full CRUD system tests validating the complete request cycle.
 
-[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.6...HEAD
+[Unreleased]: https://github.com/luizcg/ruact/compare/v0.0.7...HEAD
+[0.0.7]: https://github.com/luizcg/ruact/releases/tag/v0.0.7
 [0.0.6]: https://github.com/luizcg/ruact/releases/tag/v0.0.6

data/docs/internal/decisions/server-functions-api.md

@@ -2179,3 +2179,58 @@ TS-AST `Props` parse; a Ruby DSL / JSON sidecar; a new slot runtime; moving
 validation to render time. The **Epic 10 scaffold** consuming contracts and the
 **playground build-fails CI proof** are **Story 13.6** (`epics-phase-2.md`).
 ADR addendum (2026-06-26).
+
+### 2026-07-11 — Story 13.7 — `ruact_props` works on ActiveRecord models (deferred loud check for lazy attrs)
+
+Story 13.7 reopens **option (A)** that `deferred-work.md` #6 parked (the fix-B
+doc-only route) and makes `include Ruact::Serializable; ruact_props :id, :title`
+boot **directly on an ActiveRecord model**. It also closes the FR100 producer-side
+note (*"hoje `ruact_props` valida só o lado produtor, em class-load"*) by making the
+producer-side check itself AR-aware.
+
+**The bug.** ActiveRecord defines its attribute reader methods **lazily** (via
+`define_attribute_methods`, triggered on first instance access / `method_missing`),
+so at the moment the `ruact_props :title` macro runs, `method_defined?(:title)` is
+`false` **even for a real column**. The eager class-load check
+(`serializable.rb`) raised there — an AR model that included the module crashed at
+boot. (`attribute_names`/`column_names` would tell the truth, but they require a
+**live DB connection** — with none they raise `ActiveRecord::ConnectionNotDefined`
+— so any boot-time check based on them adds a class-load DB dependency, a Rails
+anti-pattern. Rejected.)
+
+**Decision — HYBRID timing (approach iv, locked by Luiz).** The loud check stays,
+but **when** it fires now depends on the class:
+
+- **PORO** — checked **eagerly at class-load** exactly as before. The non-lazy code
+  path is **byte-identical**; a PORO typo still raises `ArgumentError` immediately
+  (the existing PORO spec passes unedited — the C3 regression pin).
+- **ActiveRecord (lazy-attribute) class** — a name whose reader is not-yet-defined
+  is **recorded** at declaration and its loud check is **deferred to the first
+  `ruact_serialize`**, validated via `instance.respond_to?(attr)` (AR's
+  `respond_to?` returns `true` for a real column, `false` for a bogus name — a
+  genuine typo still raises the **same clean `ArgumentError`**, just at first render
+  of that model instead of at boot). The result is memoized (`respond_to?` runs once
+  per class, not per serialize).
+
+**Why this satisfies all four constraints.** C1 loud-omission preserved (PORO at
+boot, AR at first use — still loud, still `ArgumentError`); C2 **no DB dependency at
+boot** (`respond_to?` runs at first-serialize, when the DB is up); C3 PORO
+byte-identical; C4 `strict_serialization` untouched (an AR `Serializable` model
+already dispatches through `serialize_serializable` → `ruact_serialize`, verified
+under strict true/false).
+
+**No new dependency / no new config.** The lazy-attribute discriminator is
+`defined?(ActiveRecord::Base) && self < ActiveRecord::Base` — it references the
+constant **only when the host already defined it**, so the gem stays single-dep
+`nokogiri`. **No eager escape hatch** was added (Luiz chose simplicity — no config
+or macro to force an AR boot check); the natural first-serialize timing is the
+contract. No serializer-pipeline change (dispatch already routed AR → `ruact_serialize`).
+
+**Contract note (the one thing that moved).** For an AR model, a typo'd/omitted prop
+is now caught at the **first render of that model**, not at boot. This is the
+deliberate, documented cost of not adding a boot DB dependency; loudness itself is
+unchanged. The AGENTS.md/`llms.txt`/website reversal (`ruact_props` on AR is a
+first-class pattern again, manual row-hash kept as the no-model equivalent) ships in
+the same story, resolving `deferred-work.md` #7.
+
+ADR addendum (2026-07-11).

data/lib/generators/ruact/install/install_generator.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "erb"
 require "pathname"
 require "rails/generators"
 require "ruact"
@@ -19,7 +20,10 @@ module Ruact
     # 7. Creates Procfile.dev + bin/dev (foreman) so the single `bin/dev`
     #    command boots BOTH Rails and the Vite dev server (Story 14.6, Epic 14
     #    DoD — a ruact app needs both processes).
-    # 8. Runs `npm install` so JavaScript dependencies are ready (FR101);
+    # 8. Emits AGENTS.md (marker-delimited, append-aware, idempotent) so coding
+    #    agents working in the app have ruact's conventions, traps, and
+    #    verification commands in context by default (Story 15.1, FR105).
+    # 9. Runs `npm install` so JavaScript dependencies are ready (FR101);
     #    skippable via --skip-npm.
     #
     # Story 14.2 (FR104) — the generator no longer writes a bootstrap entry into
@@ -205,6 +209,40 @@ module Ruact
         say ""
       end
 
+      # Story 15.1 (FR105) — emit AGENTS.md so coding agents working in the app
+      # have ruact's conventions, traps, and verification commands in context
+      # by default. The ruact content is delimited by explicit markers
+      # (`<!-- ruact:begin -->` / `<!-- ruact:end -->`) so the action can be
+      # append-aware and idempotent:
+      #
+      #   no file                  → create it (the template IS the section)
+      #   file without markers     → APPEND the marked section, every
+      #                              pre-existing user byte preserved
+      #   markers present          → skip (re-running install is zero-diff)
+      #   markers present + --force → refresh ONLY the between-marker content —
+      #                              deliberately narrower than the vite.config
+      #                              full-overwrite posture, because a user's
+      #                              AGENTS.md may carry their own project
+      #                              instructions above/below ruact's section.
+      #
+      # Later stories (15.2 loud children error, 15.3 --json introspection,
+      # 15.4 test helpers) evolve the template; `--force` after a gem upgrade
+      # is the designed refresh path.
+      def create_agents_md
+        destination = Pathname(destination_root).join("AGENTS.md")
+
+        return template("AGENTS.md.tt", "AGENTS.md") unless destination.exist?
+
+        content = destination.read
+        if agents_md_markers_well_formed?(content)
+          refresh_or_skip_agents_md_section
+        elsif agents_md_markers_broken?(content)
+          warn_agents_md_broken_markers
+        else
+          append_agents_md_section(content)
+        end
+      end
+
       # Story 14.1 (FR101) — install JavaScript dependencies so a fresh app is
       # runnable in one command. Runs LAST among the file-producing actions
       # (after every file is written) so a failure here leaves the generated
@@ -261,6 +299,81 @@ module Ruact
 
       private
 
+      # Story 15.1 — the exact marker tokens delimiting the ruact-managed
+      # section of AGENTS.md. For a prose file the only safe idempotency key is
+      # an explicit marker pair (`append_gitignore_entries`-style exact-line
+      # dedup would misfire on edited prose).
+      AGENTS_MD_BEGIN_MARKER = "<!-- ruact:begin -->"
+      AGENTS_MD_END_MARKER   = "<!-- ruact:end -->"
+
+      # The full marked section, non-greedy so nothing outside the marker pair
+      # is ever captured (--force replaces exactly this range).
+      AGENTS_MD_SECTION_RE = /#{Regexp.escape(AGENTS_MD_BEGIN_MARKER)}.*?#{Regexp.escape(AGENTS_MD_END_MARKER)}/m
+      private_constant :AGENTS_MD_BEGIN_MARKER, :AGENTS_MD_END_MARKER, :AGENTS_MD_SECTION_RE
+
+      # The rendered ruact section — the full AGENTS.md.tt body, begin marker
+      # first line through end marker last line (the template IS the section).
+      # Rendered through ERB in the generator's context so the template may
+      # interpolate like any other Thor template (today it is fully static).
+      def agents_md_section
+        @agents_md_section ||= ERB.new(
+          File.read(File.expand_path("templates/AGENTS.md.tt", __dir__)),
+          trim_mode: "-"
+        ).result(binding)
+      end
+
+      # Story 15.1 — append the marked ruact section to a user-authored
+      # AGENTS.md, separated by exactly one blank line, preserving every
+      # pre-existing byte.
+      def append_agents_md_section(existing_content)
+        separator = existing_content.end_with?("\n") ? "\n" : "\n\n"
+        append_to_file "AGENTS.md", "#{separator}#{agents_md_section}"
+      end
+
+      # Story 15.1 — a WELL-FORMED marker pair is present (the caller matched
+      # {AGENTS_MD_SECTION_RE}): skip (idempotent re-run) unless --force, which
+      # replaces ONLY the content between (and including) the marker pair.
+      # Bytes outside the markers are never touched.
+      def refresh_or_skip_agents_md_section
+        unless options[:force]
+          say_status "skip", "AGENTS.md already carries the ruact section " \
+                             "(re-run with --force to refresh it)", :yellow
+          return
+        end
+
+        # Block form so `\`/`\1` sequences in the section are never treated as
+        # backreferences by String#gsub.
+        gsub_file("AGENTS.md", AGENTS_MD_SECTION_RE) { agents_md_section.chomp }
+      end
+
+      # Story 15.1 (Codex R1/R2) — the ONLY marker state the action manages:
+      # exactly one begin marker, exactly one end marker, begin before end.
+      # Anything else — a lone marker, end-before-begin, a stray extra marker
+      # alongside a valid pair, multiple pairs — makes the section boundary
+      # ambiguous, so it is handled as broken (warn + no-op) rather than
+      # guessed at.
+      def agents_md_markers_well_formed?(content)
+        content.scan(AGENTS_MD_BEGIN_MARKER).length == 1 &&
+          content.scan(AGENTS_MD_END_MARKER).length == 1 &&
+          AGENTS_MD_SECTION_RE.match?(content)
+      end
+
+      # Story 15.1 (Codex R1) — SOME marker text is present but not in the one
+      # well-formed shape above. The boundary is ambiguous in BOTH directions —
+      # appending would duplicate content next to stray markers, and replacing
+      # would have to guess the range — so the only byte-safe move is to warn
+      # and leave every byte alone.
+      def agents_md_markers_broken?(content)
+        content.include?(AGENTS_MD_BEGIN_MARKER) || content.include?(AGENTS_MD_END_MARKER)
+      end
+
+      def warn_agents_md_broken_markers
+        say_status "warn", "AGENTS.md has an incomplete ruact marker pair " \
+                           "(#{AGENTS_MD_BEGIN_MARKER} … #{AGENTS_MD_END_MARKER}) — " \
+                           "leaving the file untouched; restore both markers (or delete " \
+                           "the partial ruact section) and re-run", :yellow
+      end
+
       # Story 14.6 (live clean-room fix) — ruact OWNS `bin/dev`. The foreman
       # launcher is load-bearing: it boots BOTH Rails AND the Vite dev server,
       # and Vite is what writes `public/react-client-manifest.json`. Rails'

data/lib/generators/ruact/install/templates/AGENTS.md.tt

@@ -0,0 +1,159 @@
+<!-- ruact:begin -->
+<!-- Managed by `rails generate ruact:install`. Re-run it with --force after a
+     gem upgrade to refresh ONLY this marked section; everything you write
+     outside the markers is preserved. Kept in sync manually with the online
+     copy at https://ruact.dev/llms.txt -->
+
+# ruact — conventions for coding agents
+
+ruact renders React Server Components from Rails. ERB templates ARE the server
+components (serialized to the React Flight wire format), Rails routes are the
+single source of truth, and there is no Node server — Vite only bundles the
+client components. ruact is NOT Inertia, react-rails, or Next.js: do not
+transplant their patterns. When unsure, read the generated code (see "Ground
+truth" below) instead of guessing.
+
+## Mental model
+
+- A page is a normal Rails controller action rendering a normal `.html.erb`.
+- Interactive components live in `app/javascript/components/` as `"use client"`
+  files, mounted from ERB with a PascalCase self-closing tag:
+  `<LikeButton postId={@post.id} />`.
+- Mutations are ordinary non-GET controller actions on a controller that does
+  `include Ruact::Server`. Reads are `Ruact::Query` classes in `app/queries/`.
+- ruact generates a typed TypeScript module from the route table; React imports
+  server functions from `@/.ruact/server-functions`.
+
+## Server functions — the verb rule
+
+`include Ruact::Server` makes a controller's routed non-GET actions
+(`POST`/`PATCH`/`PUT`/`DELETE`) callable from React. GET page actions are
+untouched. There is no per-action DSL and no synthetic endpoint: the action IS
+the function, reached at its real route, visible in `bin/rails routes`. The JS
+runtime forwards the CSRF token automatically; keep `include Ruact::Server`
+AFTER `protect_from_forgery` in the ancestor chain.
+
+```ruby
+class PostsController < ApplicationController
+  include Ruact::Server
+
+  def create
+    @post = Post.create!(post_params) # ivars become the JSON result
+  end
+end
+```
+
+```tsx
+import { createPost } from "@/.ruact/server-functions";
+const { post } = await createPost({ post: { title: "Hi" } });
+```
+
+## Reads — queries and useQuery
+
+Reads are public methods on `Ruact::Query` subclasses in `app/queries/`,
+mounted in `config/routes.rb` with `ruact_queries CatalogQuery` (one named GET
+route per public method, default prefix `/q`). Call them with `useQuery`:
+
+```tsx
+import { categories, useQuery } from "@/.ruact/server-functions";
+const { data, loading, error } = useQuery(categories);
+```
+
+Query params come from the method's keyword arguments and accept ONLY
+`string | number | boolean | null` (arrays/objects are rejected). Queries run
+the host controller's callback chain (authentication etc.) before the query
+object is instantiated.
+
+## Ground truth — read the generated file
+
+`app/javascript/.ruact/server-functions.ts` is regenerated from the route
+table (it is gitignored). It is the authoritative list of every accessor and
+its typed params — READ THAT FILE instead of simulating the name generation.
+Regenerate it after changing routes or queries:
+
+    bin/rails ruact:server_functions:generate
+
+## Five traps
+
+1. **Component tags take no children.** Client component tags are self-closing
+   ONLY: `<Card content={@body} />`, never `<Card>...</Card>`. Children (a
+   matching closing tag) fail LOUDLY with a `PreprocessorError` at preprocess
+   time — pass content as a prop instead. Sole exception: the built-in
+   `<Suspense fallback="...">...</Suspense>` pair.
+2. **`{}` props are Ruby, not JavaScript.** `<Badge label={@post.title} />`
+   evaluates `@post.title` as a Ruby expression in the ERB. No JS ternaries,
+   no `{...spread}`, no JSX children. Plain unbraced string props are not
+   supported either — always use braces.
+3. **One action, two response shapes.** A `Ruact::Server` non-GET action
+   answers JSON — its instance variables, or `204`, or `{"$redirect": path}` —
+   when the request's `Accept` header is exactly `application/json`, which is
+   what every generated-accessor call sends (including
+   `<form action={createPost}>`). Any other request shape renders normally
+   (a Flight stream for client-side navigation, an HTML page otherwise). You
+   cannot infer the response shape from the controller body alone — the
+   caller picks it.
+4. **`ruact_errors` requires fall-through.** On the `if @post.save ... else`
+   path, call `ruact_errors(@post)` and let the action END there — ruact's
+   implicit render injects `errors: { attribute: [messages] }` into the JSON.
+   An explicit `render` on that branch opts out of the injection. In the
+   redirect-back flow, `ruact_errors(@post)` then `redirect_to` carries the
+   errors through flash to the next render.
+5. **Accessor names are derived, not declared.** `posts#create` → `createPost`,
+   `posts#publish_all` → `publishAllPosts`; query methods camelCase the same
+   way (`search_users` → `searchUsers`). Collisions fail loudly at boot;
+   break an action tie with `ruact_function_name :action, as: "otherName"` —
+   a query tie by renaming the query method. Never guess a name — read
+   `app/javascript/.ruact/server-functions.ts`.
+
+## Serialization is an allowlist
+
+Only the fields you name cross to the client. `include Ruact::Serializable` +
+`ruact_props :id, :title` is that allowlist — on a PORO OR an ActiveRecord model
+(lazy AR readers checked on first serialize, not class-load; a typo still raises):
+
+```ruby
+class Post < ApplicationRecord
+  include Ruact::Serializable
+  ruact_props :id, :title # other columns never cross
+end
+```
+
+The manual row hash `{ id: p.id, title: p.title }` is the equivalent for a
+no-model shape. An object with no allowlist warns + falls back to `as_json` in
+dev; production (`strict_serialization`) raises, as does `as_json` returning `self`.
+
+## Record references — signed and explicit
+
+Do not put raw record ids in props and trust them later. Mint a scoped signed
+token and resolve it back:
+
+```ruby
+token = Ruact.signed_global_id(@post, for: :editing, expires_in: 1.hour)
+post  = Ruact.locate_signed(params[:token], for: :editing) # tampered → 400
+```
+
+The purpose (`for:`) is always required; the expiry must be explicit — a
+duration, or a deliberate `expires_in: nil` for a non-expiring token.
+
+## Verify your work
+
+- `bin/rails ruact:doctor` — checks install/config health; exits 1 on failure.
+  Append `-- --json` for the same checks as a machine-readable report.
+- `bin/rails ruact:routes -- --json` — the accessor/route table (each accessor's
+  name, kind, verb, path, params) as JSON, from the same route table codegen
+  reads; bare `ruact:routes` prints a compact human table.
+- Both `--json` outputs are EXPERIMENTAL — the shape may change; gate on their
+  `schema_version` field (currently `0`), do not treat it as a stable contract.
+- `bin/rails ruact:server_functions:generate` — regenerates the TS module;
+  exits 1 on a naming collision or an invalid name.
+- `bin/dev` — boots Rails AND Vite (both are required: Vite serves the client
+  components and writes the client manifest).
+- If your app has TypeScript tooling configured, `npx tsc --noEmit`
+  type-checks call sites against the generated accessor types (a fresh
+  install does not ship a tsconfig).
+- In request specs, `require "ruact/testing"` then assert a page rendered a
+  component — `expect(response).to have_ruact_component("PostList").with_props(including("posts"))`
+  — no browser. Function-call/query responses are JSON: `JSON.parse(response.body)`.
+
+Docs: https://ruact.dev — compact agent reference at https://ruact.dev/llms.txt
+<!-- ruact:end -->

data/lib/ruact/controller.rb

@@ -36,10 +36,16 @@ module Ruact
     # only ever invoked internally by `ruact_html_shell`).
     private :ruact_js_assets, :__ruact_component__
 
-    # Returns the boot-time cached manifest (set by Railtie#config.to_prepare).
-    # No per-request file I/O (AC#6).
+    # Resolves the manifest for this render. In PRODUCTION this is the boot-time
+    # cached +Ruact.manifest+ (set by Railtie#config.to_prepare) — no per-request
+    # I/O. In DEVELOPMENT it fetches the live manifest from the Vite dev server
+    # (falling back to the on-disk file, then a clear error), killing the
+    # boot-race where Rails read the missing file before Vite wrote it and every
+    # first request 500'd on +nil.reference_for+. Called once per render; the
+    # returned manifest is held by RenderPipeline for the whole render (not
+    # re-fetched per component). See {Ruact::ManifestResolver}.
     def ruact_manifest
-      Ruact.manifest
+      ManifestResolver.resolve
     end
 
     # Only activate RSC rendering when the matching .html.erb template exists AND
@@ -151,6 +157,12 @@ module Ruact
     # (matching the legacy `#from_html` ordering) before any streaming
     # response headers are mutated.
     def emit_ruact_response(pipeline, html, render_context, streaming:)
+      # Story 15.5 (FR109) — record which page shape ruact rendered so the
+      # `Ruact::Server` dev log (`__ruact_log_response_shape!`) can name it and,
+      # crucially, stay SILENT on a plain Rails render (this flag is never set
+      # there). `@__`-prefixed → never leaks into `view_assigns`.
+      @__ruact_negotiated_page = ruact_request? ? :flight : :html_shell
+
       if ruact_request? && streaming
         enumerator = pipeline.render({ html: html, render_context: render_context }, mode: :stream)
         response.headers["Content-Type"]      = "text/x-component; charset=utf-8"
@@ -203,6 +215,9 @@ module Ruact
       # Flight redirect and re-render as an `errors` prop (no-op when untouched).
       __ruact_stash_errors_in_flash
 
+      # Story 15.5 (FR109) — mark the Flight-redirect sub-shape for the dev log.
+      @__ruact_negotiated_page = :flight_redirect
+
       render plain: "0:#{JSON.generate({ 'redirectUrl' => redirect_url, 'redirectType' => 'push' })}\n",
              content_type: "text/x-component"
     end

data/lib/ruact/doctor.rb

@@ -6,7 +6,7 @@ require "pathname"
 module Ruact
   # Runs a suite of installation health checks and prints ✓/✗ per check.
   # Extracted from the ruact:doctor Rake task for direct testability (FR27).
-  class Doctor
+  class Doctor # rubocop:disable Metrics/ClassLength
     CHECKS = %i[manifest vite controller layout streaming legacy_constant serialize_only flight_middleware].freeze
     # Built via Array#join so the gem-CI `name-propagation` guard does not
     # match these literals against itself (Story 5.1 review F4 — the doctor
@@ -64,6 +64,14 @@ module Ruact
     # future status) is treated as a failure (review finding R1).
     SUCCESS_STATUSES = %i[pass warn].freeze
 
+    # Story 15.3 (FR107) — version of the machine-readable `ruact:doctor --json`
+    # document (see {#as_json}). This is an **EXPERIMENTAL / UNSTABLE** contract:
+    # `0` signals the shape may change without a major version bump while the
+    # agent-facing introspection surface is iterated. Gate any parser on it.
+    # Distinct from {Ruact::ServerFunctions::Snapshot::VERSION_V2} (the internal
+    # codegen bridge version) — do not conflate the two.
+    SCHEMA_VERSION = 0
+
     # @param serialize_only_root [String] directory whose `**/*.rb` is scanned
     #   for the serialize-only tripwire. Defaults to the gem's own `lib/`;
     #   injectable so specs can point it at a fixture tree.
@@ -78,16 +86,61 @@ module Ruact
 
     def run
       puts "[ruact] Health check"
-      results = CHECKS.map { |check| send(:"check_#{check}") }
-      results.each { |status, message| puts format_result(status, message) }
+      computed = results
+      computed.each { |status, message| puts format_result(status, message) }
       # A :warn must NOT fail the run (Story 13.1 AC3); only :pass / :warn are
       # success. An unexpected status (rendered `✗`) fails loudly rather than
       # being silently treated as a pass (review finding R1).
-      passed = results.all? { |status, _| SUCCESS_STATUSES.include?(status) }
+      passed = passed?(computed)
       puts "Run rails generate ruact:install to fix configuration issues" unless passed
       passed
     end
 
+    # Runs every check ONCE and returns the raw result tuples, index-aligned with
+    # {CHECKS}. Each tuple is `[status, message]` or `[status, message,
+    # remediation]` (the optional 3rd element is a machine-readable fix string,
+    # nil when the check has no cleanly separable remediation). Shared by {#run}
+    # (human path) and {#as_json} (JSON path) so a check like `check_vite` — which
+    # opens a socket — never runs twice. (Story 15.3)
+    #
+    # @return [Array<Array>] one tuple per check, in {CHECKS} order.
+    def results
+      CHECKS.map { |check| send(:"check_#{check}") }
+    end
+
+    # @param computed [Array<Array>] result tuples (defaults to a fresh {#results} run).
+    # @return [Boolean] true when NO check failed — only `:pass`/`:warn` are
+    #   success (mirrors {#run}'s rule; an unexpected status fails).
+    def passed?(computed = results)
+      computed.all? { |status, _| SUCCESS_STATUSES.include?(status) }
+    end
+
+    # Story 15.3 (FR107) — the machine-readable `ruact:doctor --json` document.
+    # Reuses the SAME {#results} tuples the human path prints (no double-run), so
+    # the JSON never disagrees with the `✓/⚠/✗` output. EXPERIMENTAL shape — gate
+    # parsers on `schema_version` (see {SCHEMA_VERSION}). Emits NO prose — the
+    # rake task prints ONLY this document in JSON mode.
+    #
+    # @return [Hash] `{ "schema_version" => Integer, "status" =>
+    #   "pass"|"fail", "checks" => [{ "name" =>, "status" =>, "message" =>,
+    #   "remediation" => (String|nil) }] }`.
+    def as_json
+      computed = results
+      {
+        "schema_version" => SCHEMA_VERSION,
+        "status" => passed?(computed) ? "pass" : "fail",
+        "checks" => CHECKS.each_index.map do |i|
+          status, message, remediation = computed[i]
+          {
+            "name" => CHECKS[i].to_s,
+            "status" => status.to_s,
+            "message" => message,
+            "remediation" => remediation
+          }
+        end
+      }
+    end
+
     private
 
     def check_manifest
@@ -95,7 +148,8 @@ module Ruact
       if Pathname(path).exist?
         [:pass, "Manifest found at #{path}"]
       else
-        [:fail, "Manifest not found — run vite build"]
+        [:fail, "Manifest not found — run vite build",
+         "Run vite build (or bin/dev) to generate the client manifest."]
       end
     end
 
@@ -103,7 +157,8 @@ module Ruact
       TCPSocket.new("localhost", 5173).close
       [:pass, "Vite accessible at localhost:5173"]
     rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-      [:fail, "Vite not accessible at localhost:5173 — run npm run dev"]
+      [:fail, "Vite not accessible at localhost:5173 — run npm run dev",
+       "Run npm run dev (or bin/dev) to start the Vite dev server."]
     end
 
     def check_controller
@@ -111,7 +166,8 @@ module Ruact
       if File.exist?(path) && File.read(path).include?("Ruact::Controller")
         [:pass, "Ruact::Controller included in ApplicationController"]
       else
-        [:fail, "Ruact::Controller not included in ApplicationController"]
+        [:fail, "Ruact::Controller not included in ApplicationController",
+         "Run rails generate ruact:install to include Ruact::Controller in ApplicationController."]
       end
     end
 
@@ -120,7 +176,8 @@ module Ruact
       if File.exist?(path) && File.read(path).include?("ruact: root")
         [:pass, "React shell present in application.html.erb"]
       else
-        [:fail, "React shell missing from application.html.erb"]
+        [:fail, "React shell missing from application.html.erb",
+         "Run rails generate ruact:install to add the React shell to application.html.erb."]
       end
     end
 
@@ -198,7 +255,8 @@ module Ruact
       [:warn,
        "#{present.join(', ')} is mounted and may transform `text/x-component` (Flight) responses, " \
        "breaking the wire contract / streaming. Exclude Flight responses from compression " \
-       "(don't compress `text/x-component`) or mount it so it does not wrap the Flight routes."]
+       "(don't compress `text/x-component`) or mount it so it does not wrap the Flight routes.",
+       "Exclude text/x-component from compression, or mount the middleware so it does not wrap Flight routes."]
     end
 
     # Returns the app middleware stack to scan, or nil when unavailable (no