Merge remote-tracking branch 'origin/main' into codex/pr-3219-review-work

* origin/main:
  [codex] Add Markdown Prettier CI check (#3242)
  Add /stress-test Claude Code command for adversarial QA (#3207)
  Document examples catalog and naming plan (#3191)
  test(dummy): enable StrictMode in OSS and Pro dummies (#3206)

Author: justin808

.claude/commands/stress-test.md

@@ -10,18 +10,60 @@ on:
       - '**.md'
       - '.github/workflows/check-markdown-links.yml'
       - '.lychee.toml'
+      - '.prettierignore'
+      - '.prettierrc'
+      - 'pnpm-lock.yaml'
   pull_request:
     paths:
       - '**.md'
       - '.github/workflows/check-markdown-links.yml'
       - '.lychee.toml'
+      - '.prettierignore'
+      - '.prettierrc'
+      - 'pnpm-lock.yaml'
   schedule:
     # Run daily at 3am UTC to catch stale cached links
     # See: https://lychee.cli.rs/github_action_recipes/caching/
     - cron: '0 3 * * *'
   workflow_dispatch:
 
 jobs:
+  markdown-format-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: ./.github/actions/setup-node-with-retry
+        with:
+          # Pin to 22.11.0 (LTS) to avoid V8 bug in 22.21.0
+          node-version: '22.11.0'
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts --filter='{.}'
+
+      - name: Check markdown formatting
+        shell: bash
+        run: |
+          markdown_files=()
+          while IFS= read -r -d '' file; do
+            if [ -f "$file" ] && [ ! -L "$file" ]; then
+              markdown_files+=("$file")
+            fi
+          done < <(git ls-files -z -- '*.md' '*.mdx' '*.markdown')
+
+          if [ "${#markdown_files[@]}" -eq 0 ]; then
+            echo "No markdown files to check."
+            exit 0
+          fi
+
+          pnpm exec prettier --check -- "${markdown_files[@]}"
+
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:

.github/workflows/check-markdown-links.yml

@@ -102,14 +102,15 @@ exclude = [
   '^https://www\.diva-portal\.org/smash/get/diva2:1903931/FULLTEXT01\.pdf$',  # Intermittent timeout in CI
 
   # ============================================================================
-  # CHANGELOG COMPARE LINKS
+  # CHANGELOG GITHUB LINKS
   # ============================================================================
   # CHANGELOG.md contains GitHub compare links for each release. The latest
   # release link always references a tag that doesn't exist yet (created after
   # the changelog is committed). Exclude all compare links since they're
-  # auto-generated by changelog tooling.
+  # auto-generated by changelog tooling. GitHub PR pages also intermittently
+  # return 5xx responses to lychee in CI, even when the pages are live.
   '^https://github\.com/shakacode/react_on_rails/compare/',
-  '^https://github\.com/shakacode/react_on_rails/pull/2280$',  # Intermittent 502 from GitHub PR page in CI
+  '^https://github\.com/shakacode/react_on_rails/pull/[0-9]+$',  # Intermittent 5xx from GitHub PR pages in CI
   '^https://github\.com/shakacode/shakapacker/blob/cdf32835d3e0949952b8b4b53063807f714f9b24/package/environments/base\.js(#.*)?$',  # Intermittent 502 from GitHub blob view in CI
 
   # ============================================================================

.lychee.toml

@@ -22,6 +22,7 @@ React on Rails is one product with two tiers: open source for Rails + React inte
 
 ### Evaluating Rails + React options
 
+- [Examples and migration references](./oss/getting-started/examples-and-references.md) — maintained starters, migration repos, and Pro + RSC demos
 - [Example migrations](./oss/migrating/example-migrations.md) — curated migration references and proof criteria
 - [Examples gallery](https://reactonrails.com/examples) — reactonrails.com showcase apps
 - [Compare with alternatives](./oss/getting-started/comparing-react-on-rails-to-alternatives.md) — decision guide covering Hotwire, Inertia, Next.js, and more

docs/README.md

@@ -113,7 +113,8 @@ Webpack's HMR allows the replacement of modules for React in-place without reloa
 
 [github.com/pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin)
 
-You can see an [example commit adding this in the SSR HMR demo](https://github.com/shakacode/react-on-rails-demo-ssr-hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7).
+You can see an example commit in the maintained SSR + HMR tutorial repo that
+[adds React Refresh](https://github.com/shakacode/react-on-rails-demo-ssr-hmr/commit/7e53803fce7034f5ecff335db1f400a5743a87e7).
 
 1. Add react refresh packages:
    ```bash

docs/oss/building-features/rails-webpacker-react-integration-options.md

@@ -4,7 +4,8 @@ See also [Client vs. Server Rendering](../core-concepts/client-vs-server-renderi
 
 ## What is the easiest way to set up a Webpack configuration for server-side-rendering?
 
-See the example Webpack setup here: [github.com/shakacode/react-on-rails-demo-ssr-hmr](https://github.com/shakacode/react-on-rails-demo-ssr-hmr).
+See the maintained SSR + HMR tutorial repo and related evaluation apps in
+[Examples and migration references](../getting-started/examples-and-references.md).
 
 ## What is Server Rendering?
 

docs/oss/core-concepts/react-server-rendering.md

@@ -110,8 +110,10 @@ serverWebpackConfig.output = {
 
 **For older Shakapacker versions:** Use hardcoded paths and manual configuration as shown in the generator templates.
 
-Per the example repo [shakacode/react-on-rails-demo-ssr-hmr](https://github.com/shakacode/react-on-rails-demo-ssr-hmr),
-you should consider keeping your codebase mostly consistent with the defaults for [Shakapacker](https://github.com/shakacode/shakapacker).
+Per the maintained SSR + HMR tutorial repo listed in
+[Examples and migration references](../getting-started/examples-and-references.md),
+you should consider keeping your codebase mostly consistent with the defaults
+for [Shakapacker](https://github.com/shakacode/shakapacker).
 
 # React on Rails
 
@@ -121,7 +123,7 @@ A key decision in your use React on Rails is whether you go with the Shakapacker
 
 ## Option 1: Default Generator Setup: Shakapacker app/javascript
 
-Typical Shakapacker apps have a standard directory structure as documented in the [Shakapacker README](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult the [Shakapacker webpack customization docs](https://github.com/shakacode/shakapacker#webpack-configuration).
+Typical Shakapacker apps have a standard directory structure documented in the [Shakapacker README](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult the [Shakapacker webpack customization docs](https://github.com/shakacode/shakapacker#webpack-configuration).
 
 The _advantage_ of using Shakapacker to configure Webpack is that there is very little code needed to get started, and you don't need to understand really anything about Webpack customization.
 

docs/oss/core-concepts/webpack-configuration.md

@@ -0,0 +1,96 @@
+# Examples and Migration References
+
+Use this page as the canonical index for public React on Rails reference repos.
+The goal is to make evaluation, migration, and React on Rails Pro adoption easy
+to navigate without scattering hard-coded repository links across the docs.
+
+Some public repos still use older slugs with underscores or legacy wording.
+This page is the source of truth for which public repos are current and worth
+starting from.
+
+## Starter Repos
+
+Check each entry's note before evaluating — some starters are fully open
+source, while others require React on Rails Pro.
+
+### SSR + HMR Tutorial Demo (open source)
+
+- Repo: [shakacode/react-on-rails-demo-ssr-hmr](https://github.com/shakacode/react-on-rails-demo-ssr-hmr)
+- Use it when you want the maintained Rails + React + SSR + HMR walkthrough repo
+  that backs the tutorial and Webpack configuration guidance.
+
+### React on Rails Pro + RSC Starter (Pro)
+
+- Repo: [shakacode/react-on-rails-rsc-demo](https://github.com/shakacode/react-on-rails-rsc-demo)
+  _(slug rename to `react-on-rails-demo-rsc` pending — update this line when the
+  rename completes)_
+- Use it when you want a minimal public sample for React Server Components with
+  React on Rails Pro.
+- Note: this repo uses React on Rails Pro. See [OSS vs Pro](./oss-vs-pro.md)
+  for evaluation guidance.
+
+## In-Repo Reference
+
+### Spec Dummy App
+
+- Repo: [shakacode/react_on_rails — spec/dummy](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy)
+- Use it when you want the simplest in-repo reference for current generator and
+  feature behavior.
+- Note: this is the in-repo test app used by the RSpec suite, not a standalone
+  starter repository.
+
+## Migration References
+
+For detailed proof criteria and migration contribution guidance, see
+[Example Migrations](../migrating/example-migrations.md).
+
+- [shakacode/react-on-rails-example-migration](https://github.com/shakacode/react-on-rails-example-migration) —
+  focused before/after `react-rails` → React on Rails migration reference.
+- [shakacode/react-on-rails-example-open-flights](https://github.com/shakacode/react-on-rails-example-open-flights) —
+  larger example app that shows React on Rails replacing `react-rails` in a
+  more realistic codebase.
+
+## React on Rails Pro + RSC Demos
+
+> **Note:** The repos below use React on Rails Pro. See [OSS vs Pro](./oss-vs-pro.md)
+> for evaluation guidance.
+
+### Hacker News RSC Demo
+
+- Repo: [shakacode/react-on-rails-demo-hacker-news-rsc](https://github.com/shakacode/react-on-rails-demo-hacker-news-rsc)
+- Use it when you want a compact public demo of React on Rails Pro with React
+  Server Components on a familiar read-heavy UI.
+
+### Marketplace RSC Performance Demo
+
+- Repo: [shakacode/react-on-rails-demo-marketplace-rsc](https://github.com/shakacode/react-on-rails-demo-marketplace-rsc)
+- Use it when you want a public performance-oriented RSC demo showing the shape
+  of the user-visible win on a marketplace-style surface.
+
+### Gumroad-Style RSC Benchmark Demo
+
+- Repo: [shakacode/react-on-rails-demo-gumroad-rsc](https://github.com/shakacode/react-on-rails-demo-gumroad-rsc)
+- Use it when you want a benchmark-oriented comparison between an Inertia-style
+  surface and a React on Rails Pro + RSC surface on the same product domain.
+- Note: this is a ShakaCode-built demo modeled on a Gumroad-style UI, not an
+  official Gumroad product or integration.
+
+## Live Demos
+
+- [reactrails.com](https://reactrails.com) — production-style React on Rails app
+  you can click through in your browser without any local setup. Backed by the
+  legacy [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial)
+  source.
+
+## Legacy Repos
+
+Version-specific demos, `test-*` repos, generator snapshots, and older tutorial
+repos are useful historical references, but they are not the primary starting
+point for new evaluations.
+
+- Legacy full app: [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) —
+  older production-style app (see Live Demos above for the running site at reactrails.com).
+  Still useful as a historical reference, but not the recommended starting point for new projects.
+
+If you are choosing a public reference repo for docs, talks, or adoption work,
+start with the repos above.

docs/oss/getting-started/examples-and-references.md

@@ -1,6 +1,6 @@
 # React on Rails Basic Tutorial
 
-_Also see the example repo of [React on Rails Tutorial With SSR, HMR fast refresh, and TypeScript](https://github.com/shakacode/react-on-rails-demo-ssr-hmr)_
+_See also [Examples and migration references](./examples-and-references.md) for the maintained tutorial demo, migration references, and current React on Rails Pro + RSC demos._
 
 ---
 

docs/oss/getting-started/tutorial.md

@@ -72,8 +72,8 @@ Step-by-step walkthrough building a full app with Redux, routing, and deployment
 ### 👀 Learn by Example?
 
 - **[Spec/Dummy App](https://github.com/shakacode/react_on_rails/tree/main/react_on_rails/spec/dummy)** - Simple example in this repo
-- **[Tutorial Demo App](https://github.com/shakacode/react-on-rails-demo-ssr-hmr)** - Example with SSR, HMR, and TypeScript
-- **[Live Demo with Source](https://github.com/shakacode/react-webpack-rails-tutorial)** - Full production app at [reactrails.com](https://reactrails.com)
+- **[Examples and migration references](./getting-started/examples-and-references.md)** - Maintained starters, migration references, and Pro + RSC demos
+- **[Live demo at reactrails.com](https://reactrails.com)** - Running React on Rails app you can click through without local setup
 
 ## Popular Use Cases