rsc-universal 0.1.1

package/skills/rails/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: rails
+description: "Use when building or maintaining a Ruby on Rails app — generating or editing app/ models, controllers, views, config/routes.rb, db/migrate; writing ActiveRecord associations/scopes/queries; building Hotwire (Turbo + Stimulus) UI; Active Job / Solid Queue jobs; or Rails tests. Triggers: 'rails generate', 'fix this N+1', 'add a Turbo Stream', 'belongs_to / has_many', 'is this migration safe on a live table?', 'my system test went flaky after I added a Turbo Frame', 'should this be Sidekiq or Solid Queue?', 'scaffold un CRUD en Rails', 'arreglar una consulta ActiveRecord', 'aquesta migració és segura en producció?'. NOT plain Ruby scripts/gems/CLIs with no Rails loaded (that is ruby)."
+tags: [rails, activerecord, hotwire, turbo, stimulus, solid-queue, minitest]
+recommends: [ruby, postgresdb, testing-web, deployment, db-migrations]
+profiles: []
+origin: risco
+---
+
+# Build Rails the omakase way
+
+Write Rails the way a core-adjacent senior would: fat-enough models, skinny
+controllers, zero N+1, strong parameters, migrations that are reversible and safe on a
+live table, and tests that exercise the request rather than the implementation. Lean
+into the Rails 8 "omakase" defaults instead of fighting them — the framework already
+made the boring choices for you.
+
+This is **Rails the framework**: the MVC request cycle, ActiveRecord, Hotwire, Active
+Job, the Rails test stack. The moment code stops loading Rails — a plain script, a gem,
+an `Enumerable` refactor with no `ActiveRecord` in sight — it is no longer this skill.
+That is `ruby` (see `../ruby/SKILL.md`).
+
+## Target versions
+
+```text
+Rails        8.1   (stable line, released 2025-10-22; 8.0 shipped 2024-11-07)
+Ruby         3.4+  (floor for current Rails)
+Jobs/queue   Solid Queue   (default Active Job backend — database-backed, no Redis)
+Cache        Solid Cache   (default cache store — database-backed)
+WebSockets   Solid Cable   (default Action Cable adapter — database-backed)
+Assets       Propshaft     (default; Sprockets is legacy)
+JS           Importmaps    (default; no Node build step required)
+Deploy       Kamal 2 + Thruster
+Front-end    Hotwire = Turbo 8 + Stimulus
+Auth         `rails generate authentication`  (built in; no Devise for basic auth)
+```
+
+A fresh Rails 8 app needs **no Redis and no Node**. Stop reaching for Sidekiq/Redis or
+a JS bundler by reflex — the Solid trifecta and Importmaps already cover the default
+case. Rails 8.1 adds Active Job Continuations (resumable long jobs), Structured Event
+Reporting, local CI via `config/ci.rb`, and Markdown rendering.
+
+## When to use
+
+- Generating/editing anything under `app/` (models, controllers, views, jobs, mailers,
+  channels), `config/routes.rb`, or `db/migrate/`.
+- ActiveRecord work: associations, scopes, validations, callbacks, `includes`/`preload`/
+  `eager_load`, query objects, migrations.
+- Hotwire UI: Turbo Frames/Streams, morphing, Stimulus controllers, broadcasts.
+- Background work via Active Job / Solid Queue; fragment caching via Solid Cache.
+- Rails testing: Minitest model/integration/system tests, fixtures, RSpec + Capybara,
+  debugging flaky Turbo system tests.
+- Upgrading a Rails app or migrating off Redis/Sidekiq onto the Solid stack.
+
+## When NOT to use
+
+- Plain Ruby with no Rails loaded — scripts, gems, CLIs, Bundler packaging → `ruby`.
+- PHP/Laravel → `laravel`. Python/Django → `django`. (Route by the language/framework
+  the file actually uses.)
+- Pure engine-level schema/index/locking depth not expressed as an AR migration →
+  `postgresdb` / `mysql` / `db-migrations`.
+- Host/container/CI provisioning (Kamal host setup, Docker, runners) → `deployment` /
+  `docker` / `github-actions`. This skill writes the Rails-side glue, then hands off.
+
+## The request cycle — where logic lives
+
+Route → controller → model → view. Keep each layer doing one job.
+
+- **Controllers stay skinny.** A controller action finds/builds objects, calls one
+  domain method, and renders/redirects. Why: a controller fat with business rules is
+  untestable except through the full HTTP stack and impossible to reuse.
+- **Domain logic lives on the model.** Validations, scopes, state transitions, and
+  computed attributes belong on the AR class. Why: that is where the data and its
+  invariants already are.
+- **Extract a PORO/service object only when** a method spans 2+ models or does external
+  IO (payment, email, third-party API). Don't pre-extract — a one-model method is just
+  a model method. Why: premature service objects scatter logic that AR would hold fine.
+
+```ruby
+# Good: skinny controller, domain logic on the model.
+class PostsController < ApplicationController
+  def create
+    @post = Current.user.posts.build(post_params)
+    if @post.publish   # model method owns the rule
+      redirect_to @post, notice: "Published"
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def post_params
+    params.expect(post: [:title, :body])   # Rails 8 strong params
+  end
+end
+```
+
+## ActiveRecord
+
+Associations, validations, and scopes are the vocabulary — use them before writing raw
+SQL or manual loops.
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :author, class_name: "User"
+  has_many :comments, dependent: :destroy
+
+  validates :title, presence: true, length: { maximum: 120 }
+  scope :published, -> { where.not(published_at: nil) }
+
+  def publish
+    update(published_at: Time.current)
+  end
+end
+```
+
+**Kill N+1 with eager loading.** The classic footgun is touching an association inside
+a loop, firing one query per row.
+
+```ruby
+# Bad: 1 query for posts + 1 per post for its author (N+1).
+Post.published.each { |p| puts p.author.name }
+
+# Good: 2 queries total — posts, then all authors in one IN(...).
+Post.published.includes(:author).each { |p| puts p.author.name }
+```
+
+Gate it: add the `bullet` gem in development, or mark a hot association
+`strict_loading` so an accidental lazy load raises instead of silently degrading.
+
+**Migrations must be reversible and safe on a live table.** A migration that locks a
+large table blocks every reader and writer for its duration.
+
+```ruby
+# Good: a Postgres index built without an exclusive table lock.
+class AddIndexToPostsOnAuthor < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!   # required — concurrent index can't run in a txn
+  def change
+    add_index :posts, :author_id, algorithm: :concurrently
+  end
+end
+```
+
+Rules: never `add_column ..., default:` on a huge legacy table without checking your
+Rails/Postgres version handles it without a full rewrite; backfill data in batches with
+`find_each` or `update_all`, not one giant `UPDATE` in the migration; add the
+`strong_migrations` gem so unsafe operations fail in review, not in production.
+
+Deeper AR — query objects, `strict_loading`, counter caches, composite primary keys,
+advisory locks, per-operation safe-migration recipes (add column, rename, backfill in
+batches) — is in `references/activerecord.md`.
+
+## Hotwire
+
+Hotwire is the default front-end: Turbo for navigation/updates, Stimulus for behavior.
+Reach for the lightest tool that does the job.
+
+| Need | Use | Why |
+|------|-----|-----|
+| Faster full-page navigation, no code | Turbo Drive (on by default) | Free; intercepts links/forms |
+| Replace one bounded region after an action | Turbo **Frame** | Scoped DOM swap, no JS |
+| Update several elements / push from server | Turbo **Stream** | Targeted append/replace/remove + broadcasts |
+| Re-render a whole page and keep scroll/focus | **Morphing** (Turbo 8) | Diffs the DOM; kills most custom Stream choreography |
+| Client behavior (toggle, copy, debounce) | Stimulus controller | Sprinkle, not a SPA |
+
+Default to Turbo Drive and morphing; only hand-write a Turbo Stream when you need to
+touch elements that morphing can't infer (e.g. prepend to a list from a broadcast).
+
+```javascript
+// app/javascript/controllers/clipboard_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["source"]
+  static values = { successText: { type: String, default: "Copied!" } }
+
+  copy() {
+    navigator.clipboard.writeText(this.sourceTarget.value)
+  }
+}
+```
+
+Worked Frame/Stream/morph examples, model broadcasting (`broadcasts_to`), Stimulus
+values/targets/outlets, and how to system-test Turbo are in `references/hotwire.md`.
+
+## Background jobs & caching
+
+Use Active Job over **Solid Queue** (the Rails 8 default). Two non-negotiable rules:
+
+- **Jobs take serializable arguments — pass IDs, not records.** Why: a serialized AR
+  object goes stale between enqueue and run; an ID is re-fetched fresh.
+- **Jobs must be idempotent.** Why: retries and at-least-once delivery mean a job can
+  run twice; design so the second run is a no-op.
+
+```ruby
+class CommentNotificationJob < ApplicationJob
+  queue_as :default
+
+  def perform(comment_id)
+    comment = Comment.find_by(id: comment_id)
+    return unless comment   # idempotent: nothing to do if it's gone
+    CommentMailer.posted(comment).deliver_now
+  end
+end
+```
+
+For genuinely long work (large backfills, bulk exports) use **Active Job Continuations**
+(Rails 8.1) so a job can checkpoint and resume instead of restarting from zero. Cache
+expensive view fragments with the `cache` helper backed by Solid Cache:
+
+```erb
+<% cache @post do %>
+  <%= render @post.comments %>
+<% end %>
+```
+
+Do **not** add Sidekiq/Redis to a Rails 8 app unless a real, stated throughput or
+latency requirement justifies the extra moving part. Solid Queue covers the default
+case on the database you already run.
+
+## Testing
+
+Minitest + fixtures is the framework default; parallel execution is on by default.
+RSpec-rails (8.x) is the popular alternative. Pick one and exercise behavior through the
+request, never private methods.
+
+| Test type | Base class | Tests |
+|-----------|-----------|-------|
+| Model / unit | `ActiveSupport::TestCase` | validations, scopes, domain methods |
+| Integration | `ActionDispatch::IntegrationTest` | a request → response, status, redirects |
+| System (browser) | `ApplicationSystemTestCase` | end-to-end UI incl. Turbo/Stimulus |
+| Job | `ActiveJob::TestCase` | enqueue + `perform` behavior |
+
+Fixtures (default) are fast and load once; reach for factories (FactoryBot) only when
+per-test object variation gets unwieldy. **Flaky Turbo system test?** It's almost always
+a timing race: never `sleep`. Use Capybara's auto-waiting matchers (`assert_selector`,
+`assert_text`, `assert_no_selector`) which retry until the DOM settles, and swap the
+default Selenium driver for **Cuprite or Playwright** to cut Turbo-timing flake.
+
+Minitest vs RSpec layout, fixtures gotchas, driver config, parallelization, and
+request-spec / broadcast-testing patterns are in `references/testing.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|--------------|--------------|------------|
+| Business logic in the controller | Untestable except through HTTP; not reusable | Push it onto the model; service object only for cross-model/IO |
+| Callback soup (`after_save` chains for business rules) | Hidden order-dependent side effects, brutal to test | Explicit method called from the action; reserve callbacks for data hygiene |
+| Touching an association in a loop | N+1 — one query per row, silent in dev | `includes`/`preload`/`eager_load`; gate with `bullet`/`strict_loading` |
+| Blocking DDL on a big live table | Locks readers + writers for the whole migration | `disable_ddl_transaction!` + `algorithm: :concurrently`; `strong_migrations` |
+| Passing AR records into jobs | Stale serialized state; fails on retry | Pass IDs, re-`find` inside `perform` |
+| Adding Sidekiq/Redis to a Rails 8 app by reflex | A new daemon + dependency for nothing | Solid Queue is the default; add Sidekiq only for a stated need |
+| Queries or business logic in views | N+1 + logic you can't test | Prepare in controller/model; views only render |
+| Testing private methods | Locks tests to internals; refactors break green tests | Test observable behavior through the request |
+| Hand-rolled `fetch`/JS for live updates | Reinvents what Turbo gives free | Turbo Stream or morphing |
+
+## Verify
+
+Run `scripts/verify.sh` inside a Rails app for a read-only static gate: it runs RuboCop
+(if rubocop-rails is configured) and `bin/rails zeitwerk:check`, and greps for the
+statically-detectable anti-patterns above (Sidekiq/Redis in a default app, `.all.each`
+mass loads, a concurrent `add_index` missing `disable_ddl_transaction!`). It skips any
+check whose tooling is absent and exits non-zero only on a hard violation.

package/skills/rails/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — rails
+
+`cases.yaml` is a routing/trigger fixture, not an automated test harness. Run it by
+hand (or via your router-eval tool): feed each `should_trigger` prompt to the skill
+router and confirm it selects `rails`; feed each `should_not_trigger` prompt and confirm
+it routes to the named sibling (`ruby`, `laravel`, `postgresdb`, `deployment`) instead.
+For the `capability` case, give the scenario to the agent with this skill loaded and
+check the produced Rails code satisfies every line in `must_include` — resourceful
+routes, an association + validation, strong params, `includes`-based eager loading, a
+Turbo Stream/morph live update, an `ApplicationSystemTestCase` test with auto-waiting
+assertions, and Solid Queue (never Sidekiq) for any async. No external services or
+network are required.

package/skills/rails/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: rails
+
+should_trigger:
+  - prompt: "Scaffold a blog with Posts and Comments and resourceful routes."
+    why: Core Rails MVC generation — models, controller, routes, views.
+  - prompt: "This index action is slow because of post.author in the loop, fix the N+1."
+    why: ActiveRecord eager-loading; the canonical Rails query footgun.
+  - prompt: "Make the comment list update live when someone posts a new comment."
+    why: Turbo Stream / model broadcast — Hotwire, the Rails default front-end.
+  - prompt: "Is this add_index migration safe to run on a 5M-row table in production?"
+    why: >
+      Non-obvious — reads like a database question, but it is the ActiveRecord
+      migration DSL and Rails migration-safety rules (disable_ddl_transaction!,
+      algorithm: :concurrently, strong_migrations).
+  - prompt: "My Capybara system test started failing randomly after I added a Turbo Frame."
+    why: >
+      Non-obvious Hotwire-timing flake; unmistakably Rails (ApplicationSystemTestCase
+      + Turbo), fixed by auto-waiting matchers / driver swap, not by sleeps.
+  - prompt: "Necesito un job en background con Solid Queue para enviar emails de aviso."
+    why: Spanish — Active Job on the Rails 8 default Solid Queue backend.
+  - prompt: "Aquesta migració amb add_column i default és segura en producció?"
+    why: Catalan — Rails migration safety on a live table.
+
+should_not_trigger:
+  - prompt: "Refactor this standalone Ruby parser script using Enumerable, no Rails involved."
+    route_to: ruby
+    why: Plain Ruby language work; nothing loads Rails or ActiveRecord.
+  - prompt: "Fix my Eloquent hasMany relationship in this Laravel controller."
+    route_to: laravel
+    why: Same MVC problem space, but PHP/Laravel — route by the actual framework.
+  - prompt: "Design the B-tree vs partial index strategy for a Postgres table, no ORM."
+    route_to: postgresdb
+    why: Engine-level index strategy expressed in raw SQL, not an AR migration.
+  - prompt: "Set up the Kamal host, Docker image, and CI runner to deploy the app."
+    route_to: deployment
+    why: Host/container/CI provisioning — infra mechanics, not Rails-side code.
+
+capability:
+  - scenario: "Build a Posts CRUD with Comments, a live-updating comment list, and tests."
+    must_include:
+      - "resourceful nested routes (resources :posts do resources :comments)"
+      - "has_many / belongs_to association plus at least one validation"
+      - "strong parameters via params.expect or require.permit"
+      - "eager loading with includes/preload to avoid N+1 on the comment list"
+      - "Turbo Stream or morphing for the live update (not hand-rolled JS/fetch)"
+      - "a system test using ApplicationSystemTestCase with auto-waiting assertions (assert_text / assert_selector, no sleep)"
+      - "Solid Queue (not Sidekiq/Redis) for any async work introduced"

package/skills/rails/references/activerecord.md

@@ -0,0 +1,148 @@
+# ActiveRecord depth
+
+Patterns for when a model method or migration outgrows the SKILL.md basics.
+
+## Query objects
+
+When a query gets reused or spans several conditions/joins, extract a PORO instead of
+piling scopes or stuffing it in the controller.
+
+```ruby
+# app/queries/recent_active_posts_query.rb
+class RecentActivePostsQuery
+  def initialize(relation = Post.all)
+    @relation = relation
+  end
+
+  def call(since: 30.days.ago)
+    @relation
+      .where("published_at > ?", since)
+      .where(archived: false)
+      .includes(:author)
+      .order(published_at: :desc)
+  end
+end
+```
+
+Keep it returning a relation (not an array) so callers can chain or paginate.
+
+## strict_loading
+
+Make lazy loading raise instead of silently N+1-ing. Set it per-association, per-record,
+or app-wide.
+
+```ruby
+class Post < ApplicationRecord
+  has_many :comments, strict_loading: true
+end
+
+# Or per query:
+Post.strict_loading.find(id).comments   # raises unless preloaded
+```
+
+App-wide default in an environment file: `config.active_record.strict_loading_by_default
+= true`. Turn it on in CI to catch N+1 before production.
+
+## includes vs preload vs eager_load
+
+- `includes` — Rails decides: separate queries (preload) unless you reference the
+  association in a `where`/`order`, then it switches to a JOIN (eager_load).
+- `preload` — always separate queries (two `SELECT`s). Use when you don't filter on the
+  association.
+- `eager_load` — always a single `LEFT OUTER JOIN`. Use when you must filter/sort by the
+  association's columns.
+
+If you `includes(:author).where("users.name = ?", x)` without referencing the table in a
+string condition, add `.references(:author)` so Rails knows to JOIN.
+
+## Large datasets
+
+Never `Model.all.each` over a big table — it loads every row into memory. Batch it:
+
+```ruby
+Post.find_each(batch_size: 1000) do |post|   # loads 1000 at a time
+  post.recompute_score!
+end
+```
+
+For bulk updates with no callbacks needed, `update_all` issues one SQL statement.
+
+## Counter caches
+
+Avoid `COUNT(*)` on every render by caching the count on the parent.
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post, counter_cache: true   # maintains posts.comments_count
+end
+```
+
+Add the `comments_count` integer column; backfill it once with
+`Post.find_each { |p| Post.reset_counters(p.id, :comments) }`.
+
+## Composite primary keys
+
+Rails supports composite keys natively. Declare on the model when the table has a
+two-column PK:
+
+```ruby
+class TravelRoute < ApplicationRecord
+  self.primary_key = [:origin, :destination]
+end
+```
+
+`find` then takes an array: `TravelRoute.find(["NYC", "LON"])`.
+
+## Advisory locks
+
+Serialize a critical section across processes without a row lock, e.g. a singleton
+backfill:
+
+```ruby
+ApplicationRecord.with_advisory_lock("nightly-rollup") do
+  # only one process runs this block at a time
+end
+```
+
+(Via the `with_advisory_lock` gem; Solid Queue uses advisory locks internally for
+concurrency control.)
+
+## Safe migration recipes (per operation)
+
+Each recipe assumes a large live table. `strong_migrations` will flag the unsafe form.
+
+**Add a column** — modern Postgres + Rails handle `default:` without a table rewrite, but
+verify; if in doubt, add the column nullable, then set the default in a follow-up.
+
+```ruby
+add_column :posts, :views_count, :integer, default: 0, null: false
+```
+
+**Add an index** — always concurrent on a hot table:
+
+```ruby
+class AddIndex < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
+  def change
+    add_index :posts, :slug, unique: true, algorithm: :concurrently
+  end
+end
+```
+
+**Rename a column/table** — never do it in place on a live app (old code still
+references the old name). Add the new column, dual-write in the app, backfill, switch
+reads, drop the old column in a later deploy.
+
+**Backfill** — never a single `UPDATE` of millions of rows in a migration (long lock,
+not reversible cleanly). Batch in a separate, idempotent task:
+
+```ruby
+Post.where(views_count: nil).in_batches do |batch|
+  batch.update_all(views_count: 0)
+end
+```
+
+**Add a NOT NULL constraint** — add it as `NOT VALID` then validate separately, or use
+a check constraint, to avoid a full-table scan under lock.
+
+Always confirm `change` is reversible; if not, write explicit `up`/`down`.

package/skills/rails/references/hotwire.md

@@ -0,0 +1,139 @@
+# Hotwire worked examples
+
+Turbo 8 + Stimulus, the Rails 8 default front-end. Reach for the lightest layer that
+solves the problem: Drive → Frame → Stream → morph, and Stimulus only for behavior.
+
+## Turbo Frame — scoped replacement
+
+A frame replaces just its own contents on navigation/submit. Wrap the region and give
+matching IDs.
+
+```erb
+<%# app/views/posts/show.html.erb %>
+<turbo-frame id="post_title">
+  <h1><%= @post.title %></h1>
+  <%= link_to "Edit", edit_post_path(@post) %>
+</turbo-frame>
+```
+
+```erb
+<%# edit.html.erb — same frame id, so only this swaps in %>
+<turbo-frame id="post_title">
+  <%= form_with model: @post do |f| %>
+    <%= f.text_field :title %>
+    <%= f.submit %>
+  <% end %>
+</turbo-frame>
+```
+
+## Turbo Stream — targeted multi-element update
+
+After a create/destroy, return a `.turbo_stream` template to append/replace/remove
+specific DOM nodes. The controller responds to the format:
+
+```ruby
+def create
+  @comment = @post.comments.create!(comment_params)
+  respond_to do |format|
+    format.turbo_stream
+    format.html { redirect_to @post }
+  end
+end
+```
+
+```erb
+<%# create.turbo_stream.erb %>
+<%= turbo_stream.append "comments", @comment %>
+<%= turbo_stream.update "comments_count", @post.comments.count %>
+```
+
+## Broadcasting from a model
+
+Push updates to every subscribed browser over Solid Cable — no controller round-trip.
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post
+  broadcasts_to ->(comment) { [comment.post, :comments] }
+end
+```
+
+```erb
+<%# in show.html.erb, subscribe the page %>
+<%= turbo_stream_from @post, :comments %>
+<div id="comments"><%= render @post.comments %></div>
+```
+
+`broadcasts_to` fires append-on-create / replace-on-update / remove-on-destroy to that
+stream automatically.
+
+## Morphing — full refresh, kept scroll
+
+Turbo 8 can re-render the whole page and morph the DOM diff while preserving scroll and
+focus. Enable it in the layout:
+
+```erb
+<%= turbo_refreshes_with method: :morph, scroll: :preserve %>
+```
+
+Now a plain `redirect_to` / page refresh updates in place without bespoke Stream
+choreography. Use an explicit Stream only when morphing can't infer the change (e.g.
+prepend a row from a background broadcast).
+
+## Stimulus — values, targets, outlets, actions
+
+```javascript
+// app/javascript/controllers/filter_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["query", "results"]
+  static values  = { url: String, debounce: { type: Number, default: 300 } }
+  static outlets  = ["toast"]
+
+  connect() { this.timer = null }
+
+  search() {
+    clearTimeout(this.timer)
+    this.timer = setTimeout(() => this.#fetch(), this.debounceValue)
+  }
+
+  async #fetch() {
+    const res = await fetch(`${this.urlValue}?q=${this.queryTarget.value}`)
+    this.resultsTarget.innerHTML = await res.text()
+    this.toastOutlet?.show("Updated")   // call another controller via outlet
+  }
+}
+```
+
+```erb
+<div data-controller="filter" data-filter-url-value="<%= search_path %>">
+  <input data-filter-target="query" data-action="input->filter#search">
+  <div data-filter-target="results"></div>
+</div>
+```
+
+- **values** — typed, reactive config from data attributes.
+- **targets** — element references inside the controller's scope.
+- **outlets** — call methods on another controller's instance.
+- **actions** — `event->controller#method` wiring.
+
+## System-testing Turbo interactions
+
+Capybara matchers auto-wait, so they survive Turbo's async DOM updates. Never `sleep`.
+
+```ruby
+class CommentsTest < ApplicationSystemTestCase
+  test "comment appears live" do
+    visit post_path(posts(:one))
+    fill_in "Comment", with: "Nice post"
+    click_on "Post comment"
+    assert_text "Nice post"          # retries until the Stream lands
+    assert_selector "#comments .comment", count: 1
+  end
+end
+```
+
+If the page uses broadcasts, ensure the test driver runs the Action Cable/Solid Cable
+connection (default config does). For driver choice and flake-hardening, see
+`testing.md`.