Merge remote-tracking branch 'origin/main' into jg/docs-sidebar-pro-pages

* origin/main:
  Fix initial page startup race for late-loading client bundles (#3151)
  chore: apply prettier formatting to tracked docs files (#3153)
  docs: comprehensive RSC API documentation and registration consolidation (#3140)
  Split rspec-package-tests into parallel generator/unit shards (#3134)
  fix: add concurrency groups to long-running CI workflows (#3133)
  refactor: add RenderRequest, JsCodeBuilder, and RenderingStrategy abstractions (#3094)
  fix: address deferred review items from PR #2849 (#3093)
  Add complimentary OSS license policy for React on Rails Pro (#3123)
  fix: centralize CI docs-only detection and add CLI flag validation (#3091)
  refactor: replace stub-throw + Object.assign with capability-based composition (#3096)
  Enhance address-review with parallel fixes, self-review, and Greptile verification (#3121)
  fix: Doctor no longer fails custom projects for missing bin/dev (#3117)
  fix: cap webpack <5.106.0 to prevent ExecJS SSR breakage (#3095)
  Add Rspack + RSC compatibility tests and documentation (#1828) (#3120)
  Add error scenarios hub and test pages (#2497)
  docs: document polyfill requirements for web-targeted server bundles (#3092)
  docs: RSC integration pitfalls from tutorial app (#3087)
  docs: fix render function/helper API documentation (#3088)
  Doctor: accept TS/TSX server bundle suffixes (#3111)
  feat: add CI guard requiring sidebar updates when adding docs (#3089)

Author: justin808

.agents/workflows/address-review.md

@@ -112,6 +112,7 @@ Execution flow when terminal access is available:
    - If a claim is wrong, classify it as `SKIPPED` and say why.
    - Preserve comment IDs and thread IDs for later replies and thread resolution.
    - Treat actionable review summary bodies as normal feedback to classify (`MUST-FIX`/`DISCUSS` as appropriate); skip only boilerplate or status-only summaries.
+   - **Claim verification**: Before finalizing `MUST-FIX` classification, verify the reviewer's factual claims against the actual codebase. If local code inspection confirms the code already handles the concern (claim is demonstrably wrong), classify as `SKIPPED` per the rule above. If the evidence is ambiguous or you have only partial confidence the claim is wrong, downgrade to `DISCUSS` and note the discrepancy. If you have access to AI-powered codebase search tools (e.g., Greptile), use them to cross-reference claims for additional confidence, but treat their output as a signal — corroborated claims stay `MUST-FIX`, clearly contradicted claims go to `SKIPPED`, and inconclusive results go to `DISCUSS`.
    - Track only `MUST-FIX` items as your working checklist.
    - Use one checklist entry per must-fix item or deduplicated issue.
    - Use the subject format: `"{file}:{line} - {comment_summary} (@{username})"`.
@@ -151,7 +152,9 @@ Execution flow when terminal access is available:
    - Resolve threads only when the issue is actually handled or explicitly declined with my approval:
      `gh api graphql -f query='mutation($threadId:ID!) { resolveReviewThread(input:{threadId:$threadId}) { thread { id isResolved } } }' -f threadId="<THREAD_ID>"`
    - Do not resolve anything still in progress or uncertain.
+   - **Self-review gate**: After making all code changes but before committing, review the diff for issues introduced by the fixes themselves. Check for correctness bugs, style violations, and inconsistencies with surrounding code. Fix critical issues immediately. This prevents new review cycles caused by the fixes. If you have access to a code-review agent or tool, use it; otherwise, do a manual diff review.
    - Ask for push confirmation before running `git push`.
+   - **Parallel fixes**: When there are 2+ items to fix that touch different files with no logical dependencies, process them in parallel if your environment supports concurrent execution (e.g., sub-agents, background tasks). Items in the same file or with cross-file dependencies must be fixed sequentially. Instruct each sub-agent **not to commit** — all changes must remain unstaged so the self-review gate can run on the combined diff. After parallel fixes complete, verify no conflicts exist between the changes by checking whether any sub-agents touched the same files (`git diff --name-only`).
 
 9. Create follow-up issue (when `f+i` or `m` is chosen):
    - Use `gh issue create --repo "${REPO}"` with title "Follow-up: Review feedback from PR #N"

.claude/commands/address-review.md

@@ -151,6 +151,18 @@ Triage rules:
 - Preserve the original review comment ID and thread ID when available so the command can reply to the correct place and resolve the correct thread later.
 - Treat actionable review summary bodies as normal feedback to classify (`MUST-FIX`/`DISCUSS` as appropriate); skip only boilerplate or status-only summaries.
 
+**Greptile claim verification:**
+
+When Greptile MCP tools are available (`mcp__plugin_greptile_greptile__*`), cross-reference reviewer claims against Greptile's codebase analysis before finalizing triage classifications:
+
+1. For each reviewer comment that asserts a factual claim about the codebase (e.g., "this function doesn't handle null", "this breaks the existing API contract"), query Greptile to verify the claim:
+   - Use `mcp__plugin_greptile_greptile__search_greptile_comments` to find prior Greptile analysis of the same code area
+   - Use `mcp__plugin_greptile_greptile__search_custom_context` to check project-specific context that may confirm or contradict the claim
+2. If Greptile's analysis clearly contradicts the reviewer's claim and local code inspection confirms the code already handles the concern, classify as `SKIPPED` per the existing triage rule (claim is demonstrably wrong). If the analysis is inconclusive or only partially contradicts the claim, downgrade to `DISCUSS` and note the discrepancy (e.g., "Greptile analysis suggests current handling may be correct — needs verification").
+3. If Greptile's analysis corroborates the reviewer's claim, keep the `MUST-FIX` classification with higher confidence.
+4. If Greptile has no relevant data, fall back to local verification only.
+5. Do not block triage on Greptile availability — if the tools are not configured or the API fails, proceed with local verification alone.
+
 ## Step 6: Create Todo List
 
 Create a task list with TodoWrite containing **only the `MUST-FIX` items**:
@@ -250,6 +262,34 @@ When addressing items, after completing each selected item (whether `MUST-FIX` o
 If the user selects `DISCUSS` items to address, treat them the same as `MUST-FIX`: make the code change, reply, and resolve the thread.
 If the user selects skipped/declined items for rationale replies, post those replies too.
 
+**Parallel sub-agents for independent fixes:**
+
+When there are 2+ items to fix that touch different files with no logical dependencies between them, use the Task tool to spawn parallel sub-agents for faster execution:
+
+1. Group items by file path. Items in different files with no cross-file dependencies (e.g., a type change in file A that affects callers in file B) are independent.
+2. For each independent group, spawn a sub-agent via the Task tool with:
+   - The full review comment text and context
+   - The file path and line number
+   - Instructions to make the specific fix and run any relevant file-level checks
+   - A reminder not to modify files outside the assigned scope
+   - An explicit instruction **not to commit** the changes — leave all modifications unstaged so the orchestrator can run the self-review gate on the combined diff before committing
+3. After all sub-agents complete, verify there are no conflicts between their changes by checking whether any sub-agents touched the same files (e.g., `git diff --name-only` to list changed files, then check for overlaps).
+4. If conflicts exist, resolve them sequentially before proceeding.
+5. If a sub-agent fails (crashes, hits a tool error, or produces an incorrect edit), fall back to fixing that item sequentially in the parent agent before proceeding.
+6. Items that touch the same file or have logical dependencies must be fixed sequentially, not in parallel.
+7. If only 1 item needs fixing or all items are in the same file, skip parallel dispatch and fix sequentially as before.
+
+**Self-review gate before pushing:**
+
+After making all code changes but before committing, run a self-review on the diff to prevent new review cycles caused by the fixes themselves:
+
+1. Use the Task tool to launch a code-review sub-agent (e.g., `pr-review-toolkit:code-reviewer` if available, or a general-purpose review agent) against the uncommitted changes (`git diff`).
+2. The self-review should check for: correctness bugs introduced by the fixes, style violations against project standards (CLAUDE.md, linter rules), missing error handling, and inconsistencies with surrounding code.
+3. If the self-review finds critical issues (bugs, security problems, or clear correctness errors), fix them immediately before committing. These are issues that would likely trigger a new review round.
+4. If the self-review finds only minor issues (style nits, naming suggestions), note them but proceed — do not block the push for optional improvements.
+5. If the self-review catches and fixes additional issues, mention this in the commit message (e.g., "also fixed: null check in adjacent error path caught by self-review").
+6. Skip the self-review gate for non-code actions (rationale replies, follow-up issue creation, thread resolution).
+
 **For issue comments (general PR comments):**
 
 ```bash

.github/workflows/benchmark.yml

@@ -51,13 +51,7 @@ on:
   push:
     branches:
       - main
-    paths-ignore:
-      - '**.md'
-      - 'AGENTS_USER_GUIDE.md'
-      - 'docs/**'
-      - 'llms.txt'
-      - 'llms-full.txt'
-      - '.lychee.toml'
+    # Always trigger on main; docs-only detection handles skipping heavy jobs
   pull_request:
     types: [opened, synchronize, reopened, labeled]
     paths-ignore:
@@ -96,17 +90,50 @@ env:
   RAILS_MIN_THREADS: ${{ github.event.inputs.rails_threads || 3 }}
 
 jobs:
+  detect-changes:
+    permissions:
+      contents: read
+      actions: read
+    runs-on: ubuntu-22.04
+    outputs:
+      docs_only: ${{ steps.detect.outputs.docs_only }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 50
+          persist-credentials: false
+      - name: Detect relevant changes
+        id: detect
+        run: |
+          BASE_REF="${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}"
+          script/ci-changes-detector "$BASE_REF"
+        shell: bash
+      - name: Guard docs-only main pushes
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: ./.github/actions/ensure-main-docs-safety
+        with:
+          docs-only: ${{ steps.detect.outputs.docs_only }}
+          previous-sha: ${{ github.event.before }}
+
   benchmark:
+    needs: detect-changes
     # Run on: push to main, workflow_dispatch, or PRs with 'benchmark' label.
     # The 'full-ci' label is intentionally excluded — it controls test workflows,
     # not benchmarks. Use the dedicated 'benchmark' label to trigger perf runs on PRs.
     # See https://bencher.dev/docs/how-to/github-actions/#pull-requests for the extra pull_request condition
+    # Skip docs-only pushes to main to avoid wasting CI resources on non-code changes.
     if: |
-      github.event_name == 'push' ||
-      github.event_name == 'workflow_dispatch' ||
-      (
-        github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository &&
-        contains(github.event.pull_request.labels.*.name, 'benchmark')
+      !(
+        github.event_name == 'push' &&
+        github.ref == 'refs/heads/main' &&
+        needs.detect-changes.outputs.docs_only == 'true'
+      ) && (
+        github.event_name == 'push' ||
+        github.event_name == 'workflow_dispatch' ||
+        (
+          github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository &&
+          contains(github.event.pull_request.labels.*.name, 'benchmark')
+        )
       )
     runs-on: ubuntu-latest
     permissions:

.github/workflows/check-docs-sidebar.yml

@@ -0,0 +1,38 @@
+name: Check Docs Sidebar
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/oss/**'
+      - 'docs/pro/**'
+      - 'docs/sidebars.ts'
+      - 'docs/.sidebar-exclusions'
+      - 'script/check-docs-sidebar'
+      - '.github/workflows/check-docs-sidebar.yml'
+  pull_request:
+    paths:
+      - 'docs/oss/**'
+      - 'docs/pro/**'
+      - 'docs/sidebars.ts'
+      - 'docs/.sidebar-exclusions'
+      - 'script/check-docs-sidebar'
+      - '.github/workflows/check-docs-sidebar.yml'
+  workflow_dispatch:
+
+jobs:
+  check-sidebar:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check new docs have sidebar entries
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}
+        run: script/check-docs-sidebar "$BASE_REF"

.github/workflows/examples.yml

@@ -3,6 +3,10 @@ name: Generator tests # TODO needs to be duplicated for RoR Pro
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.event.pull_request.number && format('{0}-pr-{1}', github.workflow, github.event.pull_request.number) || format('{0}-{1}', github.workflow, github.sha) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 on:
   push:
     branches:

.github/workflows/gem-tests.yml

@@ -3,14 +3,15 @@ name: Rspec test for gem
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.event.pull_request.number && format('{0}-pr-{1}', github.workflow, github.event.pull_request.number) || format('{0}-{1}', github.workflow, github.sha) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 on:
   push:
     branches:
       - 'main'
-    paths-ignore:
-      - 'AGENTS_USER_GUIDE.md'
-      - 'llms.txt'
-      - 'llms-full.txt'
+    # Always trigger on main; docs-only detection handles skipping heavy jobs
   pull_request:
     paths-ignore:
       - '**.md'
@@ -85,13 +86,16 @@ jobs:
       - id: set-matrix
         run: |
           # Determine if we should run full matrix (main or full-ci label)
+          # Each Ruby version / dependency level is split into two shards:
+          #   generators – spec/react_on_rails/generators (heavy filesystem I/O)
+          #   unit       – everything else under spec/react_on_rails
           if [[ "${{ github.ref }}" == "refs/heads/main" ]] || \
              [[ "${{ needs.detect-changes.outputs.has_full_ci_label }}" == "true" ]]; then
-            # Full matrix: test both latest and minimum supported versions
-            echo 'matrix={"include":[{"ruby-version":"3.4","dependency-level":"latest"},{"ruby-version":"3.2","dependency-level":"minimum"}]}' >> $GITHUB_OUTPUT
+            # Full matrix: test both latest and minimum supported versions × 2 shards
+            echo 'matrix={"include":[{"ruby-version":"3.4","dependency-level":"latest","shard":"generators"},{"ruby-version":"3.4","dependency-level":"latest","shard":"unit"},{"ruby-version":"3.2","dependency-level":"minimum","shard":"generators"},{"ruby-version":"3.2","dependency-level":"minimum","shard":"unit"}]}' >> $GITHUB_OUTPUT
           else
-            # PR matrix: test only latest versions for fast feedback
-            echo 'matrix={"include":[{"ruby-version":"3.4","dependency-level":"latest"}]}' >> $GITHUB_OUTPUT
+            # PR matrix: test only latest versions for fast feedback × 2 shards
+            echo 'matrix={"include":[{"ruby-version":"3.4","dependency-level":"latest","shard":"generators"},{"ruby-version":"3.4","dependency-level":"latest","shard":"unit"}]}' >> $GITHUB_OUTPUT
           fi
 
   rspec-package-tests:
@@ -151,14 +155,22 @@ jobs:
         run: |
           echo "CI_DEPENDENCY_LEVEL=${{ matrix.dependency-level }}" >> $GITHUB_ENV
       - name: Run rspec tests
-        run: cd react_on_rails && bundle exec rspec spec/react_on_rails
+        env:
+          SHARD: ${{ matrix.shard }}
+        run: |
+          cd react_on_rails
+          if [[ "$SHARD" = "generators" ]]; then
+            bundle exec rspec spec/react_on_rails/generators
+          else
+            bundle exec rspec spec/react_on_rails --exclude-pattern "**/generators/**"
+          fi
       - name: Store test results
         uses: actions/upload-artifact@v4
         with:
-          name: main-rspec-${{ github.run_id }}-${{ github.job }}-ruby${{ matrix.ruby-version }}-${{ matrix.dependency-level }}
+          name: main-rspec-${{ github.run_id }}-${{ github.job }}-ruby${{ matrix.ruby-version }}-${{ matrix.dependency-level }}-${{ matrix.shard }}
           path: ~/rspec
       - name: Store artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: main-test-log-${{ github.run_id }}-${{ github.job }}-ruby${{ matrix.ruby-version }}-${{ matrix.dependency-level }}
+          name: main-test-log-${{ github.run_id }}-${{ github.job }}-ruby${{ matrix.ruby-version }}-${{ matrix.dependency-level }}-${{ matrix.shard }}
           path: log/test.log

.github/workflows/integration-tests.yml

@@ -3,14 +3,15 @@ name: Integration Tests
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.event.pull_request.number && format('{0}-pr-{1}', github.workflow, github.event.pull_request.number) || format('{0}-{1}', github.workflow, github.sha) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 on:
   push:
     branches:
       - 'main'
-    paths-ignore:
-      - 'AGENTS_USER_GUIDE.md'
-      - 'llms.txt'
-      - 'llms-full.txt'
+    # Always trigger on main; docs-only detection handles skipping heavy jobs
   pull_request:
     paths-ignore:
       - '**.md'

.github/workflows/lint-js-and-ruby.yml

@@ -7,10 +7,7 @@ on:
   push:
     branches:
       - 'main'
-    paths-ignore:
-      - 'AGENTS_USER_GUIDE.md'
-      - 'llms.txt'
-      - 'llms-full.txt'
+    # Always trigger on main; docs-only detection handles skipping heavy jobs
   pull_request:
     paths-ignore:
       - '**.md'

.github/workflows/package-js-tests.yml

@@ -7,10 +7,7 @@ on:
   push:
     branches:
       - 'main'
-    paths-ignore:
-      - 'AGENTS_USER_GUIDE.md'
-      - 'llms.txt'
-      - 'llms-full.txt'
+    # Always trigger on main; docs-only detection handles skipping heavy jobs
   pull_request:
     paths-ignore:
       - '**.md'

.github/workflows/playwright.yml

@@ -3,13 +3,14 @@ name: Playwright E2E Tests
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.event.pull_request.number && format('{0}-pr-{1}', github.workflow, github.event.pull_request.number) || format('{0}-{1}', github.workflow, github.sha) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 on:
   push:
     branches: [main]
-    paths-ignore:
-      - 'AGENTS_USER_GUIDE.md'
-      - 'llms.txt'
-      - 'llms-full.txt'
+    # Always trigger on main; docs-only detection handles skipping heavy jobs
   workflow_dispatch:
 
 jobs: