react_on_rails 15.0.0.rc.2 → 16.0.1.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50ca168413057bb25fbd6ca60307bb48baceabcef86cbbd4a8141bb5913e9ca5
-  data.tar.gz: 6cf924cd26ae04b10d303e0c761daf19af7bd3d15417421e56c6492b6e4264ee
+  metadata.gz: 6df96f164d23050adbea7f31bb61ab36a092fbad393d2d1d0e8a307f5c6a41d0
+  data.tar.gz: e6e4b7e5c65175310edc4e1c7a01df8ffdfc8cdb9ca7fc1b5012988db174d360
 SHA512:
-  metadata.gz: 3485bf92e659aa921d0352ee43e3cd56b836818c17a6d643332a5e5fecaac0da696e2ab1723215d069d25201cf1da41bfadea2546bf435bfea01924ba4010096
-  data.tar.gz: a7e120190894dd8b34637274a6fb8407c8ab6b7a7e6608b744244868d661ba8e11e3d1925a7eaa86d27905cc2db2c870453f6a7af8c795c504d1dd988f0d7130
+  metadata.gz: bf0ae04e65fe1225e159154df70a1043a447e15c058fe62a743e99fd4e8ef489b61b64766da0516d93faec781ed4d968e5b3bce85228e560f5c2c3a3646518ee
+  data.tar.gz: e604837b4b5182504ca2c2c38acbcdb8cf2dbea6f8fd94310fcedc28e4e8f4fe072048fdce21bed26317b0147d5712fb4a530a4c1fb3ae9bf52f47c05fa63a00

data/CHANGELOG.md

@@ -23,63 +23,132 @@ After a release, please make sure to run `bundle exec rake update_changelog`. Th
 
 Changes since the last non-beta release.
 
-#### Fixed
+#### Pro License Structure Implementation
 
-- Enable support for ReactRefreshWebpackPlugin v0.6.0 by adding conditional logic regarding configuration. [PR 1748](https://github.com/shakacode/react_on_rails/pull/1748) by [judahmeek](https://github.com/judahmeek).
+**🔐 License Architecture**
 
-- Replace RenderOptions.renderRequestId and use local trackers instead. This change should only be relevant to ReactOnRails Pro users. [PR 1745](https://github.com/shakacode/react_on_rails/pull/1745) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- **Core/Pro separation**: Moved Pro features into dedicated `lib/react_on_rails/pro/` and `node_package/src/pro/` directories with clear licensing boundaries [PR 1791](https://github.com/shakacode/react_on_rails/pull/1791) by [abanoubghadban](https://github.com/AbanoubGhadban)
+- **Runtime license validation**: Implemented Pro license gating with graceful fallback to core functionality when Pro license unavailable
+- **License documentation**: Added NOTICE files in Pro directories referencing canonical `REACT-ON-RAILS-PRO-LICENSE.md`
+- **Updated LICENSE.md**: Clearly distinguishes core MIT license from Pro-licensed directories
 
-- Fixed invalid warnings about non-exact versions when using a pre-release version of React on Rails, as well as missing warnings when using different pre-release versions of the gem and the Node package. [PR 1742](https://github.com/shakacode/react_on_rails/pull/1742) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
+**⚡ Pro Feature Enhancements**
 
-### [15.0.0-rc.1] - 2025-06-18
+- **Immediate hydration**: Enhanced immediate hydration functionality with Pro license validation and warning badges
+- **Security improvements**: Hardened DOM selectors using `CSS.escape()` and proper JavaScript escaping for XSS protection
+- **Architecture refactoring**: Centralized Pro utilities and clean separation between core and Pro helper functionality
 
-#### Improved
+#### Enhanced TypeScript Generator Support
 
-- Ensured that the RSC payload is injected after the component's HTML markup to improve the performance of the RSC payload injection. [PR 1738](https://github.com/shakacode/react_on_rails/pull/1738) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+**🔧 Generator Improvements**
 
-### [15.0.0-rc.0] - 2025-06-16
+- **Modern TypeScript patterns**: Generators now produce more idiomatic TypeScript code with improved type inference instead of explicit type annotations [PR 1786](https://github.com/shakacode/react_on_rails/pull/1786) by [justin808](https://github.com/justin808)
+- **Optimized tsconfig.json**: Updated compiler options to use `"moduleResolution": "bundler"` for better bundler compatibility
+- **Enhanced Redux TypeScript integration**: Improved type safety and modern React patterns (useMemo, type-only imports)
+- **Smart bin/dev defaults**: Generated `bin/dev` script now automatically navigates to `/hello_world` route for immediate component visibility
 
-#### Improved
+**🔐 Security Enhancements**
 
-- Improved RSC rendering flow by eliminating double rendering of server components and reducing the number of HTTP requests.
-- Updated communication protocol between Node Renderer and Rails to version 2.0.0 which supports the ability to upload multiple bundles at once.
-- Added `RSCRoute` component to enable seamless server-side rendering of React Server Components. This component automatically handles RSC payload injection and hydration, allowing server components to be rendered directly within client components while maintaining optimal performance.
+- **Fixed command injection vulnerabilities**: Replaced unsafe string interpolation in generator package installation commands with secure array-based system calls
+- **Improved input validation**: Enhanced package manager validation and argument sanitization across all generators
 
-[PR 1696](https://github.com/shakacode/react_on_rails/pull/1696) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+**🎯 Developer Experience**
+
+- **Better component templates**: Removed unnecessary type annotations while maintaining type safety through TypeScript's inference
+- **Cleaner generated code**: Streamlined templates following modern React and TypeScript best practices
+- **Improved helper methods**: Added reusable `component_extension` helper for consistent file extension handling
 
 #### Added
 
-- Configuration option `generated_component_packs_loading_strategy` to control how generated component packs are loaded. It supports `sync`, `async`, and `defer` strategies. [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- **`react_on_rails:doctor` rake task**: New diagnostic command to validate React on Rails setup and identify configuration issues. Provides comprehensive checks for environment prerequisites, dependencies, Rails integration, and Webpack configuration. Use `rake react_on_rails:doctor` to diagnose your setup, with optional `VERBOSE=true` for detailed output.
 
-- Support for returning React component from async render-function. [PR 1720](https://github.com/shakacode/react_on_rails/pull/1720) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+### [16.0.0] - 2025-09-16
 
-### Removed (Breaking Changes)
+**React on Rails v16 is a major release that modernizes the library with ESM support, removes legacy Webpacker compatibility, and introduces significant performance improvements. This release builds on the foundation of v14 with enhanced RSC (React Server Components) support and streamlined configuration.**
 
-- Deprecated `defer_generated_component_packs` configuration option. You should use `generated_component_packs_loading_strategy` instead. [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+See [Release Notes](docs/release-notes/16.0.0.md) for complete migration guide.
 
-### Changed
+#### Major Enhancements
 
-- **Breaking change**: The package is ESM-only now. Please see [Release Notes](docs/release-notes/15.0.0.md#esm-only-package) for more details.
-- The global context is now accessed using `globalThis`. [PR 1727](https://github.com/shakacode/react_on_rails/pull/1727) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
-- Generated client packs now import from `react-on-rails/client` instead of `react-on-rails`. [PR 1706](https://github.com/shakacode/react_on_rails/pull/1706) by [alexeyr-ci](https://github.com/alexeyr-ci).
-  - The "optimization opportunity" message when importing the server-side `react-on-rails` instead of `react-on-rails/client` in browsers is now a warning for two reasons:
-    - Make it more prominent
-    - Include a stack trace when clicked
+**🚀 React Server Components (RSC) -- Requires React on Rails Pro**
 
-### [15.0.0-alpha.2] - 2025-03-07
+- **Enhanced RSC rendering flow**: Eliminated double rendering and reduced HTTP requests
+- **`RSCRoute` component**: Seamless server-side rendering with automatic payload injection and hydration [PR 1696](https://github.com/shakacode/react_on_rails/pull/1696) by [AbanoubGhadban](https://github.com/AbanoubGhadban)
+- **Optimized RSC payload injection**: Now injected after component HTML markup for better performance [PR 1738](https://github.com/shakacode/react_on_rails/pull/1738) by [AbanoubGhadban](https://github.com/AbanoubGhadban)
+- **Communication protocol v2.0.0**: Supports uploading multiple bundles at once for improved efficiency
 
-See [Release Notes](docs/release-notes/15.0.0.md) for full details.
+**⚡ Performance & Loading Strategy**
 
-#### Added
+- **New `generated_component_packs_loading_strategy`**: Choose from `sync`, `async`, or `defer` strategies [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban)
+- **Async render function support**: Components can now return from async render functions [PR 1720](https://github.com/shakacode/react_on_rails/pull/1720) by [AbanoubGhadban](https://github.com/AbanoubGhadban)
+- **Optimized client imports**: Generated packs now import from `react-on-rails/client` for better tree-shaking [PR 1706](https://github.com/shakacode/react_on_rails/pull/1706) by [alexeyr-ci](https://github.com/alexeyr-ci)
+
+#### Developer Experience
 
-- React Server Components Support (Pro Feature) [PR 1644](https://github.com/shakacode/react_on_rails/pull/1644) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-- Improved component and store hydration performance [PR 1656](https://github.com/shakacode/react_on_rails/pull/1656) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- **Enhanced error messaging**: Clearer troubleshooting steps and prominent optimization warnings
+- **Modern global access**: Using `globalThis` instead of window/global detection [PR 1727](https://github.com/shakacode/react_on_rails/pull/1727) by [alexeyr-ci2](https://github.com/alexeyr-ci2)
+- **Simplified CI configuration**: Clear `minimum`/`latest` dependency naming instead of `oldest`/`newest`
+- **ReactRefreshWebpackPlugin v0.6.0 support**: Added conditional logic for proper configuration [PR 1748](https://github.com/shakacode/react_on_rails/pull/1748) by [judahmeek](https://github.com/judahmeek)
+- **Version validation improvements**: Fixed invalid warnings with pre-release versions [PR 1742](https://github.com/shakacode/react_on_rails/pull/1742) by [alexeyr-ci2](https://github.com/alexeyr-ci2)
 
 #### Breaking Changes
 
-- `ReactOnRails.reactOnRailsPageLoaded` is now an async function
-- `force_load` configuration now defaults to `true`
-- `defer_generated_component_packs` configuration now defaults to `false`
+**🔧 Webpacker Support Removed**
+
+- **Complete removal of Webpacker support**. Shakapacker >= 6.0 is now required.
+- Migration:
+  - Remove `webpacker` gem from your Gemfile
+  - Install `shakapacker` gem version 6.0+ (8.0+ recommended)
+  - Replace `bin/webpacker` commands with `bin/shakapacker`
+  - Update webpacker configuration files to shakapacker equivalents
+- Removed files: `rakelib/webpacker_examples.rake`, `lib/generators/react_on_rails/adapt_for_older_shakapacker_generator.rb`
+
+**📦 Package System Modernization**
+
+- **ESM-only package**: CommonJS `require()` no longer supported
+- Migration:
+  - Replace `require('react-on-rails')` with `import ReactOnRails from 'react-on-rails'`
+  - For Node.js < 20.19.0, upgrade or use dynamic imports
+  - For TypeScript errors, upgrade to TypeScript 5.8+ and set `module: "nodenext"`
+
+**⚡ Configuration API Changes**
+
+- **`defer_generated_component_packs` deprecated** → use `generated_component_packs_loading_strategy`
+- Migration:
+
+  - `defer_generated_component_packs: true` → `generated_component_packs_loading_strategy: :defer`
+  - `defer_generated_component_packs: false` → `generated_component_packs_loading_strategy: :sync`
+  - Recommended: `generated_component_packs_loading_strategy: :async` for best performance
+
+- **`force_load` renamed to `immediate_hydration`** for API clarity
+- Migration:
+  - `config.force_load = true` → `config.immediate_hydration = true`
+  - `react_component(force_load: true)` → `react_component(immediate_hydration: true)`
+  - `redux_store(force_load: true)` → `redux_store(immediate_hydration: true)`
+- Note: `immediate_hydration` requires React on Rails Pro license
+
+**🔄 Async API Changes**
+
+- **`ReactOnRails.reactOnRailsPageLoaded()` is now async**
+- Migration: Add `await` when calling: `await ReactOnRails.reactOnRailsPageLoaded()`
+
+**🏗️ Runtime Suggested Versions**
+
+- Ruby: 3.2 - 3.4 (was 3.0 - 3.3)
+- Node.js: 20 - 22 (was 16 - 20)
+- Note: These are CI-tested versions; older versions may work but aren't guaranteed
+
+**🎯 Generator Improvements**
+
+- Install generator now validates JavaScript package manager presence
+- Improved error handling with `Thor::Error` instead of `exit(1)`
+- Enhanced error messages with clearer troubleshooting steps
+
+### [15.0.0] - 2025-08-28 - RETRACTED
+
+**⚠️ This version has been retracted due to API design issues. Please upgrade directly to v16.0.0.**
+
+The `force_load` feature was incorrectly available without a Pro license and has been renamed to `immediate_hydration` for better clarity. All features from v15 are available in v16 with the corrected API.
 
 ### [14.2.0] - 2025-03-03
 
@@ -1577,8 +1646,8 @@ such as:
 
 - Fix several generator-related issues.
 
-[Unreleased]: https://github.com/shakacode/react_on_rails/compare/15.0.0-alpha.2...master
-[15.0.0-alpha.2]: https://github.com/shakacode/react_on_rails/compare/14.2.0...15.0.0-alpha.2
+[Unreleased]: https://github.com/shakacode/react_on_rails/compare/16.0.0...master
+[16.0.0]: https://github.com/shakacode/react_on_rails/compare/14.2.0...16.0.0
 [14.2.0]: https://github.com/shakacode/react_on_rails/compare/14.1.1...14.2.0
 [14.1.1]: https://github.com/shakacode/react_on_rails/compare/14.1.0...14.1.1
 [14.1.0]: https://github.com/shakacode/react_on_rails/compare/14.0.5...14.1.0

data/CLAUDE.md

@@ -0,0 +1,102 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## ⚠️ CRITICAL REQUIREMENTS
+
+**BEFORE EVERY COMMIT/PUSH:**
+
+1. **ALWAYS run `bundle exec rubocop` and fix ALL violations**
+2. **ALWAYS ensure files end with a newline character**
+3. **NEVER push without running full lint check first**
+
+These requirements are non-negotiable. CI will fail if not followed.
+
+## Development Commands
+
+### Essential Commands
+
+- **Install dependencies**: `bundle && yarn`
+- **Run tests**:
+  - Ruby tests: `rake run_rspec`
+  - JavaScript tests: `yarn run test` or `rake js_tests`
+  - 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
+  - All linters: `rake lint` (runs ESLint and RuboCop)
+  - ESLint only: `yarn run lint` or `rake lint:eslint`
+  - RuboCop only: `rake lint:rubocop`
+- **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)
+- **Type checking**: `yarn run type-check`
+- **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines
+
+### Development Setup Commands
+
+- **Initial setup**: `bundle && yarn && rake shakapacker_examples:gen_all && rake node_package && rake`
+- **Prepare examples**: `rake shakapacker_examples:gen_all`
+- **Generate node package**: `rake node_package`
+- **Run single test example**: `rake run_rspec:example_basic`
+
+### Test Environment Commands
+
+- **Dummy app tests**: `rake run_rspec:dummy`
+- **Gem-only tests**: `rake run_rspec:gem`
+- **All tests except examples**: `rake all_but_examples`
+
+## Project Architecture
+
+### Dual Package Structure
+
+This project maintains both a Ruby gem and an NPM package:
+
+- **Ruby gem**: Located in `lib/`, provides Rails integration and server-side rendering
+- **NPM package**: Located in `node_package/src/`, provides client-side React integration
+
+### Core Components
+
+#### Ruby Side (`lib/react_on_rails/`)
+
+- **`helper.rb`**: Rails view helpers for rendering React components
+- **`server_rendering_pool.rb`**: Manages Node.js processes for server-side rendering
+- **`configuration.rb`**: Global configuration management
+- **`engine.rb`**: Rails engine integration
+- **Generators**: Located in `lib/generators/react_on_rails/`
+
+#### JavaScript/TypeScript Side (`node_package/src/`)
+
+- **`ReactOnRails.ts`**: Main entry point for client-side functionality
+- **`serverRenderReactComponent.ts`**: Server-side rendering logic
+- **`ComponentRegistry.ts`**: Manages React component registration
+- **`StoreRegistry.ts`**: Manages Redux store registration
+
+### Build System
+
+- **Ruby**: Standard gemspec-based build
+- **JavaScript**: TypeScript compilation to `node_package/lib/`
+- **Testing**: Jest for JS, RSpec for Ruby
+- **Linting**: ESLint for JS/TS, RuboCop for Ruby
+
+### Examples and Testing
+
+- **Dummy app**: `spec/dummy/` - Rails app for testing integration
+- **Examples**: Generated via rake tasks for different webpack configurations
+- **Rake tasks**: Defined in `rakelib/` for various development operations
+
+## Important Notes
+
+- Use `yalc` for local development when testing with external apps
+- The project supports both Webpacker and Shakapacker
+- Server-side rendering uses isolated Node.js processes
+- React Server Components support available in Pro version
+- Generated examples are in `gen-examples/` (ignored by git)
+
+## IDE Configuration
+
+Exclude these directories to prevent IDE slowdowns:
+
+- `/coverage`, `/tmp`, `/gen-examples`, `/node_package/lib`
+- `/node_modules`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
+- `/spec/dummy/app/assets/webpack`, `/spec/dummy/log`

data/CODING_AGENTS.md

@@ -0,0 +1,312 @@
+# 🤖 Coding Agents & AI Contributors Guide
+
+This guide provides specific guidelines for AI coding agents (like Claude Code) contributing to React on Rails. It supplements the main [CONTRIBUTING.md](./CONTRIBUTING.md) with AI-specific workflows and patterns.
+
+## Quick Reference Commands
+
+### Essential Commands
+
+```bash
+# Install dependencies
+bundle && yarn
+
+# Run tests
+bundle exec rspec                    # All tests (from project root)
+cd spec/dummy && bundle exec rspec   # Dummy app tests only
+
+# Linting & Formatting
+bundle exec rubocop                  # Ruby linting
+bundle exec rubocop [file_path]     # Lint specific file
+# Note: yarn format requires local setup, format manually
+
+# Development
+cd spec/dummy && foreman start       # Start dummy app with webpack
+```
+
+### CI Compliance Checklist
+
+- [ ] `bundle exec rubocop` passes with no offenses
+- [ ] All RSpec tests pass
+- [ ] No trailing whitespace
+- [ ] Line length ≤120 characters
+- [ ] Security violations properly scoped with disable comments
+
+## Development Patterns for AI Contributors
+
+### 1. Task Management
+
+Always use TodoWrite tool for multi-step tasks to:
+
+- Track progress transparently
+- Show the user what's being worked on
+- Ensure no steps are forgotten
+- Mark tasks complete as you finish them
+
+```markdown
+Example workflow:
+
+1. Analyze the problem
+2. Create test cases
+3. Implement the fix
+4. Run tests
+5. Fix linting issues
+6. Update documentation
+```
+
+### 2. Test-Driven Development
+
+When fixing bugs or adding features:
+
+1. **Create failing tests first** that reproduce the issue
+2. **Implement the minimal fix** to make tests pass
+3. **Add comprehensive test coverage** for edge cases
+4. **Verify all existing tests still pass**
+
+### 3. File Processing Guidelines
+
+When working with file generation or processing:
+
+- **Filter by extension**: Only process relevant files (e.g., `.js/.jsx/.ts/.tsx` for React components)
+- **Validate assumptions**: Don't assume all files in a directory are components
+- **Handle edge cases**: CSS modules, config files, etc. should be excluded appropriately
+
+Example from CSS module fix:
+
+```ruby
+COMPONENT_EXTENSIONS = /\.(jsx?|tsx?)$/
+
+def filter_component_files(paths)
+  paths.grep(COMPONENT_EXTENSIONS)
+end
+```
+
+## RuboCop Compliance Patterns
+
+### Common Fixes
+
+1. **Trailing Whitespace**
+
+   ```ruby
+   # Bad
+   let(:value) { "test" }
+
+   # Good
+   let(:value) { "test" }
+   ```
+
+2. **Line Length (120 chars max)**
+
+   ```ruby
+   # Bad
+   expect { eval(pack_content.gsub(/import.*from.*['"];/, "").gsub(/ReactOnRails\.register.*/, "")) }.not_to raise_error
+
+   # Good
+   sanitized_content = pack_content.gsub(/import.*from.*['"];/, "")
+                                   .gsub(/ReactOnRails\.register.*/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   ```
+
+3. **Named Subjects (RSpec)**
+
+   ```ruby
+   # Bad
+   describe "#method_name" do
+     subject { instance.method_name(arg) }
+
+     it "does something" do
+       expect(subject).to eq "result"
+     end
+   end
+
+   # Good
+   describe "#method_name" do
+     subject(:method_result) { instance.method_name(arg) }
+
+     it "does something" do
+       expect(method_result).to eq "result"
+     end
+   end
+   ```
+
+4. **Security/Eval Violations**
+
+   ```ruby
+   # Bad
+   expect { eval(dangerous_code) }.not_to raise_error
+
+   # Good
+   # rubocop:disable Security/Eval
+   sanitized_content = dangerous_code.gsub(/harmful_pattern/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   # rubocop:enable Security/Eval
+   ```
+
+### RuboCop Workflow
+
+1. Run `bundle exec rubocop [file]` to see violations
+2. Fix violations manually or with auto-correct where safe
+3. Re-run to verify fixes
+4. Use disable comments sparingly and with good reason
+
+## Testing Best Practices
+
+### Test Structure
+
+```ruby
+describe "FeatureName" do
+  context "when condition A" do
+    let(:setup) { create_test_condition }
+
+    before do
+      # Setup code
+    end
+
+    it "does expected behavior" do
+      # Arrange, Act, Assert
+    end
+  end
+end
+```
+
+### Test Fixtures
+
+- Create realistic test data that represents edge cases
+- Use descriptive names for fixtures and variables
+- Clean up after tests (handled by RSpec automatically in most cases)
+
+### CSS Module Testing Example
+
+```ruby
+# Create test fixtures
+Write.create("ComponentWithCSSModule.module.css", css_content)
+Write.create("ComponentWithCSSModule.jsx", jsx_content)
+
+# Test the behavior
+it "ignores CSS module files during pack generation" do
+  generated_packs = PacksGenerator.instance.generate_packs_if_stale
+  expect(generated_packs).not_to include("ComponentWithCSSModule.module.js")
+end
+```
+
+## Git & PR Workflow
+
+### Branch Management
+
+```bash
+git checkout -b fix/descriptive-name
+# Make changes
+git add .
+git commit -m "Descriptive commit message
+
+- Bullet points for major changes
+- Reference issue numbers
+- Include 🤖 Generated with Claude Code signature"
+
+git push -u origin fix/descriptive-name
+```
+
+### Commit Message Format
+
+```
+Brief description of the change
+
+- Detailed bullet points of what changed
+- Why the change was needed
+- Any breaking changes or considerations
+
+Fixes #issue_number
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### PR Creation
+
+Use `gh pr create` with:
+
+- Clear title referencing the issue
+- Comprehensive description with summary and test plan
+- Link to the issue being fixed
+- Include the Claude Code signature
+
+## Common Pitfalls & Solutions
+
+### 1. File Path Issues
+
+- Always use absolute paths in tools
+- Check current working directory with `pwd`
+- Use proper path joining methods
+
+### 2. Test Environment
+
+- Run tests from correct directory (often project root)
+- Understand the difference between gem tests vs dummy app tests
+- Clean up test artifacts appropriately
+
+### 3. Dependency Management
+
+- Don't assume packages are installed globally
+- Use `bundle exec` for Ruby commands
+- Verify setup with `bundle && yarn` when needed
+
+### 4. RuboCop Configuration
+
+- Different rules may apply to different directories
+- Use `bundle exec rubocop` (not global rubocop)
+- Check `.rubocop.yml` files for project-specific rules
+
+## Debugging Workflow
+
+1. **Understand the Problem**
+
+   - Read the issue carefully
+   - Reproduce the bug if possible
+   - Identify root cause
+
+2. **Create Minimal Test Case**
+
+   - Write failing test that demonstrates issue
+   - Keep it focused and minimal
+
+3. **Implement Fix**
+
+   - Make smallest change possible
+   - Ensure fix doesn't break existing functionality
+   - Follow existing code patterns
+
+4. **Verify Solution**
+   - All new tests pass
+   - All existing tests still pass
+   - RuboCop compliance maintained
+   - Manual testing if applicable
+
+## IDE Configuration for AI Context
+
+When analyzing codebases, ignore these directories to avoid confusion:
+
+- `/coverage`, `/tmp`, `/gen-examples`
+- `/node_package/lib`, `/node_modules`
+- `/spec/dummy/app/assets/webpack`
+- `/spec/dummy/log`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
+- `/spec/react_on_rails/dummy-for-generators`
+
+## Communication with Human Maintainers
+
+- Be transparent about AI-generated changes
+- Explain reasoning behind implementation choices
+- Ask for clarification when requirements are ambiguous
+- Provide comprehensive commit messages and PR descriptions
+- Include test plans and verification steps
+
+## Resources
+
+- [Main Contributing Guide](./CONTRIBUTING.md)
+- [Pull Request Guidelines](./docs/contributor-info/pull-requests.md)
+- [Generator Testing](./docs/contributor-info/generator-testing.md)
+- [RuboCop Documentation](https://docs.rubocop.org/)
+- [RSpec Best Practices](https://rspec.info/)
+
+---
+
+This guide evolves based on AI contributor experiences. Suggest improvements via issues or PRs!