Co-authored-by: Alexey Romanov <[email protected]>

* Remove orphaned docs/guides/advanced/README.md

This navigation index file was left behind after the reorganization in #1845.
The links it contained point to files now in core-concepts/, making this
index redundant.

Cleanup after PR #1845.

* Create introduction.md and remove redundant overview

- Add docs/introduction.md as unified homepage
  - Explains what React on Rails is and why to use it
  - Clear when to use / when not to use decision guide
  - Three clear paths: Quick Start, Installation, Tutorial
  - Built from actual docs (overview, doctrine, system requirements)
  - Added community stat (thousands of production sites)

- Delete docs/core-concepts/react-on-rails-overview.md
  - Content consolidated into introduction.md
  - Outdated prerequisites (Rails >=5 vs current Rails 7+)
  - Creates confusion with two similar entry points

- Update links to overview.md:
  - docs/home.md: Overview → Introduction
  - docs/misc/doctrine.md: Overview → Introduction

Solves Problem 1.2 (Multiple Conflicting Entry Points) from docs improvement plan.
Next: Handle remaining entry point files (home.md, README.md, getting-started.md).

* Simplify docs/README.md and enhance introduction.md

- Simplify docs/README.md for GitHub users:
  - Direct users to website first
  - Keep valuable learning paths from PR #1813
  - Keep popular use cases table
  - Add documentation categories overview
  - Remove duplicate content (now in introduction.md)
  - Reduced from 173 lines to 65 lines

- Enhance introduction.md:
  - Add missing react_on_rails_demo_ssr_hmr example repo
  - Now has all 3 example repos (spec/dummy, demo SSR/HMR, live reactrails.com)

Purpose: docs/README.md serves GitHub users browsing repo structure,
while introduction.md serves as website homepage. Different audiences,
minimal duplication.

* Update ia-redesign-live.md with Phase 3 progress

Document completion of entry point consolidation work:
- Created introduction.md
- Deleted overview.md
- Simplified docs/README.md
- Updated folder structure to reflect changes

Next: Delete home.md, handle getting-started.md

* Delete docs/home.md - replaced by introduction.md

- Was the current website homepage (29 lines of links)
- All valuable content already in introduction.md or README.md
- No unique content lost (example repos, use cases, help links all covered)
- Replaced by introduction.md as new website homepage

Updated ia-redesign-live.md to reflect completion.

Next: Extract content from getting-started.md then delete it.

* Transform getting-started.md into understanding-react-on-rails.md

Transform docs/getting-started.md (253 lines) into a focused conceptual
guide: docs/getting-started/understanding-react-on-rails.md (238 lines).

Changes:
- Removed redundant sections (Choose Starting Point, System Requirements, More Reading)
- Transformed installation section into brief conceptual overview with links
- Kept and refined: Basic Usage, Auto-Bundling, Render-Functions, Error Handling
- Added clear 'Next Steps' section with organized learning paths
- Updated link in quick-start.md to point to new file
- Deleted original docs/getting-started.md

Purpose: This is now a conceptual journey guide explaining how React on Rails
works, complementing the hands-on tutorial and quick-start guides. Addresses
user feedback that tutorial was too overwhelming and mixed audiences.

Next: Website config updates (keeping for last as requested)

* Rename understanding-react-on-rails.md to using-react-on-rails.md

Rationale:
- "understanding" is vague and confusing next to how-react-on-rails-works.md
- "using" clearly indicates practical usage guide
- Better distinction: how-react-on-rails-works.md (architecture) vs using-react-on-rails.md (practical usage)

Changes:
- Renamed docs/getting-started/understanding-react-on-rails.md → using-react-on-rails.md
- Updated link in quick-start.md
- Updated references in ia-redesign-live.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Improve tutorial: extract Heroku deployment, fix versions, reorganize structure

Changes to tutorial.md:
1. Replaced Heroku deployment section (139 lines) with brief Deployment section linking to deployment guides
2. Updated versions: Ruby 2.7 → 3.0+, Rails 5.1.3 → 7.0+, RoR v13 → v16
3. Clarified Redux usage: tutorial demonstrates Redux, but basic installer uses Hooks (user choice)
4. Merged duplicate HMR sections into one cohesive section using ./bin/dev
5. Renamed "Other features" → "Going Further" with better organization:
   - Server Rendering (important)
   - Optional Configuration subsection (/client structure, Cloud9, RubyMine)

Changes to heroku-deployment.md:
1. Merged tutorial's detailed Heroku instructions with existing guide
2. Added note about older versions with link to current Heroku Rails 7 guide
3. Organized into clear sections: Create App, Buildpacks, Postgres, Puma, Node/Yarn, Assets, Deploy

Rationale:
- Tutorial was overwhelming with platform-specific deployment before core features
- Heroku content now in dedicated guide (reusable, maintainable)
- Clear separation: tutorial teaches React on Rails, deployment guides teach platforms
- Better progression: install → run → features → deploy → advanced

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Delete outdated manual-installation-overview.md

Rationale:
- File has been outdated since 2018 (had "TODO: Review this file" for 7 years)
- Confused purpose: title says "Manual Installation" but subtitle says "summarizes what generator does"
- Outdated content: references /client directory, webpacker, missing auto-bundling
- No clear use case: rails generate react_on_rails:install IS the manual installation (not external CLI like create-react-app)
- Content is better covered in:
  - how-react-on-rails-works.md (architecture)
  - using-react-on-rails.md (usage)
  - Generator source code (what files are created)

Changes:
- Deleted docs/advanced-topics/manual-installation-overview.md
- Removed link in installation-into-an-existing-rails-app.md
- Updated ia-redesign-live.md tracker

Decision discussed with team in Slack. Can be reverted if use case is identified.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Update IA redesign plan to reflect Phase 3 completion

Mark Phase 3 as completed with notes on what actually happened vs what was planned:
- ✅ Created introduction.md (as planned)
- ✅ Transformed getting-started.md → using-react-on-rails.md (adapted from original plan)
- ✅ Simplified README.md (kept, not deleted)
- ✅ Deleted home.md (as planned)
- ✅ Added tutorial improvements (discovered during work)
- ✅ Deleted manual-installation-overview.md (discovered during work)
- ✅ Updated cross-references manually (not scripted)

Updated testing checklist to show what's complete and what's deferred to Phase 1.

* linting

* Fix MDX parsing error in quick-start.md

Escape <head> tag in prose to prevent MDX from expecting closing tag.
Changed "in the <head>:" to "in the `<head>` section:" to use inline code.

This fixes gatsby-plugin-mdx compilation error:
"Expected a closing tag for <head> before the end of paragraph"

* Fix documentation H1 headings for improved search indexing

Add missing H1 headings and improve H1 quality across 10 documentation
files to enable proper Algolia search indexing and improve accessibility.

Critical fixes (missing H1):
- configuration.md: Add "React on Rails Configuration Options"
- react-on-rails-pro.md: Change H2 to H1
- rails-engine-integration.md: Add "Integrating React on Rails with Rails Engines"
- troubleshooting-when-using-webpacker.md: Add H1 and fix structure
- troubleshooting-when-using-shakapacker.md: Add H1 and fix heading hierarchy
- credits.md: Add "React on Rails Credits and Authors"

Quality improvements (better searchability):
- images.md: "Images" → "Configuring Images and Assets with Webpack"
- foreman-issues.md: "Foreman Issues" → "Troubleshooting Foreman with React on Rails"
- updating-dependencies.md: "Updating Dependencies" → "Updating Ruby and JavaScript Dependencies"
- api-reference/README.md: "API Reference" → "React on Rails API Reference Guide"

Why: Algolia indexes H1 as primary title. Files without H1 show as
"Untitled" in search results. Generic H1s reduce searchability.

Reference: docs/planning/docs-improvement/h1-headings-audit-report.md
(local file, not tracked)

* Fix multiple H1 headings in documentation for improved search indexing

Continue fixing H1 heading issues by addressing files with multiple H1s.
Demoted duplicate H1s to H2 throughout documentation while maintaining
proper heading hierarchy (H1→H2→H3→H4).

Files changed:
- tutorial.md: Demoted 6 H1s (Table of Contents, Installation, HMR, Deployment, Going Further, Conclusion)
- rails-engine-integration.md: Changed "Github Issues" H1 to H2
- hmr-and-hot-reloading-with-the-webpack-dev-server.md: Fixed 2 H1s with proper hierarchy
- i18n.md: "Notes" H1 to H2
- react-and-redux.md: "Redux Reducers" H1 to H2
- react-router.md: "Server Rendering Using React Router V4" H1 to H2
- rspec-configuration.md: 2 H1s to H2s
- generator-details.md: "Understanding the Organization..." H1 to H2
- redux-store-api.md: "More Details" H1 to H2
- view-helpers-api.md: "More details" H1 to H2
- style.md: "Git Usage" H1 to H2

Rationale: Multiple H1s per document confuse Algolia search ranking,
screen readers, and violate accessibility standards. Each document
should have exactly one H1 as the main title.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Restructure turbolinks.md to clarify Turbo vs legacy Turbolinks

Reorganize turbolinks.md content to clearly separate modern Turbo
(recommended) from legacy Turbolinks support. All Turbolinks v2 and v5
content is now properly nested under "Legacy Turbolinks Support" section.

Key structural changes:
- "Using Turbo" section remains at H2 level (modern, recommended approach)
- Created "Legacy Turbolinks Support" H2 section with clear deprecation notice
- Nested all Turbolinks content as H3-H5 subsections:
  - Why Turbolinks? (H3)
  - Requirements and "Why Not" sections (H3)
  - Installation details with checklists (H3→H4→H5)
  - Turbolinks 5 Specific Information (H3)
  - Technical Details and Troubleshooting (H3→H4)

Content improvements:
- Added explicit support status for Turbolinks 5.x and 2.x
- Clarified auto-detection behavior for legacy versions
- Moved CSRF/MIME type technical details under proper troubleshooting section
- Updated messaging from "may be outdated" to "still supported, migrate when possible"

Rationale: Based on codebase investigation (pageLifecycle.ts, turbolinksUtils.ts),
Turbo is the recommended navigation system since 2021. All Turbolinks versions
are legacy but still supported. Original flat structure mixed modern and legacy
content without clear distinction, potentially confusing users about which system
to use.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Modernize generator and project structure documentation

This commit updates documentation that was 9.5 years outdated, removing
references to directory structures and patterns that haven't existed since
2016 and replacing them with accurate modern (2025) guidance.

## Changes to docs/api-reference/generator-details.md

- Replace outdated structure description with accurate modern organization
- Document both non-Redux and Redux generator structures separately
- Add visual directory trees showing actual generated code locations
- Document previously undocumented --typescript option
- Remove references to non-existent app/lib folder (removed Apr 2016)
- Remove incorrect path app/javascript/app/bundles (never existed - was docs typo)
- Add auto-bundling explanation with cross-reference
- Show real component structure: src/ComponentName/ror_components/

## Changes to docs/building-features/react-router.md

- Update path reference from legacy client/app/bundles to modern src/ structure
- Clarify this example applies to --redux generator option
- Make path reference generic rather than specific to outdated structure

## Changes to docs/getting-started/project-structure.md

Complete rewrite to reflect modern React on Rails:

### Removed outdated content:
- Old bundles/ structure presented as current (was 2015-2016 pattern)
- "Moving node_modules to /client" section (tested and proven broken with Shakapacker)
- References to /client/app/assets directory (generator stopped creating in Apr 2016)
- Outdated CSS/assets management discussion

### Added modern content:
- Modern auto-bundling structure as recommended approach
- Traditional manual structure as legacy option with clear use cases
- Decision guide for choosing between approaches
- CSS Modules documentation (default in generator since modern versions)
- Real code examples from actual generator templates
- Rails Asset Pipeline as alternative approach
- Advanced global styles pattern

## Historical Context

Research revealed:
- Oct 2015: Generator created client/app/lib/middlewares/ and client/app/bundles/
- Apr 5, 2016: Docs added describing app/lib folder
- Apr 23, 2016: Generator removed these directories (18 days later!)
- Apr 2016 - Oct 2025: Docs never updated - outdated for 9.5 years

## Testing Performed

Created test app at /home/ihab/ihab/work/shakacode/test/default-structure-test/:
- Verified default generator creates src/ structure, not bundles/
- Verified CSS modules co-located with components
- Tested /client conversion: works perfectly (just move + config change)
- Tested moving node_modules to /client: FAILS with Shakapacker
- Confirmed SHAKAPACKER_CONFIG env var doesn't solve the issue

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Update React Router documentation and spec/dummy to v6

This major update modernizes React Router integration from outdated v4/v5
to current v6 API, fixing critical gaps discovered through testing.

Documentation Changes (docs/building-features/react-router.md):
- Remove 5-year-old "needs updating" warning
- Pin React Router to v6 (^6.0.0) with explanation about v7 incompatibility
- Add critical "Rails Routes Configuration" section with wildcard routing
- Update all code examples to React Router v6 API:
  * Switch → Routes
  * component prop → element prop
  * StaticRouter import from 'react-router-dom/server'
- Add path matching guidance (React Router paths must match Rails routes)
- Update Turbolinks → Turbo/Turbolinks with Rails version context
- Improve clarity: generator doesn't create React Router code
- Add installation instructions and compatibility notes

spec/dummy Updates (v5→v6 migration):
- client/app/routes/routes.jsx: Add Routes wrapper, wildcard path support
- client/app/components/RouterLayout.jsx: Switch→Routes, use relative paths
- client/app/startup/RouterApp.server.jsx: Update StaticRouter import location
- package.json: Upgrade react-router-dom from ^5.2.0 to ^6.0.0
- yarn.lock: Update dependencies (@remix-run/[email protected])

Key Discoveries from Testing:
1. React Router v7 merged with Remix, incompatible with our SSR approach
2. Rails wildcard routing is CRITICAL but was never documented
3. Documentation examples were 9+ years misleading about generator output
4. StaticRouter import location changed in v6 (breaks without this update)

Testing:
- Created fresh test app following documentation step-by-step
- Validated client-side routing, SSR, direct URL visits, browser navigation
- Confirmed spec/dummy React Router demo works with v6 API

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Modernize process manager documentation

Replace outdated foreman-issues.md with comprehensive process-managers.md guide.

Changes:
- Create docs/building-features/process-managers.md with modern guidance
  - Documents both Overmind (recommended) and Foreman
  - Explains why React on Rails needs multiple processes
  - Includes authoritative explanation from Foreman's wiki about not bundling
  - Shows how bin/dev works under the hood
- Move docs/building-features/foreman-issues.md to docs/outdated/
  - Preserves 2017-era bug reports for historical reference
  - Removes clutter from main docs (outdated/ filtered from navigation)
- Update lib/react_on_rails/dev/process_manager.rb
  - Change link from our old doc to official Foreman wiki
  - Users get explanation directly from authoritative source

Addresses feedback that foreman-issues.md was outdated and didn't mention
modern alternatives like Overmind (which bin/dev actually prefers).

* Move outdated code-splitting.md to outdated/ and update references

The code-splitting.md file was explicitly marked as "(Outdated)" and
directed users to contact [email protected] instead of following it.
The modern solution is React on Rails Pro's loadable-components guide.

Changes:
- Moved docs/building-features/code-splitting.md → docs/outdated/code-splitting.md
- Updated API reference to point to Pro loadable-components (appropriate for reference docs)
- Removed outdated code-splitting links from beginner guides (quick-start, using-react-on-rails)
- Updated planning doc to track the move

Rationale:
- File content from 2017 for React Router v3/v4 with ExecJS
- Uses deprecated patterns (manual renderer functions, webpack v1)
- Example uses abandoned react-s3-uploader package
- Pro's loadable-components doc (updated Sept 2022) provides modern approach
- Uses @loadable/component (React team's official recommendation)
- Both docs solve the same problem: code splitting WITH SSR
- Outdated doc itself says to contact Justin about loadable-components

Decision: Keep Pro feature out of beginner docs to avoid confusion about
whether Pro is required. Only mention in API reference where advanced
users look for specific features.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix broken links to outdated/webpack.md

Two user-facing docs were linking to docs/outdated/webpack.md which is
excluded from the website, causing 404 errors.

Changes:
- docs/core-concepts/webpack-configuration.md: Updated to link to Shakapacker's
  webpack customization docs (most relevant for users customizing webpack)
- docs/deployment/troubleshooting-build-errors.md: Updated to link to our own
  webpack-configuration.md (keeps users in our documentation)

Context:
webpack.md was moved to outdated/ in commit e08f91d (Oct 3, 2025) because
it contained "outdated Webpack v2 content". The file references Webpack v2
patterns and links to a 2017 forum post. These two links were not updated
when the file was moved, causing broken references.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Remove outdated documentation folder

The docs/outdated/ folder contained deprecated content that was excluded from
the website build. This content is preserved in git history and can be
accessed through previous commits if needed.

Deleted files:
- docs/outdated/code-splitting.md
- docs/outdated/converting-from-custom-webpack-config-to-rails-webpacker-config.md
- docs/outdated/deferred-rendering.md
- docs/outdated/foreman-issues.md
- docs/outdated/rails-assets-relative-paths.md
- docs/outdated/rails-assets.md
- docs/outdated/rails3.md
- docs/outdated/tips-for-usage-with-sp6.md
- docs/outdated/upgrade-webpacker-v3-to-v4.md
- docs/outdated/webpack-v1-notes.md
- docs/outdated/webpack.md

This cleanup follows the recommendation to rely on git history rather than
maintaining hidden documentation in the main branch.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix failing RSpec test after process manager docs update

Updated test expectation to match the new Foreman documentation link.

In commit 6cc93c7, we updated lib/react_on_rails/dev/process_manager.rb
to link to Foreman's official wiki instead of our outdated foreman-issues.md.
The test was still expecting the old link pattern.

Change:
- Old expectation: /foreman-issues\.md/
- New expectation: /Don't-Bundle-Foreman/

This matches the new error message which now points to:
https://github.com/ddollar/foreman/wiki/Don't-Bundle-Foreman

Fixes the failing spec:
ReactOnRails::Dev::ProcessManager.show_process_manager_installation_help
displays helpful error message with installation instructions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix broken markdown links to turbolinks.md

Updated two broken links in react-router.md that were pointing to the old
location ../rails/turbolinks.md which no longer exists.

The turbolinks.md file was moved from docs/rails/ to docs/building-features/
during the PR #1845 documentation reorganization, but these links were not
updated at that time.

Changes:
- ../rails/turbolinks.md → ./turbolinks.md (same directory)

This fixes the markdown-link-check CI failure:
ERROR: 1 dead link found in docs/building-features/react-router.md !
[✖] ../rails/turbolinks.md → Status: 400

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Enable React Router v7 future flags to silence warnings in tests

Added future flags to BrowserRouter in the dummy app to enable v7-compatible
behavior and eliminate console warnings that were causing test failures.

Changes:
- spec/dummy/client/app/startup/RouterApp.client.jsx: Added future prop with
  v7_startTransition and v7_relativeSplatPath flags

Why this fixes the issue:
The dummy app integration tests were failing because selenium_logger.rb treats
JavaScript console warnings as errors. React Router v6 emits warnings about
upcoming v7 changes:

  ⚠️ React Router Future Flag Warning: React Router will begin wrapping state
  updates in React.startTransition in v7. You can use the v7_startTransition
  future flag to opt-in early.

  ⚠️ React Router Future Flag Warning: Relative route resolution within Splat
  routes is changing in v7. You can use the v7_relativeSplatPath future flag
  to opt-in early.

By enabling these flags, we:
1. Silence the warnings
2. Adopt v7-compatible behavior early
3. Demonstrate best practices for React Router v6 users
4. Align with React Router's official migration guide

Reference: https://reactrouter.com/upgrading/future

Fixes test failures:
- React Router when rendering /react_router is expected to have text "Woohoo..."
- React Router when rendering /react_router clicking links correctly renders...

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix documentation issues identified in PR review

Addresses valid issues from Claude's PR review:

1. Fixed JavaScript syntax error in using-react-on-rails.md:192
   - Changed semicolon to comma in object destructuring example
   - Was accidentally introduced during linting commit

2. Clarified Rails version requirements in tutorial.md
   - Changed "We support Rails 6 and later" to "This tutorial targets Rails 7.0+"
   - Explicitly noted Rails 6 is supported but tutorial uses Rails 7
   - Removed version confusion between prerequisites and tutorial steps

3. Fixed markdownlint issues
   - Added language hint to code fence in using-react-on-rails.md (text)
   - Added language hint to Procfile code fence in heroku-deployment.md (procfile)

These changes ensure code examples are syntactically correct and version
requirements are clear for users following the tutorial.

* typo

* Remove redundant api-reference/README.md

This category index file was an orphaned remnant from PR #1813 that used
a different navigation approach with category landing pages.

During the IA redesign (PR #1845), similar category index files like
guides/advanced/README.md were deleted as "redundant" because docs/README.md
now serves as the single navigation hub.

The api-reference/README.md survived by accident and is now the only category
with such an index file, creating inconsistency.

Changes:
- Deleted docs/api-reference/README.md (7-line TOC)
- Updated docs/README.md reference to point directly to view-helpers-api.md
  (the main API reference file)
- Preserves existing folder-level link on line 50 that points to api-reference/

Rationale: Category folders don't need README indexes when the main docs hub
already provides navigation. This matches the pattern established when we
deleted guides/advanced/README.md.

* fix dead link

* another dead link

* Update Node.js requirement from 18+/16 to 20+ across documentation

Fixes Node version inconsistencies identified by CodeRabbit in PR #1860.

Changes:
- docs/introduction.md: 18+ → 20+
- docs/getting-started/quick-start.md: 18+ → 20+
- docs/deployment/heroku-deployment.md: 16.19.0 → 20.0.0

Rationale:
- React on Rails v16 requires Node 20+ for ESM module support
- Node 16 reached EOL in September 2023
- Node 18 reaches EOL in April 2025
- CI currently tests only Node 20 and 22
- Release notes specify Node 20.19.0+ or 22.12.0+ required

The tutorial.md (line 7) says "Updated for React on Rails v16" and
users following it would use Node 20+, so deployment guide should
match to avoid confusion.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix broken React Router v6 migration guide link

The link was returning 404. Updated from the incorrect path:
- /en/main/upgrading/v5 (broken)
to the working path:
- /docs/en/v6/upgrading/v5 (verified working)

This link was added in commit 391281a when updating React Router
documentation to v6. The URL structure changed on reactrouter.com.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix inconsistent link text in how-to-conditionally-server-render doc

Update link display text from 'here in docs/basics/configuration.md' to 'available here' to match the actual URL path (docs/api-reference/configuration/)

Co-authored-by: Ihab Adham <[email protected]>

* Document Turbo integration and immediate_hydration feature (resolve TODO)

Replace TODO from PR #1620 with comprehensive Turbo documentation covering
both free (Turbo Frames) and Pro (Turbo Streams) features.

Changes:

1. **New "Using Turbo" Section**
   - Installation steps (turbo-rails gem + @hotwired/turbo-rails package)
   - Basic configuration (ReactOnRails.setOptions({ turbo: true }))
   - Turbo Frames usage (free, works out of the box)
   - Turbo Streams usage (requires immediate_hydration: true - Pro feature)
   - Complete working example with turbo_frame_tag and turbo_stream.update
   - Links to v16.0 release notes, streaming docs, and spec/dummy example

2. **Migration Context**
   - Note about force_load → immediate_hydration rename in v16.0
   - Clear distinction between free vs Pro features
   - Explanation of WHY Turbo Streams need immediate_hydration
     (they don't dispatch turbo:render events, directly manipulate DOM)

3. **Improved Async Scripts Warning**
   - Replaced confusing "Do not use immediate_hydration: false" warning
   - New clear warning: "Async Scripts with Turbolinks Require Pro Feature"
   - Explains the race condition problem
   - Provides three alternatives with behavioral descriptions:
     * defer (waits for full page load before hydration)
     * Upgrade to Turbo (recommended)
     * Use Pro for immediate_hydration: true

Technical Context:
- PR #1620 (Aug 2024) added force_load for Turbo Streams
- PR #1781 (Sep 2025) renamed to immediate_hydration + made Pro-only
- Feature still actively used (spec/dummy has working example)
- Default immediate_hydration: false causes race conditions with async scripts

Resolves TODO on line 16 left by Justin in PR #1620 comments.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Remove confusing "(Free)" label from Turbo Basic Setup heading

The "(Free)" label in "### Basic Setup (Free)" was confusing because:
- Appears before any mention of Pro features
- Not used elsewhere in the codebase
- Readers don't know what it's contrasting with yet
- The Pro callout box later provides sufficient contrast

Changed to simply "### Basic Setup" to match patterns used in other docs
like streaming-server-rendering.md.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix multiple H1 headings in client-vs-server-rendering.md

Changed second H1 to H2 for proper document structure:
- Line 21: "# Different Server-Side Rendering Code" → "## Different..."

Having multiple H1s in a document is problematic for:
- SEO (search engines expect one H1 per page)
- Accessibility (screen readers use heading hierarchy)
- Documentation systems (assume H1 is the page title)
- Navigation/table of contents generation

The second heading is a subtopic about techniques for having different
client/server code, so it should be H2 under the main page topic.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Ihab Adham <[email protected]>

…ndle PR (#1889)

- Moves `packages/react-on-rails/handleError.ts` to `packages/react-on-rails/src/generateRenderingErrorMessage.ts`.
- Move some utility functions from `packages/react-on-rails-pro/src/streamServerRenderedReactComponent.ts` to `packages/react-on-rails-pro/src/streamingUtils.ts`

… 'react-dom/server' in the RSC bundle (#1888)

- Moved all utility functions needed by `ReactOnRailsRSC` to separate files, so these files don't include any imports for `react-dom/server` module.
- Improved Error handling while generating RSC payload by transferring the erorr to the rails side and logging the error and the stack

…eaks (#1894)

## Key Improvements

### Architecture Changes
- **Eliminated global state**: Removed shared Redis clients and global promise
  maps that caused memory leaks and cross-request contamination
- **Lazy initialization**: Stream listening now starts only when getValue() is
  called, reducing unnecessary connections
- **Simplified promise management**: Replaced complex dual-lifecycle promise
  handling with a simple value map and promise cache
- **Single-phase stream reading**: Merged checkExistingMessages() and
  setupStreamListener() into one listenToStream() function

### Bug Fixes
- Fixed memory leaks by using Map.delete() instead of setting undefined
- Fixed race conditions in connection handling with proper promise guards
- Improved error handling and propagation throughout the module
- Fixed lastProcessedId tracking to prevent message loss
- Added proper cleanup in destroy() method

Add concurrency tests to ensure there are no memory leakage or deadlocks at react on rails and react on rails pro packages

New developers following the Getting Started guides encounter the "can't
find executable foreman" error when running ./bin/dev. This commit adds
clear documentation about this prerequisite in both the Quick Start and
Using React on Rails guides.

Changes:
- Add foreman/overmind to Prerequisites section in quick-start.md
- Add installation instructions before bin/dev command in quick-start.md
- Add note with installation info in using-react-on-rails.md
- Include links to detailed installation guides for both tools
- Emphasize global installation requirement for foreman

This improves the developer onboarding experience by surfacing this
requirement before developers encounter errors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

* Add changelog guidelines to CLAUDE.md

Following the Shakapacker PR #742 guidelines, this adds comprehensive
changelog documentation requirements to CLAUDE.md:

- Changelog entries required for user-visible changes only (features,
  bug fixes, breaking changes, deprecations, performance improvements)
- No entries needed for linting, formatting, internal refactoring, tests,
  or documentation fixes
- Format requirements: PR links, author links, consistent formatting
- Breaking changes: bold formatting with migration guide links
- Version release: update version diff links

This ensures consistent, high-quality changelog maintenance across
the project.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix changelog guidelines: PR format and automation reference

Fixes identified in code review:

1. PR link format: Changed from `[PR #123]` to `[PR 1818]` (no hash)
   - Analysis shows 165 entries without hash vs only 7 with hash
   - Aligns with actual project standard

2. Added reference to `bundle exec rake update_changelog`
   - This is the existing automation for updating version headers
   - Mentioned in CHANGELOG.md line 18 but was missing from guidelines

3. Verified file ends with newline (required per CLAUDE.md)

These changes ensure guidelines match actual usage and reference
existing automation tools.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Enhance changelog guidelines with comprehensive documentation

Following code review recommendations, this adds:

1. **Section header guidance**: Documents both standard keepachangelog.com
   headers (Added, Changed, Deprecated, Removed, Fixed, Security) and
   project-specific headers (Breaking Changes, New Features, Bug Fixes,
   Security Enhancements, API Improvements, etc.)

2. **Complete format examples**: Three real-world examples showing:
   - Simple entry format
   - Breaking change with migration guide
   - Entry with sub-bullets
   All examples verified against actual CHANGELOG.md patterns

3. **Cross-reference**: Added reference to CHANGELOG.md lines 15-18
   for contributor guidelines and keepachangelog.com format

4. **Better organization**: Restructured into subsections (Section Headers,
   Format Requirements, Entry Format Examples) for easier reference

These enhancements make the guidelines actionable and ensure consistent,
high-quality changelog entries.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Simplify changelog section to conserve space

Reduces the changelog section from ~50 lines to 5 concise bullets:
- Consolidates what to include/exclude into one line each
- Provides format example inline instead of separate section
- References CHANGELOG.md lines 15-18 for full guidelines
- Points to existing `bundle exec rake update_changelog` task
- Includes grep command to view real formatting examples

This saves space while making the guidelines more actionable by
pointing developers to existing tools and real examples rather
than duplicating information.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Add /update-changelog command for guided changelog updates

Adds comprehensive slash command based on Shakapacker's implementation
with React on Rails-specific improvements:

**New slash command**: `/update-changelog`
- Provides guided workflow for adding changelog entries
- Ensures correct formatting (no hash in PR numbers)
- Validates user-visible vs non-user-visible changes
- Handles version boundaries and beta releases
- Includes real examples from the codebase
- Documents both standard and custom section headers

**Improvements over Shakapacker version**:
- Updated PR link format (no hash symbol)
- Documents all React on Rails custom section headers
- References `bundle exec rake update_changelog` for version management
- Includes actual examples from CHANGELOG.md
- Added grep command for viewing real formatting examples

**Updated CLAUDE.md**:
- References `/update-changelog` command for guided updates
- Separates version management (rake task) from entry creation (command)
- Maintains concise 6-bullet format

This makes changelog updates consistent and reduces errors by providing
an interactive guided process with comprehensive documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix update-changelog command: remove redundancy and fix formatting

Addresses code review feedback:

1. **Removed redundant section headers**:
   - "New Features" (redundant with standard "Added")
   - "Bug Fixes" (redundant with standard "Fixed")
   - "Security Enhancements" (redundant with standard "Security")
   - "Code Improvements" (internal, not user-visible)

2. **Added "Improved" to standard headers** (used 9 times in CHANGELOG.md)

3. **Emphasized standard headers**: Updated guidance to prefer standard
   keepachangelog.com headers and use custom ones sparingly

4. **Fixed broken markdown formatting**:
   - Corrected triple/quadruple backtick issues in Breaking Change example
   - Removed nested code blocks that broke rendering
   - Simplified code examples within the markdown example

5. **Final header list**:
   - Standard: Added, Changed, Deprecated, Removed, Fixed, Security, Improved
   - Custom: Breaking Changes, API Improvements, Developer Experience,
     Generator Improvements, Performance, Pro License Features

This reduces confusion and ensures the command guides developers to use
consistent, standard headers while keeping legitimate project-specific
headers for special cases.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

* Improve bin/dev kill error handling for process termination

Enhance the terminate_processes method to distinguish between ESRCH
(process already stopped) and EPERM (permission denied) errors, providing
clearer feedback to users when process termination fails.

Key improvements:
- Separate handling for ESRCH vs EPERM exceptions
- User warning when permission is denied for a process
- Clearer indication of what actually happened during process termination

This change aligns with the pattern implemented in react_on_rails-demos
PR #42 for better process management.

Fixes #1858

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Add comprehensive test coverage and edge case handling for terminate_processes

Improvements based on PR feedback:

1. Test Coverage:
   - Add 7 new test cases for terminate_processes method
   - Cover ESRCH, EPERM, ArgumentError, RangeError scenarios
   - Test mixed success/error cases

2. Edge Case Handling:
   - Handle ArgumentError (invalid signal)
   - Handle RangeError (invalid PID)
   - Consistent with file_manager.rb patterns

3. Return Value Consistency:
   - All rescue branches now explicitly return nil
   - Consistent behavior across all error types

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

* Mark React Router Sixth Page test as pending

This test is being worked on in another branch, justin808/fix-body-dup-retry, so marking it as
skipped to prevent failures in this branch.

* Update skip message for React Router Sixth Page test

Why
Reduce GitHub Actions usage and provide faster PR feedback.

Summary
Implements intelligent CI gating that skips irrelevant tests on branches
while maintaining full coverage on master. Adds local testing tools.

Key improvements
- Smart change detection skips docs-only PRs and irrelevant tests
- Reduced test matrix on PRs (latest versions) saves ~73% time
- Local CI tools (bin/ci-local, script/ci-changes-detector) test before push

Impact
Existing: PR CI runs in ~12 min instead of ~45 min for code changes
New: Contributors can validate changes locally, preventing CI failures

Risks
None. Backward compatible. Master branch retains full test coverage.

* Add lockfile version resolution for exact version checking

Similar to shakacode/shakapacker#170, this adds support for resolving
exact package versions from lockfiles (yarn.lock and package-lock.json)
when checking version compatibility between the gem and npm package.

Key improvements:
- Adds lockfile parsing to NodePackageVersion class
- Resolves exact versions from yarn.lock (v1 format)
- Resolves exact versions from package-lock.json (v1, v2, v3 formats)
- Falls back to package.json version if lockfiles are unavailable
- Prefers yarn.lock over package-lock.json when both exist
- Supports both react-on-rails and react-on-rails-pro packages

This enhancement improves version constraint checking by using the
exact resolved version from lockfiles instead of semver ranges in
package.json, making version mismatch detection more accurate.

Test coverage includes:
- Yarn.lock v1 parsing
- Package-lock.json v1 and v2 format parsing
- Pro package version resolution
- Lockfile preference order
- Fallback to package.json when no lockfile exists

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Improve lockfile parsing robustness and error handling

- Fix error handling in version_from_package_lock to safely check for
  version key existence using safe navigation operator
- Improve lockfile path construction using File.dirname instead of
  ".." for more robust path resolution
- Add ClassLength RuboCop disable for NodePackageVersion class

These changes address code review feedback to make the implementation
more robust and handle edge cases better.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix lockfile path resolution and add comprehensive edge case tests

Path Resolution Fixes:
- Fix lockfile path construction to look in same directory as package.json
- Use base_dir from node_modules_location instead of File.dirname
- Prevent resolving to filesystem root when node_modules_location is empty
- Ensure lockfiles are found next to package.json as expected

Package-lock.json v1 Fix:
- Fix dependency_data type checking (can be Hash or String in v1)
- Use is_a?(Hash) check before calling key? method

New Test Coverage:
- Similar package names (react-on-rails vs react-on-rails-pro)
- Package-lock.json v1 format parsing
- Malformed yarn.lock handling (graceful fallback)
- Malformed package-lock.json handling (graceful fallback)

The regex pattern ^"?package-name@ already ensures exact matching because
@ is the delimiter, preventing "react-on-rails" from matching
"react-on-rails-pro". Added test to verify this behavior.

All 65 tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix lockfile resolution for local paths to prevent CI failures

Problem:
- CI was failing because yarn.lock contains version "0.0.0" for local links
- The resolve_version method was checking lockfiles before detecting local paths
- This caused "0.0.0" to be returned instead of the local path from package.json

Solution:
- Check if package.json version is a local path/URL BEFORE resolving from lockfiles
- Add local_path_or_url_version? helper method
- Skip lockfile resolution for local paths since they have placeholder versions

This fixes the CI failures where spec/dummy uses "link:.yalc/react-on-rails"
and yarn.lock contains version "0.0.0" for this local link.

All 65 tests still passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

…1899)

* Add retry logic for transient HTTP errors in markdown link checker

Configure markdown-link-check to retry on transient server errors (500, 502, 503, 504)
in addition to rate limit errors (429). This prevents CI failures from flaky external
links that temporarily return 502 Bad Gateway or similar intermittent errors.

Changes:
- Increase retryCount from 3 to 5 for better resilience
- Add explicit retry configuration with 10-second delays between attempts
- Configure retries for HTTP status codes: 429, 500, 502, 503, 504

This should resolve the flaky test failures where external links like
https://github.com/shakacode/react_on_rails_demo_ssr_hmr occasionally return 502 errors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix markdown link checker to properly retry on transient errors

The previous commit added an invalid 'retry' configuration object that is not
supported by markdown-link-check, which only retries on HTTP 429 (rate limiting).

This commit implements proper retry logic by:
1. Wrapping the markdown-link-check action with Wandalen/wretry.action
2. Configuring 3 retry attempts with 10-second delays between attempts
3. Removing the unsupported 'retry' configuration object from the JSON config
4. Increasing retryCount to 5 for 429 rate limit handling

This approach will retry the entire link check operation when it fails due to
transient errors like 502 Bad Gateway, while maintaining the existing 429
retry configuration for rate limiting.

Impact on CI time: Each retry adds ~10 seconds, so worst case is +20 seconds
for a completely failing run (which would fail anyway without retries).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

* Fix Turbo navigation by updating to Turbo-compatible script tag

Changed from deprecated 'data-turbolinks-track' to modern 'data-turbo-track'
attribute with 'reload' value. Also explicitly added defer: true for clarity.

This fixes Turbo navigation issues in the dummy app.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Update Pro dummy app and docs to use modern Turbo syntax

Address inconsistencies identified in the Turbo migration by updating:

1. Pro version dummy app layout (react_on_rails_pro/spec/dummy/app/views/layouts/application.html.erb):
   - Change 'data-turbolinks-track': true to 'data-turbo-track': 'reload'
   - Ensures consistency with main dummy app which was already updated

2. Documentation (docs/building-features/turbolinks.md):
   - Clarify Turbolinks 5.x vs 2.x syntax differences
   - Add note pointing users to modern Turbo syntax
   - Improve readability of legacy Turbolinks section

These changes complete the Turbo migration across all dummy apps and provide
clearer guidance for users on the recommended modern approach.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

* Fix bin/dev pack generation failure when run from Bundler context

When bin/dev runs in a Bundler context, calling `bundle exec rake` can fail
or cause issues. This change detects when we're already inside a Bundler
context and runs the Rake task directly instead of shelling out.

Key improvements:
- Detects Bundler context and runs tasks directly
- Falls back to bundle exec when not in Bundler context
- Properly handles silent mode for both execution paths
- Loads Rails environment when needed

This fixes pack generation failures when using bin/dev.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Add rails_available? check to prevent nil Rails.application

The previous implementation didn't check if Rails.application was available
before calling load_tasks, which caused test failures. This adds the
rails_available? method to check if Rails is properly initialized.

Also updates run_rake_task_directly to use task.reenable for better
re-execution support.

Fixes RSpec test failures in pack_generator_spec.rb

* Improve pack generator robustness and error handling

Based on code review feedback, this commit addresses several critical issues:

1. **Better Bundler context detection**: Now checks ENV['BUNDLE_GEMFILE']
   for more robust detection of meaningful Bundler contexts

2. **Enhanced Rails availability checking**: Safely verifies Rails.application
   can actually load tasks, with proper error handling

3. **Consistent error handling**: Errors are always written to stderr,
   even in silent mode. Backtrace included when DEBUG env var is set

4. **Reduced code complexity**: Refactored run_rake_task_directly into
   smaller, focused methods (load_rake_tasks, prepare_rake_task,
   capture_output, handle_rake_error) to satisfy RuboCop complexity checks

5. **Maintained test compatibility**: Tests continue to pass because the
   code properly falls back to bundle exec in test environment where
   BUNDLE_GEMFILE is not set

These changes ensure:
- Tests work correctly (they mock system calls which are used in test env)
- Production bin/dev usage is optimized (direct Rake execution when safe)
- Error messages are never silently swallowed
- More robust detection of execution context

---------

Co-authored-by: Claude <[email protected]>

Update system calls in lib/react_on_rails/dev/pack_generator.rb to use
the safer array form instead of string form for better security and
cross-platform compatibility.

Changes:
- Convert string-based system calls to array form
- Update output redirection to use File::NULL with out:/err: options
- Update corresponding RSpec tests to match new system call signatures

This prevents potential shell injection issues and improves
cross-platform compatibility.

Fixes #1910

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Upgrade Shakapacker to 9.0.0 with minimal changes (#1904)

Why
Enable Shakapacker 9.0 features while maintaining full backward
compatibility with existing React on Rails applications.

Summary
Upgraded from Shakapacker 8.2.0 to 9.0.0, configured Babel transpiler
for compatibility, added precompile hook support, and resolved CI issues.

Key improvements
- Configured Babel instead of default SWC for PropTypes compatibility
- Added bin/shakapacker-precompile-hook for ReScript and pack generation
- Fixed CSS Modules to use default exports (backward compatible)

Impact
Existing: No code changes required, maintains all current functionality
New: Access to Shakapacker 9.0 features and precompile hook system

Risks
None. Babel configuration ensures compatibility with existing code.

…1913)

This fixes an error that occurs when running `rake shakapacker:install`
on a fresh Rails application. The validation was introduced in commit
0d87ea7 and runs during Rails initialization via an `after_initialize`
hook.

The problem: `shakapacker:install` needs to load the Rails environment
before it can create package.json, but the version validation runs
during environment loading and fails because package.json doesn't exist yet.

The fix: Skip validation if package.json doesn't exist yet. This allows
installation tasks to complete successfully while still validating
versions on normal Rails application startup.

This issue was reported in CI logs where `rake shakapacker:install`
would fail with "package.json file not found" error.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

#1918)

* Fix CI failure by skipping version validation during generator runtime

The strict version validation added in #1881 runs during Rails initialization
via an after_initialize hook. However, when running `rails generate react_on_rails:install`,
the npm packages haven't been installed yet, causing the validation to fail with:
"No React on Rails npm package is installed."

This fix adds a check to skip validation when running Rails generators (detected by
checking if ARGV.first is "generate" or "g"). The generator will install packages
during its execution, so validation at initialization time is not appropriate.

This allows CI to successfully run example generation tasks without errors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Address code review feedback: improve validation skip logic

Improvements based on code review:

1. **Nil-safe ARGV check**: Use safe navigation operator and check for empty ARGV
   - Prevents errors when ARGV is empty or nil
   - More defensive against edge cases

2. **Refactored to extract methods**: Created testable class methods
   - skip_version_validation?() - main entry point
   - running_generator?() - checks if running Rails generator
   - package_json_missing?() - checks if package.json exists
   - Improves testability and code clarity

3. **Added debug logging**: Log when validation is skipped
   - "Skipping validation - package.json not found"
   - "Skipping validation during generator runtime"
   - Helps debugging and understanding behavior

4. **Optimized check order**: Check package.json existence first
   - File existence check is cheaper than ARGV inspection
   - Handles more cases (initial setup, generators, etc.)

5. **Comprehensive test coverage**: Added 15 test cases
   - Tests for package.json missing scenarios
   - Tests for generator detection (both "generate" and "g")
   - Tests for edge cases (empty ARGV, other commands)
   - Tests for each helper method

All tests passing, RuboCop clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix NoMethodError: call Engine.skip_version_validation? as class method

The initializer block context doesn't have direct access to class methods.
Changed from `skip_version_validation?` to `Engine.skip_version_validation?`
to properly call the class method.

Fixes error:
NoMethodError: undefined method `skip_version_validation?' for #<ReactOnRails::Engine>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

### Summary

#2121 missed some changes in scripts and docs.

### Pull Request checklist

- [ ] ~Add/update test to cover these changes~
- [x] Update documentation
- [ ] ~Update CHANGELOG file~


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Chores**
* Migrated documentation and developer workflows from Yarn to PNPM
across install, build, test, lint, publish, workspace, and CI guidance.
* Updated examples, checklists, verification steps, and lockfile
references to reflect PNPM or package-manager-agnostic instructions.
* Removed a legacy optional preinstall orchestration step and aligned
scripts and setup guidance with the PNPM workflow.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Alexey Romanov <[email protected]>
Co-authored-by: Claude Opus 4.5 <[email protected]>

## Summary

Fixes intermittent CI failures in the `markdown-link-check` job caused
by `https://npmjs.com/` returning 403 Forbidden.

The existing exclude pattern only matched URLs with `www.`:
```
^https://www\.npmjs\.(org|com)
```

But `docs/getting-started/tutorial.md` links to `https://npmjs.com/`
(without `www`), which wasn't excluded.

## Changes

Updated the pattern to make `www.` optional:
```
^https://(www\.)?npmjs\.(org|com)
```

## Test plan

- [x] Pattern syntax is valid regex
- [x] CI `markdown-link-check` job should pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Chores**
* Updated configuration to exclude additional npmjs URL variants from
link checking.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Claude Opus 4.5 <[email protected]>

- Add required YAML frontmatter (name, description) to pr-testing-agent.md
- Move pr-testing-guide.md to .claude/docs/ (documentation, not an agent)
- Replace markdown links with plain file paths per subagent best practices
- Add "Additional Context" section pointing to files the agent can read
- Update cross-references for new file locations
- Remove reference to non-existent code-reviewer agent

The agent was originally created as documentation (PR #2109) and later
moved to .claude/agents/ (PR #2112) without the required frontmatter.
This aligns it with Claude Code subagent specifications.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

…2239)

## Summary

- Moved configuration documentation files from `docs/api-reference/` to
`docs/configuration/`
- Configuration docs are not API reference - they document how to
configure React on Rails
- Creates a dedicated folder for better organization

## Changes

- Moved `configuration.md`, `configuration-pro.md`,
`configuration-deprecated.md` to `docs/configuration/`
- Updated all internal documentation links (9 files)
- Updated generator template references
- Updated spec/dummy initializer file references
- Updated CHANGELOG reference
- Updated docs README to list Configuration as a separate category

## Test plan

- [ ] Verify all documentation links work correctly
- [ ] Check that the new folder structure renders properly on the
documentation website

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Reorganized Configuration documentation into its own dedicated
section, separating it from the API Reference.
* Updated all documentation links to reference the new Configuration
location.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

## Summary

Adds a custom Claude Code slash command (`/address-review`) that fetches
GitHub PR review comments and creates a todo list to address them.

## Features

- Accepts full PR URLs or just PR numbers
- Supports specific review comments (`#pullrequestreview-...`)
- Supports specific issue comments (`#issuecomment-...`)
- Creates organized todo list with file paths, line numbers, and
reviewer names
- Automatically replies to comments after addressing them to close the
feedback loop

## Usage

```
/address-review 12345
/address-review https://github.com/org/repo/pull/12345
/address-review https://github.com/org/repo/pull/12345#pullrequestreview-123456789
/address-review https://github.com/org/repo/pull/12345#issuecomment-123456789
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Introduced a comprehensive guide for an automated workflow to manage
GitHub PR review comments. The workflow converts comments into
actionable todo lists with support for multiple PR reference formats,
intelligent filtering to exclude non-actionable items, error handling
for edge cases, and GitHub API integration for seamless comment
management and responses.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <[email protected]>

After PR #1841 split JS Pro code into a separate package, Pro documentation
was not updated. Users following these docs encountered the "Cannot mix
react-on-rails (core) with react-on-rails-pro" error.

Changes:
- Fix 19 incorrect imports across 5 RSC/code-splitting docs
- Add client package installation section to installation.md
- Add import migration guide to updating.md with troubleshooting
- Clarify import requirements in LICENSING_FAQ.md
- Fix broken link to RSC tutorial in installation.md
- Exclude yourmechanic.com from link checker (blocks bots)

Fixes #2249

## Summary

Format all 21 Pro documentation files with Prettier and fix documentation issues.

### Changes
- **Prettier formatting**: Applied consistent formatting to all Pro docs (first time since monorepo merger in Sept 2025)
- **Fixed Prettier bug corruption**: `RENDERER_PORT` was mangled to `RENDERER*PORT` due to [Prettier issue #4362](prettier/prettier#4362) - wrapped in backticks to prevent
- **Fixed typos**: "automaticaly" → "automatically", "we you open the noder-renderer" → "when you open the node-renderer"
- **Fixed grammar**: "Ruby only" → "Ruby-only" (compound adjective hyphenation)
- **Fixed capitalization**: "Github" → "GitHub"
- **Removed vague TODO**: Unhelpful `(*TODO: Need to check on this*)` removed from heroku.md

### Files Changed
- 21 Pro docs formatted with Prettier
- 4 docs with content fixes (bundle-caching.md, heroku.md, profiling-server-side-rendering-code.md, style.md)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

…#2256)

Add `main` field to `react-on-rails-pro` and `react-on-rails-pro-node-renderer` package.json files for compatibility with legacy module resolvers.

## Problem
ESLint import resolvers like `eslint-import-resolver-node` use the `resolve` npm package, which doesn't support Node.js conditional exports. This caused false positive "Unable to resolve path to module" errors even though imports worked at runtime.

## Solution
Add the `main` field pointing to the default export:
- `react-on-rails-pro`: `lib/ReactOnRails.full.js`
- `react-on-rails-pro-node-renderer`: `lib/ReactOnRailsProNodeRenderer.js`

This matches the approach used in the open-source `react-on-rails` package and provides backward compatibility without affecting modern tools that use `exports`.

## Testing
- ✅ Clean install passes
- ✅ Build succeeds
- ✅ yalc publish works
- ✅ ESLint import resolver resolves modules correctly

Fixes #2255

…ndencies (#2261)

Address 58 Dependabot security vulnerabilities in dev/test dependencies.

Key fixes:
- Ruby: activestorage (critical), rack (5 high CVEs), nokogiri (critical),
  rexml, puma, net-imap
- JS: webpack (critical XSS/cross-realm), webpack-dev-server (source theft),
  jws/jsonwebtoken (HMAC bypass)

Changes:
- Pin Rails to ~> 7.1.0 in OS dev Gemfile (stays on 7.1.6, avoids 7.2 breaking changes)
- Upgrade webpack-dev-server 4→5 (no security fix in 4.x line)
- Update all affected Gemfile.lock and pnpm-lock.yaml files

All changes are dev/test dependencies only — production gem code unchanged.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

#2259)

## Summary

Fixes race conditions in `ReactOnRailsPro::Request` connection
management:

- **Lazy initialization race**: `@connection ||= create_connection` is
not atomic - multiple threads could create duplicate connections at
startup
- **Mutex creation race**: Even `@mutex ||= Mutex.new` has a race, so we
use a constant `CONNECTION_MUTEX` instead
- **Exception safety**: Create new connection before closing old one

## Solution

Uses the **double-checked locking pattern**:

```ruby
CONNECTION_MUTEX = Mutex.new

def connection
  conn = @connection
  return conn if conn  # Fast path: lock-free

  CONNECTION_MUTEX.synchronize do
    @connection ||= create_connection  # Slow path: only once per process
  end
end
```

### Performance characteristics

| Scenario | Behavior |
|----------|----------|
| Steady state (99.99% of calls) | Lock-free pointer read |
| Initialization | Single mutex acquisition per worker |
| Reset | Mutex-protected, creates before closing |

## Why this approach?

Alternatives considered:
- `Concurrent::AtomicReference`: Lock-free but wastes connections at
startup (all racing threads create one, N-1 discarded)
- `Concurrent::Map`: Equivalent behavior but adds dependency and
complexity for a single value

The Mutex + double-checked locking is optimal because:
- Only 1 connection created at startup (vs N with AtomicReference)
- Lock-free after initialization
- No external dependencies (`concurrent-ruby` not in gemspec)
- Simple and well-understood pattern

## Test plan

- [ ] Existing tests pass
- [ ] Manual verification in multi-threaded environment

Closes #2258

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Refactor**
* Improved internal connection management for more reliable, thread-safe
lazy initialization and atomic swaps during concurrent access and
resets.

* **Tests**
* Added concurrency-focused tests to ensure single initialization under
race conditions, safe resets while in use, proper replacement/closure of
connections, and graceful handling of close errors.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

### Summary

Consolidated the CHANGELOG entries from beta versions into single
16.2.0.rc.0 release sections for both open-source and Pro changelogs.
This matches the new release candidate tagged on December 29, 2025.

**Open-source CHANGELOG.md:**
- Consolidated 16.2.0.beta.19 and 16.2.0.beta.20 into 16.2.0.rc.0
- Added new entries for PRs 2259, 2256, 2261, 2233

**Pro react_on_rails_pro/CHANGELOG.md:**
- Renamed v16.2.0.beta.13 section to v16.2.0.rc.0
- Added Legacy Module Resolver Compatibility fix (PR 2256)
- Updated version links

### Pull Request checklist

- [x] Update CHANGELOG file
- ~[ ] Add/update test to cover these changes~
- ~[ ] Update documentation~

### Other Information

New user-visible entries in 16.2.0.rc.0:
- **Thread-Safe Connection Management (Pro)** - Fixed race conditions
(PR 2259)
- **Legacy Module Resolver Compatibility (Pro)** - Added main field for
legacy resolvers (PR 2256)
- **Development Dependencies Security** - 58 Dependabot vulnerabilities
fixed (PR 2261)
- **React Server Components CVE Fixes** - Upgraded React to v19.0.3 (PR
2233)

---------

Co-authored-by: Claude Haiku 4.5 <[email protected]>

The tag `v16.1.1` does not exist - only `16.1.1` exists (without `v` prefix).

PR #2262 accidentally changed `16.1.1` to `v16.1.1` in the compare links when
consolidating beta versions into the rc.0 release.

Fixes:
- CHANGELOG.md: `v16.1.1...v16.2.0.rc.0` → `16.1.1...v16.2.0.rc.0`
- react_on_rails_pro/CHANGELOG.md: same fix

🤖 Generated with [Claude Code](https://claude.com/claude-code)

### Summary

Security alerts are now enabled, configure Dependabot to only do
security upgrades (for now at least).

### Pull Request checklist

- [ ] ~Add/update test to cover these changes~
- [ ] ~Update documentation~
- [ ] ~Update CHANGELOG file~


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Chores**
* Enabled weekly, security-only Dependabot updates for npm, Bundler, and
GitHub Actions; disabled non-security PRs, set a 3-day cooldown, added
grouped security and CI labels, and scoped updates by directory/group.
* **Documentation**
* Added monorepo merger guidance with configuration update steps,
Dependabot configuration examples (pre/post), and a "When to update
dependabot" operational section.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Alexey Romanov <[email protected]>

## Summary

- Removes references to `config.license_token` which doesn't exist in
the codebase
- Replaces with correct config file method
(`config/react_on_rails_pro_license.key`)
- Adds link to LICENSE_SETUP.md for complete instructions

## Background

The `config.license_token` option was incorrectly documented in PR #1901
but was never actually implemented in PR #1857. The LicenseValidator
only supports two methods:

1. **Environment variable**: `REACT_ON_RAILS_PRO_LICENSE`
2. **Config file**: `config/react_on_rails_pro_license.key`

There is no `license_token` attribute in the
`ReactOnRailsPro::Configuration` class.

## Files Changed

- `react_on_rails_pro/docs/installation.md` - Fixed license
configuration section
- `react_on_rails_pro/docs/updating.md` - Fixed license configuration
section

## Test Plan

- [x] Verified the config file method matches what LICENSE_SETUP.md
documents
- [x] Verified `config.license_token` does not exist in the codebase

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* License configuration now uses file-based setup instead of environment
variables.
  * New license key file requires .gitignore configuration.
  * Comprehensive setup guidance available in LICENSE_SETUP.md.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Claude Opus 4.5 <[email protected]>

## Summary
- Upgrade webpack-cli from v4 to v6.0.1 (required for webpack-dev-server
v5)
- Remove @webpack-cli/serve (now bundled in webpack-cli v5+)
- Remove deprecated `https: false` from shakapacker.yml configs

## Test plan
- [x] `pnpm install` succeeds in all dummy apps
- [ ] CI passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

## Problem

When `immediate_hydration` is enabled and HTML streams on slow networks,
a race condition can cause JSON parse errors:

```
SyntaxError: Unterminated string in JSON at position XXXXX
```

**Root cause:** The props `<script>` element exists in the DOM before
its content is fully received. If the JS bundle executes during this
window, `el.textContent` returns truncated JSON.

## Solution

Filter immediate hydration elements to only process those with a
`nextSibling`. The immediate hydration script is always rendered right
after the props script:

```html
<script class="js-react-on-rails-component">{"props":...}</script>
<script>ReactOnRails.reactOnRailsComponentLoaded('App');</script>
```

If `nextSibling` exists, the props script's `</script>` was parsed →
content is complete.
If `nextSibling` is null, skip the element → it will hydrate when its
inline script executes.

## Testing

Added `StreamingRaceSimulator` middleware that splits props script
content with a delay, reliably reproducing the race condition. E2E test
verifies hydration succeeds even under race condition.

Fixes #2283

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Fixed a JSON parse race condition during HTML streaming that could
affect immediate component hydration, ensuring more reliable prop
parsing and component initialization.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

### Summary

Updated CHANGELOG.md to document v16.2.0.rc.1 release with two bug fixes
that address streaming and build compatibility issues since rc.0.

### Pull Request checklist

- [x] Update CHANGELOG file

### Changes

- **JSON Parse Race Condition Fix** (PR #2290): Fixed race condition in
`immediate_hydration` that could cause JSON parse errors when HTML
streams on slow networks.
- **webpack-cli Compatibility Fix** (PR #2291): Fixed compatibility
issue with webpack-dev-server v5 by upgrading webpack-cli and removing
deprecated configurations.

Co-authored-by: Claude Haiku 4.5 <[email protected]>

## Summary

- Add `bin/mise-exec` wrapper script to ensure commands use mise-managed
tool versions
- Update `.rubocop.yml` to exclude the shell script from linting
- Document Conductor compatibility in `CLAUDE.md`

## Problem

Conductor (and other non-interactive shells) don't source `.zshrc`, so
mise's shell hook that reorders PATH based on `.tool-versions` never
runs. This causes commands to use system Ruby/Node instead of the
project-specified versions.

**Symptoms:**
- `ruby --version` returns system Ruby (e.g., 2.6.10) instead of project
Ruby (3.3.4)
- Pre-commit hooks fail with wrong tool versions
- `bundle` commands fail due to incompatible Ruby versions

## Solution

The `bin/mise-exec` wrapper explicitly invokes mise to ensure correct
tool versions:

```bash
bin/mise-exec ruby --version       # Uses .tool-versions Ruby
bin/mise-exec bundle exec rubocop  # Correct Ruby for linting
bin/mise-exec pnpm install         # Uses .tool-versions Node
```

## Related

- Mirrors implementation from
[react_on_rails-demos#106](shakacode/react_on_rails-demos#106)
- See
[react_on_rails-demos#105](shakacode/react_on_rails-demos#105)
for detailed problem analysis

## Test plan

- [x] Verify `bin/mise-exec ruby --version` returns mise-managed Ruby
(3.3.4)
- [x] Verify `bin/mise-exec bundle exec rubocop` runs successfully
- [x] Verify pre-commit hooks pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <[email protected]>

## Summary

- Detect and support multiple version managers: mise, asdf, or direct
PATH (rbenv/nvm/nodenv)
- Use `bin/mise-exec` wrapper automatically when mise is detected
- Fall back to direct commands for other version managers
- Keep `conductor.json` scripts simple with no version manager
requirement

## How it works

The setup script now:
1. Checks for mise first → uses `bin/mise-exec` wrapper for all commands
2. Falls back to asdf → sources asdf.sh to configure PATH
3. Falls back to direct commands → assumes rbenv/nvm/nodenv or system
tools are in PATH

## Related

Follows up on [PR
#2301](#2301) which
added the `bin/mise-exec` wrapper.

## Test plan

- [x] Verify setup script detects mise and uses bin/mise-exec
- [x] Verify setup script falls back to asdf when available
- [x] Verify setup script works with direct PATH when no manager
detected
- [ ] Test workspace setup in Conductor with mise (requires manual
testing)
- [ ] Test workspace setup in Conductor with asdf (requires manual
testing)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Setup now auto-detects multiple version managers and routes tool
invocations through a manager-aware wrapper.
* Environment files (.env, .env.local) are copied automatically during
setup.
  * Added a “Key commands”/help section with updated usage guidance.

* **Bug Fixes**
* Wrapper now falls back to running commands directly when the helper is
unavailable.
* Clearer runtime version checks and upgrade guidance, plus a final tip
for correct tool resolution.

* **Chores**
* Test, lint and run commands updated to use the manager-aware wrapper.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

…2295)

## Summary

Fixes the intermittent "Could not find component registered with name
<component name>" error that occurs during hydration.

### The Problem

When `document.readyState === 'interactive'`, deferred scripts may still
be executing. The previous check `document.readyState !== 'loading'`
would trigger hydration in the `interactive` state, potentially before
component registration scripts had finished executing. This caused a
race condition where:

1. `pageLifecycle.ts` detects `readyState === 'interactive'` and
proceeds with hydration
2. Component bundle scripts are still executing
3. Hydration tries to find the component before `ReactOnRails.register({
Component })` has been called
4. Error: "Could not find component registered with name <component
name>"

### The Fix

Changed the condition from `document.readyState !== 'loading'` to
`document.readyState === 'complete'` to ensure all deferred scripts have
finished executing before hydration begins.

**Note:** ReactOnRailsPro handles this differently - it immediately
hydrates components as soon as their HTML and bundle are loaded, making
it resilient against this type of race condition.

## Test Plan

- [x] Updated existing test to verify `interactive` state now waits for
`DOMContentLoaded`
- [ ] Run `pnpm test` to verify all tests pass
- [ ] Manual testing with the dummy app to confirm the error no longer
occurs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

Fixed pre-commit hooks not catching linting errors in root-level files.
The glob patterns like `**/*.rb` only match files in subdirectories.
Updated to use `{*.ext,**/*.ext}` format to match files at all directory
levels.

## Testing

- Verified RuboCop now catches errors in root-level `.rb` files
- Verified Prettier now catches formatting errors in root-level `.md`
and `.yml` files
- Pre-commit hook now runs successfully on staged files in any directory

## Pull Request checklist

- [x] Testing completed locally
- [ ] Add/update test to cover these changes (not
applicable—configuration-only)
- [ ] Update documentation (not applicable—configuration-only)
- [ ] Update CHANGELOG file (not applicable—tooling fix)

## Summary

- Consolidates 16.2.0.rc.0 and 16.2.0.rc.1 changelog entries into a
single `### [16.2.0] - 2026-01-14` section
- Adds missing PR #2295 fix for "component not registered" error
- Removes all beta/RC version headers and version comparison links
- Updates version links at the bottom of the file

## Changes Made

1. **Version header**: Changed `### [16.2.0.rc.1]` to `### [16.2.0] -
2026-01-14`
2. **RC section removal**: Removed the separate `### [16.2.0.rc.0]`
header and its "Changes since..." line
3. **New entry**: Added PR #2295 (Component Registration fix) to the
Fixed section
4. **Version links**: Updated `[unreleased]` and `[16.2.0]` comparison
links, removed RC links

## Test plan

- [x] Verify no RC/beta version headers remain
- [x] Verify version links are correct at bottom of file
- [x] Verify file ends with newline
- [x] Pre-commit hooks pass (Prettier, trailing newlines)

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Co-authored-by: Claude Opus 4.5 <[email protected]>

## Summary

- Merged two duplicate `#### Fixed` sections in the 16.2.0 release into
one
- Reordered all sections to put **Breaking Changes first** (most
critical for upgrading users)
- Updated `/update-changelog` command to document and enforce the
preferred section order

## New Preferred Section Order

1. **Breaking Changes** (FIRST - most critical for upgrading)
2. Added
3. Changed
4. Improved
5. Fixed
6. Deprecated
7. Removed
8. Security

**Rationale:** Users upgrading need to see breaking changes immediately
so they know if their code will break before exploring new features.

## Context

The 16.2.0 release had two issues:
1. Two separate `#### Fixed` headers (now merged into one)
2. Breaking Changes buried at the bottom (now moved to top)

## Test plan

- [x] Verified correct changelog structure: Breaking Changes → Added →
Changed → Improved → Fixed → Security
- [x] Verified file ends with newline
- [x] Updated `/update-changelog` command documentation
- [x] Passed pre-commit hooks (Prettier)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Reorganized changelog guidelines with a preferred section order for
future entries, including clearer guidance on Breaking Changes, Added,
Changed, Improved, Fixed, Deprecated, Removed, and Security sections.
* Restructured existing changelog entries to align with the new
organization standards.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

## Summary
- Fix bug in `publish_gem_with_retry` that caused NameError when gem
publish failed
- Rake's `sh` method raises `RuntimeError`, not `Gem::CommandException`
(which doesn't exist)

## Background
During the 16.2.0 release, when the `react_on_rails_pro` gem publish
failed due to an expired OTP code, the release script crashed with:

```
NameError: uninitialized constant Gem::CommandException (NameError)
```

This prevented the retry logic from working properly.

## Test plan
- [x] Verified with `bundle exec rubocop` - no offenses

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Chores**
* Improved error handling for the gem publishing retry flow to account
for an additional exception type.
* Added logging of error class and message when publish attempts fail,
providing clearer diagnostics during retries.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>