diff --git a/.claude/docs/analysis/CI_FAILURES_2024-11-21.md b/.claude/docs/analysis/CI_FAILURES_2024-11-21.md
new file mode 100644
index 0000000000..01fa1f8af4
--- /dev/null
+++ b/.claude/docs/analysis/CI_FAILURES_2024-11-21.md
@@ -0,0 +1,523 @@
+# CI Failure Analysis - Branch justin808/monorepo-completion
+
+**Date**: 2025-11-21
+**PR**: #2069
+**Analyst**: Claude Code Review
+**Status**: 🔴 NOT READY TO MERGE - Multiple Test Failures
+
+---
+
+## ⚠️ CRITICAL DISCLAIMER
+
+**This analysis contains UNTESTED hypotheses only.**
+
+**Environment**: Analysis performed in Conductor isolated workspace with limited capabilities:
+
+- ❌ Cannot run full Rails application
+- ❌ Cannot execute integration tests
+- ❌ Cannot test webpack build pipeline
+- ❌ Cannot verify fixes against actual failing tests
+- ✅ Can analyze CI logs and source code
+- ✅ Can identify suspicious commits
+- ✅ Can provide reproduction steps
+
+**What this means**:
+
+- All "fixes" below are **hypotheses that MUST be tested locally**
+- Do NOT assume any proposed fix will work without verification
+- All investigation is based on log analysis and code inspection only
+- Actual root causes may differ from analysis after local testing
+
+**Before implementing any fix**: Test it locally in the actual React on Rails repository first.
+
+---
+
+## Executive Summary
+
+**All tests PASSED on merge base** (`5e033c716` - v16.2.0.beta.12) ✅
+**Current Status**: 3 test suites FAILING, 1 test suite HUNG (80+ minutes)
+
+This is a **REGRESSION** introduced by changes in this branch related to:
+
+1. Monorepo restructuring (Phase 5: Pro Node Renderer extraction)
+2. `buildConsoleReplay` parameter order fix
+3. Workspace dependency changes
+
+---
+
+## Failing Test Suites
+
+### 1. Integration Tests - JavaScript Asset Loading ❌
+
+**Configurations**: Both `minimum` (Ruby 3.2, Node 20) and `latest` (Ruby 3.4, Node 22)
+**Duration**: Failed after 2m26s - 2m36s
+**Failed Examples**: 21 failures
+
+#### Error Pattern
+
+```text
+Uncaught SyntaxError: Unexpected token '<'
+```
+
+At line numbers: 167, 199, 211, 226, 239, 253, 267, 274 in HTML pages
+
+#### Root Cause Analysis
+
+JavaScript files returning HTML (404 pages) instead of JavaScript code. The browser attempts to execute HTML as JavaScript, causing syntax errors.
+
+**Evidence**:
+
+- ✅ Webpack bundles restored from cache successfully
+- ✅ `yarn install` completes without errors
+- ✅ Some webpack files load correctly (e.g., `/webpack/test/js/890.js`)
+- ❌ Most component-specific bundles fail to load
+
+**What This Means**:
+The webpack infrastructure partially works, but specific bundles aren't being generated or served correctly. This suggests:
+
+1. Build artifacts may not be created during `yarn install` (prepare scripts)
+2. Asset paths may be incorrect after monorepo restructuring
+3. Rails may be looking for bundles in the wrong location
+
+#### Sample Failing Tests
+
+```text
+Pages/Index when rendering All in one page
+  with Server Rendered/Cached React/Redux Component
+    ✗ is expected to have visible css "div#ReduxApp-react-component-0"
+    ✗ changes name in message according to input
+  with Server Rendered/Cached React Component Without Redux
+    ✗ is expected to have visible css "div#HelloWorld-react-component-1"
+    ✗ changes name in message according to input
+  with Simple Client Rendered Component
+    ✗ is expected to have visible css "div#HelloWorldApp-react-component-2"
+    ✗ changes name in message according to input
+```
+
+**Total Impact**: All React component rendering tests fail
+
+---
+
+### 2. Pro Node Renderer Tests - Console Replay Format ❌
+
+**Configuration**: Ruby 3.3.7
+**Duration**: Failed after 4m58s
+**Failed Examples**: 1 failure
+
+#### Error Details
+
+```ruby
+Failure/Error: expect(script_line).to eq(expected_line)
+
+  expected: "console.log.apply(console, [\"[SERVER] RENDERED ReduxSharedStoreApp to dom node with id: ReduxSharedStoreApp-react-component-0\"]);"
+       got: "<script id=\"consoleReplayLog\">"
+```
+
+**Test File**: `react_on_rails_pro/spec/dummy/spec/requests/renderer_console_logging_spec.rb:52`
+
+#### Root Cause Analysis
+
+The test uses Nokogiri to extract text content from `<script id="consoleReplayLog">` tags:
+
+```ruby
+script_nodes = html_nodes.css("script#consoleReplayLog")
+script_text = script_nodes.map(&:text).join("\n")
+script_lines = script_text.split("\n")
+```
+
+**Expected behavior**: `script_lines[0]` should be the first console statement
+**Actual behavior**: `script_lines[0]` is `"<script id=\"consoleReplayLog\">"`
+
+**Possible Causes**:
+
+1. HTML structure changed - Nokogiri not finding the correct nodes
+2. buildConsoleReplay output format changed
+3. Node renderer not correctly processing console replay
+4. Test parsing logic broken
+
+#### Related Changes
+
+Commit `09f8c27cb` - "Fix buildConsoleReplay parameter order":
+
+- Changed signature: `(consoleHistory, messages)` → `(messages, consoleHistory, nonce)`
+- Updated Pro call site in `streamingUtils.ts`
+- May have inadvertently changed output format
+
+---
+
+### 3. Pro Package JS Tests - HUNG ⏳
+
+**Configuration**: Ubuntu 22.04, Node.js, Redis 6.2.6
+**Status**: Running for 80+ minutes (normal: 1-3 minutes)
+**Command**: `yarn workspace react-on-rails-pro-node-renderer run ci`
+
+#### Test Configuration
+
+```yaml
+services:
+  redis:
+    image: cimg/redis:6.2.6
+    ports:
+      - 6379:6379
+```
+
+**Jest Command**: `jest --ci --runInBand --reporters=default --reporters=jest-junit`
+
+#### Possible Causes
+
+1. **Test waiting for timeout** - Infinite loop or stuck async operation
+2. **Redis connection issue** - Tests hanging on Redis operations
+3. **Missing build artifacts** - Tests can't import required modules
+4. **Jest configuration** - `--runInBand` runs serially; one hung test blocks all
+
+**Note**: Logs unavailable while test is running
+
+#### Recommendation
+
+🛑 **CANCEL CI RUN** - it's wasting resources after 80 minutes
+
+---
+
+## Suspicious Commits
+
+### High Priority Suspects
+
+#### 1. `09f8c27cb` - Fix buildConsoleReplay parameter order ⚠️
+
+**When**: 3 hours ago
+**Changes**:
+
+- Fixed parameter order in `buildConsoleReplay()`
+- Updated Pro package call in `streamingUtils.ts`
+
+**Why Suspicious**:
+
+- **Directly related** to Pro Node Renderer console replay test failure
+- Changed function signature and all call sites
+- May have changed output format
+
+**Code Changes**:
+
+```typescript
+// Before
+buildConsoleReplay(consoleHistory, previouslyReplayedConsoleMessages);
+
+// After
+buildConsoleReplay(previouslyReplayedConsoleMessages, consoleHistory, nonce);
+```
+
+---
+
+#### 2. `c124df6c0` - Fix workspace dependencies and build scripts ⚠️⚠️
+
+**When**: 2 hours ago
+**Changes**:
+
+- Modified `package-scripts.yml` paths
+- Changed prepare scripts in package.json files
+- Added conditional: `"prepare": "[ -f lib/ReactOnRails.full.js ] || yarn run build"`
+
+**Why Suspicious**:
+
+- **Most likely cause** of integration test asset failures
+- Changed how/when packages are built
+- Modified critical infrastructure code
+
+**Files Changed**:
+
+```text
+package-scripts.yml (path updates)
+packages/react-on-rails-pro-node-renderer/package.json
+packages/react-on-rails-pro/package.json
+packages/react-on-rails/package.json
+```
+
+---
+
+#### 3. `002d07423` - Update react_on_rails_pro build paths ⚠️
+
+**Why Suspicious**:
+
+- Updated Pro package build paths after node-renderer extraction
+- Could have broken asset path resolution
+- Related to monorepo restructuring
+
+---
+
+### Medium Priority Suspects
+
+- `6ae74c2b8` - Phase 5: Add Pro Node Renderer Package to workspace
+- `83b21f217` - Fix node-renderer package.json and knip configuration
+- `82021be66` - Remove invalid exports from react_on_rails_pro/package.json
+- `e7befce71` - don't use yalc in a yarn workspace
+
+---
+
+## What Still Works ✅
+
+**22 checks passing**:
+
+- ✅ Linting (JS and Ruby)
+- ✅ Markdown link checks
+- ✅ RSpec gem specs
+- ✅ Package tests (non-Pro)
+- ✅ Examples generation
+- ✅ Build processes
+- ✅ Pro lint
+- ✅ Dummy app webpack bundle building
+
+**Local verification**:
+
+- ✅ `packages/react-on-rails/lib/` contains all built files
+- ✅ `buildConsoleReplay.js` has correct function signature
+- ✅ TypeScript compilation successful
+
+**CI verification**:
+
+- ✅ Webpack bundles cached and restored
+- ✅ Node modules installed successfully
+- ✅ Bundles present in `spec/dummy/public/webpack`
+
+---
+
+## Debugging Strategy
+
+### Step 1: Reproduce Locally
+
+From `.claude/docs/testing-build-scripts.md`:
+
+```bash
+# Test clean install (CRITICAL)
+rm -rf node_modules packages/*/lib
+yarn install --frozen-lockfile
+
+# Verify build artifacts created
+ls -la packages/react-on-rails/lib/ReactOnRails.full.js
+ls -la packages/react-on-rails-pro/lib/ReactOnRails.full.js
+ls -la packages/react-on-rails-pro-node-renderer/lib/ReactOnRailsProNodeRenderer.js
+
+# Test prepare scripts
+yarn nps build.prepack
+
+# Test yalc publish
+yarn run yalc:publish
+
+# Run failing integration tests
+cd spec/dummy
+bundle exec rspec spec/system/integration_spec.rb
+
+# Run failing Pro tests
+cd react_on_rails_pro/spec/dummy
+bundle exec rspec spec/requests/renderer_console_logging_spec.rb
+
+# Test hung Pro JS tests
+cd packages/react-on-rails-pro-node-renderer
+timeout 5m yarn run ci
+```
+
+### Step 2: Compare with Base Commit
+
+```bash
+# Checkout base commit
+git checkout 5e033c716
+
+# Run same tests
+cd spec/dummy
+bundle exec rspec spec/system/integration_spec.rb
+
+# Note differences in:
+# - Generated HTML
+# - Asset paths
+# - Console replay output
+# - Webpack bundle locations
+```
+
+### Step 3: Bisect Breaking Commit
+
+```bash
+# Binary search through 52 commits
+git bisect start
+git bisect bad HEAD
+git bisect good 5e033c716
+
+# For each bisect step:
+yarn install --frozen-lockfile
+cd spec/dummy
+bundle exec rspec spec/system/integration_spec.rb:23
+git bisect good/bad
+```
+
+---
+
+## Fix Recommendations
+
+**⚠️ IMPORTANT: All recommendations below are UNTESTED hypotheses based on CI log analysis.**
+
+**Testing Limitation**: This analysis was performed in a Conductor isolated workspace without:
+
+- Full Rails application environment
+- Webpack build pipeline
+- Database/Redis services
+- Integration test infrastructure
+
+**All proposed fixes MUST be tested locally in the actual React on Rails repository before claiming they work.**
+
+---
+
+### Priority 1: Integration Test Asset Loading (CRITICAL) 🔥
+
+**Status**: ⚠️ UNTESTED HYPOTHESIS
+
+**Hypothesis**: Prepare scripts don't run correctly in workspace context, OR webpack output paths changed.
+
+**Investigation**:
+
+1. Check CI logs for prepare script execution during `yarn install`
+2. Verify webpack output directory matches Rails expectations
+3. Check if workspace-based builds work differently than monorepo root builds
+
+**Potential Fixes**:
+
+- Ensure prepare scripts execute during CI's `yarn install`
+- Verify all package.json "prepare" scripts are correct
+- Check if `yarn workspace` commands need different configuration
+- Restore previous package-scripts.yml paths if incorrect
+
+**Test After Fix**:
+
+```bash
+rm -rf node_modules packages/*/lib
+yarn install --frozen-lockfile
+cd spec/dummy
+bundle exec rspec spec/system/integration_spec.rb:23
+```
+
+---
+
+### Priority 2: Pro Console Replay Test 🟡
+
+**Status**: ⚠️ UNTESTED HYPOTHESIS
+
+**Hypothesis**: buildConsoleReplay parameter fix changed output format OR test HTML parsing broken.
+
+**Investigation**:
+
+1. Run test locally with verbose output
+2. Inspect actual HTML generated
+3. Check if `wrapInScriptTags` output changed
+4. Verify Nokogiri extracts text correctly
+
+**Potential Fixes**:
+
+- Update test expectations if format intentionally changed
+- Fix buildConsoleReplay if output is broken
+- Debug why Nokogiri returns tag instead of text
+
+**Test After Fix**:
+
+```bash
+cd react_on_rails_pro/spec/dummy
+bundle exec rspec spec/requests/renderer_console_logging_spec.rb:13 --format documentation
+```
+
+---
+
+### Priority 3: Hung Pro JS Tests 🟡
+
+**Status**: ⚠️ UNTESTED HYPOTHESIS
+
+**Immediate**: Cancel the 80+ minute CI run
+
+**Investigation**:
+
+```bash
+cd packages/react-on-rails-pro-node-renderer
+timeout 5m yarn run ci --verbose
+```
+
+**Potential Fixes**:
+
+- Add Jest timeout configuration
+- Check Redis connection in tests
+- Verify all imports resolve correctly
+- Add `--forceExit` flag temporarily
+- Run with `--detectOpenHandles` to find hanging promises
+
+**Test After Fix**:
+
+```bash
+yarn workspace react-on-rails-pro-node-renderer run ci
+```
+
+---
+
+## Prevention Strategies
+
+### Add CI Validation (from testing-build-scripts.md)
+
+```yaml
+# .github/workflows/validate-build.yml
+- name: Validate workspace dependencies
+  run: |
+    ! grep -r '".*": "workspace:\*"' packages/*/package.json || {
+      echo "ERROR: Use '*' not 'workspace:*' for Yarn Classic"
+      exit 1
+    }
+
+- name: Validate prepare scripts create artifacts
+  run: |
+    rm -rf node_modules packages/*/lib
+    yarn install --frozen-lockfile
+    test -f packages/react-on-rails/lib/ReactOnRails.full.js
+    test -f packages/react-on-rails-pro/lib/ReactOnRails.full.js
+    test -f packages/react-on-rails-pro-node-renderer/lib/ReactOnRailsProNodeRenderer.js
+```
+
+### Document Build Path Changes
+
+When changing directory structure:
+
+1. Update ALL path references in configuration files
+2. Search codebase: `grep -r "old/path"`
+3. Test scripts: `yarn run prepack`, `yarn run yalc.publish`
+4. Run full test suite before committing
+
+---
+
+## Timeline of Events
+
+1. **Base commit** `5e033c716` - All tests passing ✅
+2. **52 commits later** - Multiple test failures ❌
+3. **Key commit** `09f8c27cb` - buildConsoleReplay parameter order fix
+4. **Key commit** `c124df6c0` - Workspace dependencies and build scripts
+5. **Current state** - 3 failing + 1 hung test suite
+
+---
+
+## Conclusion
+
+This branch is **NOT READY TO MERGE**. The monorepo restructuring introduced regressions that need investigation and fixes:
+
+1. **JavaScript asset loading broken** - Most critical, blocks all integration tests
+2. **Console replay format issue** - Fixable, likely test expectation update needed
+3. **Hung Jest tests** - Needs local reproduction and debugging
+
+**Estimated Time to Fix**: 4-8 hours
+
+- 2-4 hours: Reproduce and debug integration test asset issue
+- 1-2 hours: Fix console replay test
+- 1-2 hours: Debug hung Jest tests
+
+**Risk Level**: Medium-High
+
+- Changes affect core infrastructure (prepare scripts, build paths)
+- Multiple interdependent failures suggest deeper architectural issue
+- Long history (52 commits) makes bisecting time-consuming
+
+**Recommendation**:
+
+1. ❌ **DO NOT MERGE** until all tests pass
+2. 🔍 Reproduce failures locally
+3. 🐛 Debug systematically using bisect or commit-by-commit review
+4. ✅ Add CI validations to prevent regression
+5. 📝 Document any intentional breaking changes
diff --git a/.claude/docs/analysis/INDEX.md b/.claude/docs/analysis/INDEX.md
new file mode 100644
index 0000000000..d50aadcbe6
--- /dev/null
+++ b/.claude/docs/analysis/INDEX.md
@@ -0,0 +1,266 @@
+# React on Rails Monorepo Migration - Analysis Index
+
+This directory contains comprehensive analysis of the React on Rails monorepo migration status and recommendations.
+
+## Documents Overview
+
+### 1. CI_FAILURES_2024-11-21.md (CURRENT BLOCKER - 24 KB) 🔴
+
+**Critical CI failure analysis for justin808/monorepo-completion branch**
+
+**Status**: NOT READY TO MERGE - 3 failing test suites, 1 hung test
+
+Contains:
+
+- Executive summary of all test failures
+- Root cause analysis for each failure
+- Comparison with base commit (all tests passing)
+- Suspicious commits that likely introduced issues
+- Detailed debugging strategy and fix recommendations
+- Prevention strategies for future regressions
+
+**Use when**: Debugging current CI failures, planning fixes, understanding what broke
+
+---
+
+### 2. MONOREPO_MIGRATION_ANALYSIS.md (PRIMARY - 16 KB)
+
+**Comprehensive technical analysis of the entire monorepo migration**
+
+Contains 12 detailed sections:
+
+- Executive summary with current phase status
+- Directory structure analysis (current vs target)
+- YALC publishing configuration review
+- Build and package scripts examination
+- Documentation status
+- Migration TODOs and issues
+- CI/CD configuration analysis
+- What's working and what needs attention
+- Critical dependencies and interactions
+- Key files to monitor
+- Detailed next steps recommendations
+- Success criteria definition
+
+**Use when**: You need complete technical details, planning next phases, or understanding dependencies
+
+### 3. MIGRATION_QUICK_REFERENCE.md (REFERENCE - 6.8 KB)
+
+**Quick lookup guide with status dashboards and checklists**
+
+Contains:
+
+- Migration phase status overview
+- Directory structure comparison table
+- YALC workflow comparison
+- Path reference guide (CRITICAL)
+- Status tables for all components
+- Testing checklists
+- Common issues and solutions
+- Key metrics
+- Next actions breakdown
+
+**Use when**: You need quick answers, status updates, or testing guidance
+
+### 4. CLAUDE_MD_UPDATES.md (SUPPORTING - 11 KB)
+
+**Documentation of CLAUDE.md improvements for monorepo**
+
+Details improvements to project guidelines including:
+
+- Monorepo-specific development instructions
+- Workspace management guidance
+- Build and testing updates
+- CI configuration notes
+
+**Use when**: Learning about updated developer guidelines
+
+### 5. claude-md-improvements.md (SUPPORTING - 8 KB)
+
+**Additional CLAUDE.md enhancement recommendations**
+
+Suggested improvements for developer experience in monorepo context.
+
+**Use when**: Reviewing documentation enhancement opportunities
+
+### 6. pr-splitting-strategy.md (STRATEGIC - 12 KB)
+
+**Strategy guide for breaking large PRs into smaller ones**
+
+Contains:
+
+- When to split a large PR (indicators and decision criteria)
+- Strategy for identifying independent commits
+- Step-by-step splitting process
+- Real-world example: How to split PR #2069
+- Benefits, anti-patterns, and decision tree
+- Template for announcing PR splits
+
+**Use when**: Facing complex CI failures in large PRs, planning PR strategy, deciding whether to split
+
+---
+
+## Related Documentation
+
+Outside the analysis directory:
+
+- **PR Splitting Strategy**: `/.claude/docs/pr-splitting-strategy.md` (splitting large PRs)
+- **Main Migration Plan**: `/docs/MONOREPO_MERGER_PLAN.md` (authoritative source)
+- **Path Management Guide**: `/.claude/docs/managing-file-paths.md` (validation procedures)
+- **Build Script Testing**: `/.claude/docs/testing-build-scripts.md` (artifact verification)
+- **CI Monitoring**: `/.claude/docs/master-health-monitoring.md` (CI status checks)
+- **Contributing Guide**: `/CONTRIBUTING.md` (developer instructions)
+
+---
+
+## Quick Navigation
+
+### I Need To...
+
+**Fix current CI failures**
+→ Read: CI_FAILURES_2024-11-21.md (MOST URGENT)
+
+**Decide whether to split a large PR**
+→ Read: pr-splitting-strategy.md (for complex PRs with multiple failures)
+
+**Understand the current state**
+→ Read: Executive Summary in MONOREPO_MIGRATION_ANALYSIS.md
+
+**Plan Phase 3 or 4 work**
+→ Read: "Recommendations for Next Steps" in MONOREPO_MIGRATION_ANALYSIS.md
+
+**Find path references to update**
+→ Read: "Build Scripts - Path Reference Guide" in MIGRATION_QUICK_REFERENCE.md
+
+**Check what's working/broken**
+→ Read: "What's Working Well" and "Critical Issues" in MONOREPO_MIGRATION_ANALYSIS.md
+
+**Run tests before committing**
+→ Read: "Testing Checklist Before Merging" in MIGRATION_QUICK_REFERENCE.md
+
+**Fix a specific issue**
+→ Read: "Common Issues & Solutions" in MIGRATION_QUICK_REFERENCE.md
+
+**Monitor file changes**
+→ Read: "Key Files to Monitor" in MONOREPO_MIGRATION_ANALYSIS.md
+
+**Setup workspace development**
+→ Read: CLAUDE_MD_UPDATES.md and claude-md-improvements.md
+
+## Key Facts at a Glance
+
+**Current Phase**: Phase 5 (Pro Node Renderer Package) - COMPLETE
+**Next Phase**: Phase 6 (Documentation & Polish)
+**Estimated Timeline**: Phases 1-5 complete, Phases 6-7 remaining
+
+**Directory Structures**:
+
+- Surabaya-v1: `packages/` workspaces (fully implemented)
+- Three packages: react-on-rails, react-on-rails-pro, react-on-rails-pro-node-renderer
+
+**Critical Risk**: Path validation for yalc publish
+
+- Past incident: 7-week silent failure (Sept 2024)
+- Prevention: Always test `yarn run yalc.publish` manually
+
+**Packages in Migration**:
+
+- 2 Ruby gems (core + pro)
+- 3 NPM packages (core + pro + pro-node-renderer)
+
+## Document Features
+
+### Color Coding in Quick Reference
+
+- ✅ Working/Complete items
+- ❌ Items needing updates
+- 🔄 In-progress items
+- ⏳ Planned items
+- ⚠️ Critical issues
+
+### Sections in Analysis
+
+- 📋 Executive summaries
+- 🏗️ Architecture details
+- ⚙️ Configuration specifics
+- 📊 Status and metrics
+- 🔍 Issues and risks
+- 📝 Recommendations
+- ✓ Checklists and criteria
+
+## Workflow Tips
+
+### Before Starting Work
+
+1. Read MIGRATION_QUICK_REFERENCE.md phase status
+2. Check "What Needs Attention" section
+3. Review relevant next steps
+
+### During Development
+
+1. Keep MIGRATION_QUICK_REFERENCE.md open for reference
+2. Use path reference guide when modifying configs
+3. Follow testing checklists before committing
+
+### Before Committing
+
+1. Verify all paths in MIGRATION_QUICK_REFERENCE.md
+2. Run testing checklist
+3. Validate build artifacts
+
+### Before Merging PR
+
+1. Confirm all tests pass
+2. Manual verification of yalc publish
+3. Documentation updates aligned
+
+## Contact & Updates
+
+These documents were generated on: 2025-11-22
+
+Updates to analysis:
+
+- Document updates based on phase completion
+- New issues/findings during implementation
+- Success criteria validation
+
+## Completed Phases
+
+**Phase 3**: ✅ Pre-Monorepo Structure Preparation (Completed)
+
+- Validated surabaya-v1 state
+- Updated all paths
+- Tested workspace commands
+
+**Phase 4**: ✅ Final Monorepo Restructuring (Completed)
+
+- Consolidated Pro package
+- Merged CI systems
+- Updated publishing process
+
+**Phase 5**: 🔴 Pro Node Renderer Package Extraction (IN PROGRESS - PR #2069 - CI FAILING)
+
+- ✅ Extracted node-renderer as separate workspace package
+- ✅ Updated build and publishing workflows
+- ❌ CI/CD integration BROKEN - 3 test failures + 1 hung test
+- **Status**: NOT READY TO MERGE - See CI_FAILURES_2024-11-21.md
+
+## Future Phases
+
+**Phase 6**: ⏳ Documentation & Polish (Planned)
+
+- Documentation consolidation
+- Developer experience improvements
+- Final polish and refinements
+
+**Phase 7**: ⏳ Post-Migration Cleanup & Deprecation (Planned)
+
+- Legacy structure removal
+- Deprecation notices
+- Migration guide finalization
+
+---
+
+Last Updated: 2025-11-22
+Status: Phase 5 IN PROGRESS - CI Failures Must Be Fixed Before Merge
+**BLOCKER**: See CI_FAILURES_2024-11-21.md for complete failure analysis
diff --git a/.claude/docs/pr-splitting-strategy.md b/.claude/docs/pr-splitting-strategy.md
new file mode 100644
index 0000000000..aa94f69f2c
--- /dev/null
+++ b/.claude/docs/pr-splitting-strategy.md
@@ -0,0 +1,473 @@
+# PR Splitting Strategy for CI Failures
+
+## When to Split a Large PR
+
+### Indicators That Splitting Makes Sense
+
+1. **Multiple Independent Test Failures**
+
+   - Different test suites failing for different reasons
+   - Failures span multiple subsystems (integration, unit, Pro package, etc.)
+   - Each failure requires significant debugging time
+
+2. **Long Git History**
+
+   - 50+ commits in the branch
+   - Multiple feature changes mixed together
+   - Hard to bisect or identify which commit broke what
+
+3. **Mixed Concerns**
+
+   - Infrastructure changes + feature changes
+   - Multiple unrelated fixes bundled together
+   - Refactoring mixed with new functionality
+
+4. **Time Investment vs. Value**
+   - Estimated fix time > 8 hours
+   - Unknown number of additional failures lurking
+   - Blocking other work that depends on parts of the PR
+
+### Example: The Monorepo Completion PR
+
+**Original PR #2069**: 52 commits, multiple failures
+
+- Integration tests failing (JavaScript asset loading)
+- Pro Node Renderer tests failing (console replay format)
+- Pro JS tests hung (80+ minutes)
+- Mix of: monorepo restructuring, buildConsoleReplay fix, workspace dependency changes
+
+**Why it's a good candidate for splitting**:
+
+- ✅ Multiple independent failures
+- ✅ 52 commits make bisecting difficult
+- ✅ Contains both infrastructure (monorepo) and bug fixes (buildConsoleReplay)
+- ✅ Some parts might work independently
+- ✅ Estimated 4-8 hours to fix all issues
+
+---
+
+## Strategy for Splitting
+
+### Step 1: Identify Independent Commits
+
+Look for commits that:
+
+- ✅ Can stand alone without dependencies
+- ✅ Have passing tests on their own
+- ✅ Provide value independently
+- ✅ Don't break existing functionality
+
+**Example groups from PR #2069**:
+
+```text
+Group 1 (Documentation & Analysis):
+- CI failure analysis documents
+- Testing requirement documentation
+- CLAUDE.md updates
+
+Group 2 (Build Console Replay Fix):
+- buildConsoleReplay parameter order fix
+- Test updates for new parameter order
+- Related Pro package updates
+
+Group 3 (Workspace Dependencies):
+- Yarn Classic workspace syntax fixes
+- Package.json prepare script updates
+- Build path updates
+
+Group 4 (Monorepo Node Renderer):
+- Extract node-renderer package
+- Update build workflows
+- CI configuration changes
+```
+
+### Step 2: Determine Merge Order
+
+**Principle**: Merge least risky changes first
+
+1. **Documentation-only changes** (safest)
+
+   - No code changes
+   - No risk of breaking tests
+   - Provides value immediately
+
+2. **Bug fixes with tests** (safe if tests pass)
+
+   - Clear, focused changes
+   - Well-tested
+   - Doesn't change infrastructure
+
+3. **Refactoring with no behavior change** (moderate risk)
+
+   - Keep tests passing
+   - No API changes
+   - Can be verified by running existing tests
+
+4. **Infrastructure changes** (highest risk)
+   - Save for last
+   - Requires most careful testing
+   - Most likely to have cascading effects
+
+### Step 3: Create Split PRs
+
+**For Each Independent Group**:
+
+1. **Create new branch from master**
+
+   ```bash
+   git checkout master
+   git pull --rebase
+   git checkout -b feature/specific-focused-change
+   ```
+
+2. **Cherry-pick relevant commits**
+
+   ```bash
+   # Pick commits for this specific feature
+   git cherry-pick <commit-hash>
+   git cherry-pick <commit-hash>
+   # etc.
+   ```
+
+3. **Test locally**
+
+   ```bash
+   # Ensure tests pass
+   bundle exec rspec
+   yarn test
+
+   # Ensure linting passes
+   bundle exec rubocop
+   yarn run lint
+   ```
+
+4. **Create focused PR**
+   ```bash
+   git push -u origin feature/specific-focused-change
+   gh pr create --title "Focused change description" --body "..."
+   ```
+
+### Step 4: Handle the Original PR
+
+#### Option A: Close and Replace
+
+- Close original PR with note: "Split into smaller PRs for easier review"
+- Link to all new PRs
+- Advantage: Clean history, easier to review
+
+#### Option B: Rebase and Reduce
+
+- Remove commits that went into other PRs
+- Rebase remaining commits
+- Update PR description
+- Advantage: Preserves PR number and discussion
+
+---
+
+## Splitting Example: PR #2069
+
+### Original PR Issues
+
+- 52 commits
+- 3 failing test suites + 1 hung
+- Mix of documentation, bug fixes, infrastructure
+- Unknown how long to fix
+
+### Proposed Split
+
+#### PR 1: Documentation & Testing Requirements (MERGE FIRST) ✅
+
+**Branch**: `docs/testing-requirements-and-ci-analysis`
+**Commits**: 2 commits
+
+- Add comprehensive CI failure analysis
+- Document testing requirements for hypothetical vs tested fixes
+
+**Why merge first**:
+
+- Zero code changes
+- No risk of breaking anything
+- Provides value to team immediately
+- Documents current state
+
+**Testing**: None needed (documentation only)
+
+---
+
+#### PR 2: Build Console Replay Parameter Order Fix
+
+**Branch**: `fix/build-console-replay-parameter-order`
+**Commits**: ~5 commits
+
+- Fix buildConsoleReplay parameter signature
+- Update all call sites (open source + Pro)
+- Update tests for new parameter order
+- Add TSDoc documentation
+
+**Why second**:
+
+- Focused bug fix
+- Clear before/after
+- Can be tested independently
+- Might fix Pro Node Renderer test failure
+
+**Testing Required**:
+
+```bash
+# Open source tests
+bundle exec rspec spec/react_on_rails/
+yarn test packages/react-on-rails/tests/buildConsoleReplay.test.js
+
+# Pro tests
+cd react_on_rails_pro/spec/dummy
+bundle exec rspec spec/requests/renderer_console_logging_spec.rb
+```
+
+**Success Criteria**: All buildConsoleReplay-related tests pass
+
+---
+
+#### PR 3: Workspace Dependencies Yarn Classic Fix
+
+**Branch**: `fix/workspace-dependencies-yarn-classic`
+**Commits**: ~3 commits
+
+- Change "workspace:_" to "_" for Yarn Classic compatibility
+- Document in testing-build-scripts.md
+- Add validation steps
+
+**Why third**:
+
+- Small, focused infrastructure fix
+- Well documented issue
+- Easy to test
+
+**Testing Required**:
+
+```bash
+rm -rf node_modules packages/*/lib
+yarn install --frozen-lockfile
+# Verify no errors about "workspace:*"
+# Verify packages built correctly
+ls packages/*/lib/
+```
+
+**Success Criteria**: Clean install works, no workspace protocol errors
+
+---
+
+#### PR 4: Monorepo Node Renderer Package (DEFER)
+
+**Branch**: `feature/monorepo-node-renderer-v2`
+**Commits**: Remaining commits
+
+- Extract node-renderer as separate package
+- Update build workflows
+- Fix integration test asset loading
+
+**Why defer**:
+
+- Most complex changes
+- Most failing tests
+- Needs significant debugging
+- Can benefit from PRs 1-3 being merged first
+
+**Before attempting**:
+
+1. Merge PRs 1-3
+2. Rebase on updated master
+3. Re-run tests to see what's still broken
+4. Debug integration test failures locally
+5. Consider further splitting if still too complex
+
+---
+
+## Benefits of This Approach
+
+### For Reviewers
+
+- ✅ Smaller PRs are easier to review thoroughly
+- ✅ Clear, focused changes
+- ✅ Less cognitive load
+- ✅ Faster review cycles
+
+### For the Codebase
+
+- ✅ Incremental progress
+- ✅ Each merge adds value
+- ✅ Easier to revert if needed
+- ✅ Better git history
+
+### For Debugging
+
+- ✅ Easier to identify which change broke what
+- ✅ Can bisect smaller ranges
+- ✅ Test failures more clearly attributed
+- ✅ Less interference between changes
+
+### For Team Velocity
+
+- ✅ Unblock parts of work sooner
+- ✅ Other work can build on merged PRs
+- ✅ Reduce risk of merge conflicts
+- ✅ Maintain momentum even with complex issues
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Don't Split Too Much
+
+**Problem**: Creating 20+ micro-PRs
+**Result**: Review fatigue, PR dependency hell
+**Better**: 3-5 focused PRs maximum
+
+### ❌ Don't Split Dependent Changes
+
+**Problem**: PR 2 needs PR 1's changes to work
+**Result**: Can't test or merge independently
+**Better**: Keep dependent changes together
+
+### ❌ Don't Leave Original PR in Limbo
+
+**Problem**: Original PR still open, new PRs also open
+**Result**: Confusion about what to review, duplicated work
+**Better**: Close original with clear migration plan
+
+### ❌ Don't Split Without Testing
+
+**Problem**: Assume split PRs will pass CI without verification
+**Result**: Multiple broken PRs instead of one
+**Better**: Test each split PR locally before creating
+
+---
+
+## Decision Tree
+
+```text
+Is PR failing CI?
+├─ YES → Continue
+└─ NO → No need to split
+
+Are there multiple independent failures?
+├─ YES → Consider splitting
+└─ NO → Fix the one failure
+
+Can failures be attributed to distinct commits/features?
+├─ YES → Good candidate for splitting
+└─ NO → May need to debug as-is
+
+Are there commits that can merge independently with value?
+├─ YES → Split those out first
+└─ NO → Fix failures in original PR
+
+Is estimated fix time > 8 hours?
+├─ YES → Strongly consider splitting
+└─ NO → May be faster to fix in place
+
+Will splitting unblock other work?
+├─ YES → Split to unblock
+└─ NO → Evaluate other factors
+```
+
+---
+
+## Template: PR Split Announcement
+
+**For closing original PR**:
+
+```markdown
+## PR Split Decision
+
+This PR has been split into smaller, more focused PRs for easier review and debugging.
+
+### Why Split?
+
+- [x] Multiple independent test failures
+- [x] 52 commits make debugging difficult
+- [x] Mix of documentation, bug fixes, and infrastructure
+- [x] Estimated 4-8 hours to fix all issues
+- [x] Some parts provide value independently
+
+### New PRs (in merge order):
+
+1. **#XXXX: Documentation & Testing Requirements** ✅ READY
+
+   - CI failure analysis
+   - Testing requirement documentation
+   - Zero risk (docs only)
+
+2. **#YYYY: Build Console Replay Parameter Fix** 🔄 IN REVIEW
+
+   - Focused bug fix
+   - All tests passing
+   - Addresses one of the three failures
+
+3. **#ZZZZ: Workspace Dependencies Fix** ⏳ DRAFT
+
+   - Yarn Classic compatibility
+   - Small infrastructure fix
+   - Easy to verify
+
+4. **#AAAA: Monorepo Node Renderer v2** 📋 PLANNED
+   - Will rebase on master after PRs 1-3 merge
+   - Re-evaluate test failures after rebase
+   - May split further if needed
+
+### Benefits:
+
+- Easier code review
+- Incremental progress
+- Can merge low-risk changes immediately
+- Better attribution if issues arise
+- Unblocks dependent work
+
+Closing this PR in favor of the focused PRs above.
+```
+
+---
+
+## Real-World Example Timeline
+
+**Week 1**:
+
+- Day 1: Identify PR #2069 has complex CI failures
+- Day 2: Analyze and document failures (this becomes PR 1)
+- Day 3: Create PR 1 (docs) - merged same day ✅
+
+**Week 2**:
+
+- Day 1: Cherry-pick buildConsoleReplay commits to PR 2
+- Day 2: Test PR 2 locally, fix issues, open for review
+- Day 3: Address review comments, merge ✅
+
+**Week 3**:
+
+- Day 1: Create PR 3 for workspace dependencies
+- Day 2: Test, merge ✅
+- Day 3: Rebase PR 4 (node renderer) on latest master
+
+**Week 4**:
+
+- Day 1-2: Debug PR 4 with PRs 1-3 merged (fewer variables)
+- Day 3: Find that integration tests now pass! Only need minor fix
+- Day 4: Merge PR 4 ✅
+
+**Total**: 4 weeks with incremental progress vs. potentially 4 weeks stuck on one PR
+
+---
+
+## Key Takeaway
+
+**Big PRs with multiple failures are a red flag, not a requirement.**
+
+When you see:
+
+- Multiple test suites failing
+- Long commit history
+- Mixed concerns
+- Uncertain fix time
+
+Ask yourself: **"Can I provide value incrementally by splitting this?"**
+
+If yes, split it. Your reviewers, your codebase, and your future self will thank you.
diff --git a/CLAUDE.md b/CLAUDE.md
index 70047aac3c..32b4a35392 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,22 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Project Structure Guidelines
+
+### Analysis Documents
+
+When creating analysis documents (deep dives, investigations, historical context):
+- **Location**: Place in `/analysis` directory
+- **Format**: Use Markdown (.md)
+- **Naming**: Use descriptive kebab-case names (e.g., `rake-task-duplicate-analysis.md`)
+- **Purpose**: Keep detailed analyses separate from top-level project files
+
+Examples:
+- `/analysis/rake-task-duplicate-analysis.md` - Historical analysis of duplicate rake task bug
+- `/analysis/feature-investigation.md` - Investigation of a specific feature or issue
+
+Top-level documentation (like README.md, CONTRIBUTING.md) should remain at the root.
+
 ## ⚠️ CRITICAL REQUIREMENTS
 
 **BEFORE EVERY COMMIT/PUSH:**
@@ -13,10 +29,46 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 These requirements are non-negotiable. CI will fail if not followed.
 
+**CRITICAL - LOCAL TESTING REQUIREMENTS:**
+
+1. **NEVER claim a test is "fixed" without running it locally first**
+   - If working in Conductor workspace or similar isolated environment, clearly state: "Cannot test locally in isolated workspace"
+   - If test requires specific environment (database, Redis, etc.), state: "Requires [X] setup not available in current environment"
+
+2. **Distinguish hypothetical fixes from confirmed fixes:**
+   - ✅ Use "This fixes..." or "Fixed" ONLY after local verification
+   - ⚠️ Use "This SHOULD fix..." or "Proposed fix (UNTESTED)" when you haven't verified
+   - 📋 Use "Analysis suggests..." or "Root cause appears to be..." for investigation without fixes
+
+3. **When analyzing CI failures:**
+   - Clearly mark all analysis as "UNTESTED - requires local reproduction" unless verified
+   - Provide exact commands to reproduce and test the fix locally
+   - State why you cannot test if applicable (workspace restrictions, missing services, etc.)
+
+4. **Prefer local testing over CI iteration:**
+   - Don't push "hopeful" fixes and wait for CI feedback
+   - Test locally first whenever technically possible
+   - Document what you tested and what results you got
+
+5. **Document your testing:**
+   - Include test commands in commit messages for complex fixes
+   - Note in PR descriptions which fixes were tested locally vs. which are hypothetical
+   - Explain any testing limitations encountered
+
+**See also**: When facing complex PRs with multiple CI failures, refer to `.claude/docs/pr-splitting-strategy.md` for guidance on splitting large PRs into smaller, more manageable pieces.
+
+---
+
 **🚀 AUTOMATIC: Git hooks are installed automatically during setup**
 
 Git hooks will automatically run linting on **all changed files (staged + unstaged + untracked)** before each commit - making it fast while preventing CI failures!
 
+Pre-commit hooks automatically run:
+- **RuboCop** (auto-fix Ruby code style)
+- **ESLint** (auto-fix JS/TS code style)
+- **Prettier** (auto-format all supported files)
+- **Trailing newline checks** (ensure all files end with newlines)
+
 **Note:** Git hooks are for React on Rails gem developers only, not for users who install the gem.
 
 ## Development Commands
@@ -27,6 +79,7 @@ Git hooks will automatically run linting on **all changed files (staged + unstag
 - **Run tests**:
   - Ruby tests: `rake run_rspec`
   - JavaScript tests: `yarn run test` or `rake js_tests`
+  - Playwright E2E tests: See Playwright section below
   - All tests: `rake` (default task runs lint and all tests except examples)
 - **Linting** (MANDATORY BEFORE EVERY COMMIT):
   - **REQUIRED**: `bundle exec rubocop` - Must pass with zero offenses
@@ -36,11 +89,220 @@ Git hooks will automatically run linting on **all changed files (staged + unstag
 - **Code Formatting**:
   - Format code with Prettier: `rake autofix`
   - Check formatting without fixing: `yarn start format.listDifferent`
-- **Build**: `yarn run build` (compiles TypeScript to JavaScript in node_package/lib)
+- **Build**: `yarn run build` (compiles TypeScript to JavaScript in packages/react-on-rails/lib)
 - **Type checking**: `yarn run type-check`
+- **RBS Type Checking**:
+  - Validate RBS signatures: `bundle exec rake rbs:validate`
+  - Run Steep type checker: `bundle exec rake rbs:steep`
+  - Run both: `bundle exec rake rbs:all`
+  - List RBS files: `bundle exec rake rbs:list`
 - **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines
 - Never run `npm` commands, only equivalent Yarn Classic ones
 
+### Replicating CI Failures Locally
+
+**CRITICAL: NEVER wait for CI to verify fixes. Always replicate failures locally first.**
+
+**When Analyzing CI Failures:**
+
+1. **First, reproduce the failure locally** using the tools below
+2. **If you cannot reproduce locally**, clearly state why:
+   - "Working in Conductor isolated workspace - cannot run full Rails app"
+   - "Requires Docker/Redis/PostgreSQL not available in current environment"
+   - "Integration tests need full webpack build pipeline not set up locally"
+3. **Mark all proposed fixes as UNTESTED** until they can be verified:
+   - ❌ DON'T: "This fixes the integration test failures"
+   - ✅ DO: "This SHOULD fix the integration test failures (UNTESTED - requires local Rails app with webpack)"
+4. **Provide reproduction steps** even if you can't execute them:
+   - Include exact commands to run
+   - Document environment requirements
+   - Explain what success looks like
+
+#### Switch Between CI Configurations
+
+The project tests against two configurations:
+- **Latest**: Ruby 3.4, Node 22, Shakapacker 9.3.0, React 19 (runs on all PRs)
+- **Minimum**: Ruby 3.2, Node 20, Shakapacker 8.2.0, React 18 (runs only on master)
+
+```bash
+# Check your current configuration
+bin/ci-switch-config status
+
+# Switch to minimum dependencies (for debugging minimum CI failures)
+bin/ci-switch-config minimum
+
+# Switch back to latest dependencies
+bin/ci-switch-config latest
+```
+
+**See `SWITCHING_CI_CONFIGS.md` for detailed usage and troubleshooting.**
+
+**See `spec/dummy/TESTING_LOCALLY.md` for local testing tips and known issues.**
+
+#### Re-run Failed CI Jobs
+
+```bash
+# Automatically detects and re-runs only the failed CI jobs
+bin/ci-rerun-failures
+
+# Search recent commits for failures (when current commit is clean/in-progress)
+bin/ci-rerun-failures --previous
+
+# Or for a specific PR number
+bin/ci-rerun-failures 1964
+```
+
+This script:
+- ✨ **Fetches actual CI failures** from GitHub using `gh` CLI
+- 🎯 **Runs only what failed** - no wasted time on passing tests
+- ⏳ **Waits for in-progress CI** - offers to poll until completion
+- 🔍 **Searches previous commits** - finds failures before your latest push
+- 📋 **Shows you exactly what will run** before executing
+- 🚀 **Maps CI jobs to local commands** automatically
+
+#### Run Only Failed Examples
+
+When RSpec tests fail, run just those specific examples:
+
+```bash
+# Copy failure output from GitHub Actions, then:
+pbpaste | bin/ci-run-failed-specs        # macOS
+# xclip -o | bin/ci-run-failed-specs     # Linux (requires: apt install xclip)
+# wl-paste | bin/ci-run-failed-specs     # Wayland (requires: apt install wl-clipboard)
+
+# Or pass spec paths directly:
+bin/ci-run-failed-specs './spec/system/integration_spec.rb[1:1:1:1]'
+
+# Or from a file:
+bin/ci-run-failed-specs < failures.txt
+```
+
+This script:
+- 🎯 **Runs only failing examples** - not the entire test suite
+- 📋 **Parses RSpec output** - extracts spec paths automatically
+- 🔄 **Deduplicates** - removes duplicate specs
+- 📁 **Auto-detects directory** - runs from spec/dummy when needed
+
+## RBS Type Checking
+
+React on Rails uses RBS (Ruby Signature) for static type checking with Steep.
+
+### Quick Start
+
+- **Validate signatures**: `bundle exec rake rbs:validate` (run by CI)
+- **Run type checker**: `bundle exec rake rbs:steep` (currently disabled in CI due to existing errors)
+- **Runtime checking**: Enabled by default in tests when `rbs` gem is available
+
+### Runtime Type Checking
+
+Runtime type checking is **ENABLED BY DEFAULT** during test runs for:
+- `rake run_rspec:gem` - Unit tests
+- `rake run_rspec:dummy` - Integration tests
+- `rake run_rspec:dummy_no_turbolinks` - Integration tests without Turbolinks
+
+**Performance Impact**: Runtime type checking adds overhead (typically 5-15%) to test execution. This is acceptable during development and CI as it catches type errors in actual execution paths that static analysis might miss.
+
+To disable runtime checking (e.g., for faster test iterations during development):
+```bash
+DISABLE_RBS_RUNTIME_CHECKING=true rake run_rspec:gem
+```
+
+**When to disable**: Consider disabling during rapid test-driven development cycles where you're running tests frequently. Re-enable before committing to catch type violations.
+
+### Adding Type Signatures
+
+When creating new Ruby files in `lib/react_on_rails/`:
+
+1. **Create RBS signature**: Add `sig/react_on_rails/filename.rbs`
+2. **Add to Steepfile**: Include `check "lib/react_on_rails/filename.rb"` in Steepfile
+3. **Validate**: Run `bundle exec rake rbs:validate`
+4. **Type check**: Run `bundle exec rake rbs:steep`
+5. **Fix errors**: Address any type errors before committing
+
+### Files Currently Type-Checked
+
+See `Steepfile` for the complete list. Core files include:
+- `lib/react_on_rails.rb`
+- `lib/react_on_rails/configuration.rb`
+- `lib/react_on_rails/helper.rb`
+- `lib/react_on_rails/packer_utils.rb`
+- `lib/react_on_rails/server_rendering_pool.rb`
+- And 5 more (see Steepfile for full list)
+
+### Pro Package Type Checking
+
+The Pro package has its own RBS signatures in `react_on_rails_pro/sig/`.
+
+Validate Pro signatures:
+```bash
+cd react_on_rails_pro && bundle exec rake rbs:validate
+```
+## Changelog
+
+**IMPORTANT: This is a monorepo with TWO separate changelogs:**
+- **Open Source**: `/CHANGELOG.md` - for react_on_rails gem and npm package
+- **Pro**: `/CHANGELOG_PRO.md` - for react_on_rails_pro gem and npm packages
+
+When making changes, update the **appropriate changelog(s)**:
+- Open-source features/fixes → Update `/CHANGELOG.md`
+- Pro-only features/fixes → Update `/CHANGELOG_PRO.md`
+- Changes affecting both → Update **BOTH** changelogs
+
+### Changelog Guidelines
+
+- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
+- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
+- **Format**: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
+- **Use `/update-changelog` command** for guided changelog updates with automatic formatting
+- **Version management after releases**:
+  - Open source: `bundle exec rake update_changelog`
+  - Pro: `bundle exec rake update_changelog CHANGELOG=CHANGELOG_PRO.md`
+- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples
+
+### Beta Release Changelog Curation
+
+When consolidating beta versions into a stable release, carefully curate entries to include only user-facing changes:
+
+**Remove these types of entries:**
+
+1. **Developer-only tooling**:
+   - yalc publish fixes (local development tool)
+   - Git dependency support (contributor workflow)
+   - CI/build script improvements
+   - Internal tooling changes
+
+2. **Beta-specific fixes**:
+   - Bugs introduced during the beta cycle (not present in last stable)
+   - Fixes for new beta-only features (e.g., bin/dev in 16.2.0.beta)
+   - Generator handling of beta/RC version formats
+
+3. **Pro-specific features** (move to Pro changelog):
+   - Node renderer fixes/improvements
+   - Streaming-related changes
+   - Async loading features (Pro-exclusive)
+
+**Keep these types of entries:**
+
+1. **User-facing fixes**:
+   - Bugs that existed in previous stable release (e.g., 16.1.x)
+   - Compatibility fixes (Rails version support, etc.)
+   - Performance improvements affecting all users
+
+2. **Breaking changes**:
+   - API changes requiring migration
+   - Removed methods/features
+   - Configuration changes
+
+**Investigation process:**
+
+For each suspicious entry:
+1. Check git history: `git log --oneline <last_stable>..<current_beta> -- <file>`
+2. Determine when bug was introduced (stable vs beta cycle)
+3. Verify whether fix applies to stable users or only beta users
+4. Check PR description for context about what was broken
+
+**Example reference:** See [PR #2072](https://github.com/shakacode/react_on_rails/pull/2072) for a complete example of beta changelog curation with detailed investigation notes.
+
 ## ⚠️ FORMATTING RULES
 
 **Prettier is the SOLE authority for formatting non-Ruby files, and RuboCop for formatting Ruby files. NEVER manually format code.**
@@ -54,12 +316,25 @@ Git hooks will automatically run linting on **all changed files (staged + unstag
 **CRITICAL**: When resolving merge conflicts, follow this exact sequence:
 
 1. **Resolve logical conflicts only** - don't worry about formatting
-2. **Add resolved files**: `git add .` (or specific files)
-3. **Auto-fix everything**: `rake autofix`
-4. **Add any formatting changes**: `git add .`
-5. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+2. **VERIFY FILE PATHS** - if the conflict involved directory structure:
+   - Check if any hardcoded paths need updating
+   - Run: `grep -r "old/path" . --exclude-dir=node_modules`
+   - Pay special attention to package-scripts.yml, webpack configs, package.json
+   - **Test affected scripts:** If package-scripts.yml changed, run `yarn run prepack`
+3. **Add resolved files**: `git add .` (or specific files)
+4. **Auto-fix everything**: `rake autofix`
+5. **Add any formatting changes**: `git add .`
+6. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+7. **TEST CRITICAL SCRIPTS if build configs changed:**
+   ```bash
+   yarn run prepack          # Test prepack script
+   yarn run yalc.publish     # Test yalc publish if package structure changed
+   rake run_rspec:gem        # Run relevant test suites
+   ```
 
 **❌ NEVER manually format during conflict resolution** - this causes formatting wars between tools.
+**❌ NEVER blindly accept path changes** - verify they're correct for current structure.
+**❌ NEVER skip testing after resolving conflicts in build configs** - silent failures are dangerous.
 
 ### Debugging Formatting Issues
 - Check current formatting: `yarn start format.listDifferent`
@@ -79,14 +354,30 @@ Git hooks will automatically run linting on **all changed files (staged + unstag
 - **Gem-only tests**: `rake run_rspec:gem`
 - **All tests except examples**: `rake all_but_examples`
 
+## Testing Build and Package Scripts
+
+@.claude/docs/testing-build-scripts.md
+
+## Master Branch Health Monitoring
+
+@.claude/docs/master-health-monitoring.md
+
+## Managing File Paths in Configuration Files
+
+@.claude/docs/managing-file-paths.md
+
 ## Project Architecture
 
-### Dual Package Structure
+### Monorepo Structure
 
-This project maintains both a Ruby gem and an NPM package:
+This is a monorepo containing both the open-source package and the Pro package:
 
+- **Open Source**: Root directory contains the main React on Rails gem and package
+- **Pro Package**: `react_on_rails_pro/` contains the Pro features (separate linting/formatting config)
 - **Ruby gem**: Located in `lib/`, provides Rails integration and server-side rendering
-- **NPM package**: Located in `node_package/src/`, provides client-side React integration
+- **NPM package**: Located in `packages/react-on-rails/src/`, provides client-side React integration
+
+**IMPORTANT**: The `react_on_rails_pro/` directory has its own Prettier/ESLint configuration. When CI runs, it lints both directories separately. The pre-commit hooks will catch issues in both directories.
 
 ### Core Components
 
@@ -98,7 +389,7 @@ This project maintains both a Ruby gem and an NPM package:
 - **`engine.rb`**: Rails engine integration
 - **Generators**: Located in `lib/generators/react_on_rails/`
 
-#### JavaScript/TypeScript Side (`node_package/src/`)
+#### JavaScript/TypeScript Side (`packages/react-on-rails/src/`)
 
 - **`ReactOnRails.ts`**: Main entry point for client-side functionality
 - **`serverRenderReactComponent.ts`**: Server-side rendering logic
@@ -108,7 +399,7 @@ This project maintains both a Ruby gem and an NPM package:
 ### Build System
 
 - **Ruby**: Standard gemspec-based build
-- **JavaScript**: TypeScript compilation to `node_package/lib/`
+- **JavaScript**: TypeScript compilation to `packages/react-on-rails/lib/`
 - **Testing**: Jest for JS, RSpec for Ruby
 - **Linting**: ESLint for JS/TS, RuboCop for Ruby
 
@@ -118,6 +409,94 @@ This project maintains both a Ruby gem and an NPM package:
 - **Examples**: Generated via rake tasks for different webpack configurations
 - **Rake tasks**: Defined in `rakelib/` for various development operations
 
+## Debugging Webpack Configuration Issues
+
+When encountering issues with Webpack/Shakapacker configuration (e.g., components not rendering, CSS modules failing), use this debugging approach:
+
+### 1. Create Debug Scripts
+
+Create temporary debug scripts in the dummy app root to inspect the actual webpack configuration:
+
+```javascript
+// debug-webpack-rules.js - Inspect all webpack rules
+const { generateWebpackConfig } = require('shakapacker');
+
+const config = generateWebpackConfig();
+
+console.log('=== Webpack Rules ===');
+console.log(`Total rules: ${config.module.rules.length}\n`);
+
+config.module.rules.forEach((rule, index) => {
+  console.log(`\nRule ${index}:`);
+  console.log('  test:', rule.test);
+  console.log('  use:', Array.isArray(rule.use) ? rule.use.map(u => typeof u === 'string' ? u : u.loader) : rule.use);
+
+  if (rule.test) {
+    console.log('  Matches .scss:', rule.test.test && rule.test.test('example.scss'));
+    console.log('  Matches .module.scss:', rule.test.test && rule.test.test('example.module.scss'));
+  }
+});
+```
+
+```javascript
+// debug-webpack-with-config.js - Inspect config AFTER modifications
+const commonWebpackConfig = require('./config/webpack/commonWebpackConfig');
+
+const config = commonWebpackConfig();
+
+console.log('=== Webpack Rules AFTER commonWebpackConfig ===');
+config.module.rules.forEach((rule, index) => {
+  if (rule.test && rule.test.test('example.module.scss')) {
+    console.log(`\nRule ${index} (CSS Modules):`);
+    if (Array.isArray(rule.use)) {
+      rule.use.forEach((loader, i) => {
+        if (loader.loader && loader.loader.includes('css-loader')) {
+          console.log(`  css-loader options:`, loader.options);
+        }
+      });
+    }
+  }
+});
+```
+
+### 2. Run Debug Scripts
+
+```bash
+cd spec/dummy  # or react_on_rails_pro/spec/dummy
+NODE_ENV=test RAILS_ENV=test node debug-webpack-rules.js
+NODE_ENV=test RAILS_ENV=test node debug-webpack-with-config.js
+```
+
+### 3. Analyze Output
+
+- Verify the rules array structure matches expectations
+- Check that loader options are correctly set
+- Confirm rules only match intended file patterns
+- Ensure modifications don't break existing loaders
+
+### 4. Common Issues & Solutions
+
+**CSS Modules breaking after Shakapacker upgrade:**
+- Shakapacker 9.0+ defaults to `namedExport: true` for CSS Modules
+- Existing code using `import styles from './file.module.css'` will fail
+- Override in webpack config:
+  ```javascript
+  loader.options.modules.namedExport = false;
+  loader.options.modules.exportLocalsConvention = 'camelCase';
+  ```
+
+**Rules not matching expected files:**
+- Use `.test.test('example.file')` to check regex matching
+- Shakapacker may combine multiple file extensions in single rules
+- Test with actual filenames from your codebase
+
+### 5. Clean Up
+
+Always remove debug scripts before committing:
+```bash
+rm debug-*.js
+```
+
 ## Important Notes
 
 - Use `yalc` for local development when testing with external apps
@@ -126,10 +505,230 @@ This project maintains both a Ruby gem and an NPM package:
 - Generated examples are in `gen-examples/` (ignored by git)
 - Only use `yarn` as the JS package manager, never `npm`
 
+## Playwright E2E Testing
+
+### Overview
+Playwright E2E testing is integrated via the `cypress-on-rails` gem (v1.19+), which provides seamless integration between Playwright and Rails. This allows you to control Rails application state during tests, use factory_bot, and more.
+
+### Setup
+The gem and Playwright are already configured. To install Playwright browsers:
+
+```bash
+cd spec/dummy
+yarn playwright install --with-deps
+```
+
+### Running Playwright Tests
+
+**Note:** Playwright will automatically start the Rails server on port 5017 before running tests. You don't need to manually start the server.
+
+```bash
+cd spec/dummy
+
+# Run all tests (Rails server auto-starts)
+yarn test:e2e
+
+# Run tests in UI mode (interactive debugging)
+yarn test:e2e:ui
+
+# Run tests with visible browser
+yarn test:e2e:headed
+
+# Debug a specific test
+yarn test:e2e:debug
+
+# View test report
+yarn test:e2e:report
+
+# Run specific test file
+yarn test:e2e e2e/playwright/e2e/react_on_rails/basic_components.spec.js
+```
+
+### Writing Tests
+
+Tests are located in `spec/dummy/e2e/playwright/e2e/`. The gem provides helpful commands for Rails integration:
+
+```javascript
+import { test, expect } from "@playwright/test";
+import { app, appEval, appFactories } from '../../support/on-rails';
+
+test.describe("My React Component", () => {
+  test.beforeEach(async ({ page }) => {
+    // Clean database before each test
+    await app('clean');
+  });
+
+  test("should interact with component", async ({ page }) => {
+    // Create test data using factory_bot
+    await appFactories([['create', 'user', { name: 'Test User' }]]);
+
+    // Or run arbitrary Ruby code
+    await appEval('User.create!(email: "test@example.com")');
+
+    // Navigate and test
+    await page.goto("/");
+    const component = page.locator('#MyComponent-react-component-0');
+    await expect(component).toBeVisible();
+  });
+});
+```
+
+### Available Rails Helpers
+
+The `cypress-on-rails` gem provides these helpers (imported from `support/on-rails.js`):
+
+- `app('clean')` - Clean database
+- `appEval(code)` - Run arbitrary Ruby code
+- `appFactories(options)` - Create records via factory_bot
+- `appScenario(name)` - Load predefined scenario
+- See `e2e/playwright/app_commands/` for available commands
+
+### Creating App Commands
+
+Add custom commands in `e2e/playwright/app_commands/`:
+
+```ruby
+# e2e/playwright/app_commands/my_command.rb
+CypressOnRails::SmartFactoryWrapper.configure(
+  always_reload: !Rails.configuration.cache_classes,
+  factory: :factory_bot,
+  dir: "{#{FactoryBot.definition_file_paths.join(',')}}"
+)
+
+command 'my_command' do |options|
+  # Your custom Rails code
+  { success: true, data: options }
+end
+```
+
+### Test Organization
+
+```text
+spec/dummy/e2e/
+├── playwright.config.js          # Playwright configuration
+├── playwright/
+│   ├── support/
+│   │   ├── index.js              # Test setup
+│   │   └── on-rails.js           # Rails helper functions
+│   ├── e2e/
+│   │   ├── react_on_rails/       # React on Rails specific tests
+│   │   │   └── basic_components.spec.js
+│   │   └── rails_examples/       # Example tests
+│   │       └── using_scenarios.spec.js
+│   └── app_commands/             # Rails helper commands
+│       ├── clean.rb
+│       ├── factory_bot.rb
+│       ├── eval.rb
+│       └── scenarios/
+│           └── basic.rb
+```
+
+### Best Practices
+
+- Use `app('clean')` in `beforeEach` to ensure clean state
+- Leverage Rails helpers (`appFactories`, `appEval`) instead of UI setup
+- Test React on Rails-specific features: SSR, hydration, component registry
+- Use component IDs like `#ComponentName-react-component-0` for selectors
+- Monitor console errors during tests
+- Test across different browsers with `--project` flag
+
+### Debugging
+
+- Run in UI mode: `yarn test:e2e:ui`
+- Use `page.pause()` to pause execution
+- Check `playwright-report/` for detailed results after test failures
+- Enable debug logging in `playwright.config.js`
+
+### CI Integration
+
+Playwright E2E tests run automatically in CI via GitHub Actions (`.github/workflows/playwright.yml`). The workflow:
+- Runs on all PRs and pushes to master
+- Uses GitHub Actions annotations for test failures
+- Uploads HTML reports as artifacts (available for 30 days)
+- Auto-starts Rails server before running tests
+
+## Rails Engine Development Nuances
+
+React on Rails is a **Rails Engine**, which has important implications for development:
+
+### Automatic Rake Task Loading
+
+**CRITICAL**: Rails::Engine automatically loads all `.rake` files from `lib/tasks/` directory. **DO NOT** use a `rake_tasks` block to explicitly load them, as this causes duplicate task execution.
+
+```ruby
+# ❌ WRONG - Causes duplicate execution
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    rake_tasks do
+      load File.expand_path("../tasks/generate_packs.rake", __dir__)
+      load File.expand_path("../tasks/assets.rake", __dir__)
+      load File.expand_path("../tasks/locale.rake", __dir__)
+    end
+  end
+end
+
+# ✅ CORRECT - Rails::Engine loads lib/tasks/*.rake automatically
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    # Rake tasks are automatically loaded from lib/tasks/*.rake by Rails::Engine
+    # No explicit loading needed
+  end
+end
+```
+
+**When to use `rake_tasks` block:**
+- Tasks are in a **non-standard location** (not `lib/tasks/`)
+- You need to **programmatically generate** tasks
+- You need to **pass context** to the tasks
+
+**Historical Context**: PR #1770 added explicit rake task loading, causing webpack builds and pack generation to run twice during `rake assets:precompile`. This was fixed in PR #2052. See `analysis/rake-task-duplicate-analysis.md` for full details.
+
+### Engine Initializers and Hooks
+
+Engines have specific initialization hooks that run at different times:
+
+```ruby
+module ReactOnRails
+  class Engine < ::Rails::Engine
+    # Runs after Rails initializes but before routes are loaded
+    config.to_prepare do
+      ReactOnRails::ServerRenderingPool.reset_pool
+    end
+
+    # Runs during Rails initialization, use for validations
+    initializer "react_on_rails.validate_version" do
+      config.after_initialize do
+        # Validation logic here
+      end
+    end
+  end
+end
+```
+
+### Engine vs Application Code
+
+- **Engine code** (`lib/react_on_rails/`): Runs in the gem context, has limited access to host application
+- **Host application code**: The Rails app that includes the gem
+- **Generators** (`lib/generators/react_on_rails/`): Run in host app context during setup
+
+### Testing Engines
+
+- **Dummy app** (`spec/dummy/`): Full Rails app for integration testing
+- **Unit tests** (`spec/react_on_rails/`): Test gem code in isolation
+- Always test both contexts: gem code alone and gem + host app integration
+
+### Common Pitfalls
+
+1. **Assuming host app structure**: Don't assume `app/javascript/` exists—it might not in older apps
+2. **Path resolution**: Use `Rails.root` for host app paths, not relative paths
+3. **Autoloading**: Engine code follows Rails autoloading rules but with a different load path
+4. **Configuration**: Engine config is separate from host app config—use `ReactOnRails.configure`
+
 ## IDE Configuration
 
 Exclude these directories to prevent IDE slowdowns:
 
-- `/coverage`, `/tmp`, `/gen-examples`, `/node_package/lib`
+- `/coverage`, `/tmp`, `/gen-examples`, `/packages/react-on-rails/lib`
 - `/node_modules`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
 - `/spec/dummy/app/assets/webpack`, `/spec/dummy/log`
+- `/spec/dummy/e2e/playwright-report`, `/spec/dummy/test-results`