react_on_rails 17.0.0.rc.1 → 17.0.0.rc.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0feb399078c3e60a35b5e36bc257cc2711bf793fd04dab39c3ccfcfdd8448cd8
-  data.tar.gz: 3848ca13d934d2fda5ca63f8b7660aaac360ac3daec07d7a15433a647d058c44
+  metadata.gz: 0630c2730fc7389d31e1f99d88e8df8dc6eb18b670e2909afd25e1e71b0c50ab
+  data.tar.gz: 6db462a802556e23085ae038585dd7c310c7710fd41a0a336d350383e85b9333
 SHA512:
-  metadata.gz: 3d2a9e86976672ce1b5ae6b869a9d777bb652b35423cb7b361614db8ccdb710423ad8434115f460ffd7522336a9eb8eec74382bd793f4cd537dfe2d12b69df46
-  data.tar.gz: b75324ae9ad146861baebd20716ef293c28509734afbf206da63275db4d29c6a24115a9e2b834781d275a1a586fd9215cdd208c1e93a1101a47d275436cbfda1
+  metadata.gz: 395e61f25e352b69df2788554dd0fcba85834df3e2f42bd768b6c2a81c8579e2d2504da1a47417abcc8ee5369181260c54f828e206f36dba409cbeef5a5818a9
+  data.tar.gz: 5ee8406c0ce296a4dca6e38299c1274fd2e5b6dde7f62f83f9790122dfc44cf88c0ca2cc093a9da7089265e53ed08ded28a018efc1929828c3a3ced000ba41c4

data/.rubocop.yml

@@ -11,6 +11,7 @@ AllCops:
 
   Exclude:
     - 'spec/dummy/bin/*'
+    - 'spec/react_on_rails/dummy-for-generators/**/*'  # Generated fixture contains intentionally invalid Ruby
     - 'spike/**/*'  # Exploratory spike code outside lib/ — not part of the production surface
 
 Naming/FileName:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (17.0.0.rc.1)
+    react_on_rails (17.0.0.rc.3)
       addressable
       connection_pool
       execjs (~> 2.5)
@@ -207,7 +207,6 @@ GEM
       racc (~> 1.4)
     ostruct (0.6.1)
     package_json (0.2.0)
-    parallel (1.24.0)
     parser (3.3.1.0)
       ast (~> 2.4.1)
       racc
@@ -313,34 +312,6 @@ GEM
     rspec-support (3.13.1)
     rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (1.61.0)
-      json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
-      parser (>= 3.3.0.2)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.3)
-      parser (>= 3.3.1.0)
-    rubocop-capybara (2.20.0)
-      rubocop (~> 1.41)
-    rubocop-factory_bot (2.25.1)
-      rubocop (~> 1.41)
-    rubocop-performance (1.20.2)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
-    rubocop-rspec (2.29.2)
-      rubocop (~> 1.40)
-      rubocop-capybara (~> 2.17)
-      rubocop-factory_bot (~> 2.22)
-      rubocop-rspec_rails (~> 2.28)
-    rubocop-rspec_rails (2.28.3)
-      rubocop (~> 1.40)
-    ruby-progressbar (1.13.0)
     rubyzip (2.3.2)
     sass-rails (6.0.0)
       sassc-rails (~> 2.1, >= 2.1.1)
@@ -469,9 +440,6 @@ DEPENDENCIES
   rspec-rails
   rspec-retry
   rspec_junit_formatter
-  rubocop (= 1.61.0)
-  rubocop-performance (~> 1.20.0)
-  rubocop-rspec (~> 2.26)
   sass-rails (~> 6.0)
   sdoc
   selenium-webdriver (= 4.9.0)

data/Rakefile

@@ -13,7 +13,7 @@ desc "All actions but no examples, good for local developer run."
 task all_but_examples: ["run_rspec:all_but_examples", "lint"]
 
 desc "Prepare for ci, including node_package, dummy app, and generator examples"
-task prepare_for_ci: prepare_for_ci
+task(prepare_for_ci:)
 
 desc "Runs prepare_for_ci and tasks"
 task ci: [:prepare_for_ci, *tasks]

data/lib/generators/USAGE

@@ -8,6 +8,12 @@ The react_on_rails:install generator integrates a React frontend, including SSR,
     to integrate the Redux state container framework. The necessary node modules
     will be automatically included for you.
 
+* Tailwind CSS v4 (Optional)
+
+    Passing the --tailwind generator option installs Tailwind CSS v4, configures
+    the PostCSS plugin for Webpack or Rspack, and styles the generated
+    server-rendered Hello World example.
+
 *******************************************************************************
 
 After running the generator, you will want to:

data/lib/generators/react_on_rails/base_generator.rb

@@ -41,6 +41,12 @@ module ReactOnRails
                    type: :boolean,
                    desc: "Use Webpack as the bundler (alias for --no-rspack; --no-webpack is equivalent to --rspack)"
 
+      # --tailwind
+      class_option :tailwind,
+                   type: :boolean,
+                   default: false,
+                   desc: "Install Tailwind CSS v4 and style the generated SSR example"
+
       # --pro
       class_option :pro,
                    type: :boolean,
@@ -106,9 +112,21 @@ module ReactOnRails
           generator.__send__(:use_rsc?)
         end
 
+        def use_tailwind?
+          generator.__send__(:use_tailwind?)
+        end
+
         def shakapacker_version_9_or_higher?
           generator.__send__(:shakapacker_version_9_or_higher?)
         end
+
+        def rsc_plugin_class_name
+          generator.__send__(:rsc_plugin_class_name)
+        end
+
+        def rsc_plugin_import_path
+          generator.__send__(:rsc_plugin_import_path)
+        end
       end
 
       REMOVABLE_WEBPACK_FILES = (MANAGED_WEBPACK_FILE_TEMPLATES.keys +
@@ -220,7 +238,7 @@ module ReactOnRails
         base_files = %w[app/javascript/packs/server-bundle.js]
 
         # Skip HelloWorld CSS for Redux (uses HelloWorldApp) or RSC (uses HelloServer)
-        unless options.redux? || use_rsc?
+        unless options.redux? || use_rsc? || use_tailwind?
           base_files << "app/javascript/src/HelloWorld/ror_components/HelloWorld.module.css"
         end
 
@@ -251,6 +269,14 @@ module ReactOnRails
         copy_webpack_main_config(base_path, config)
       end
 
+      def copy_tailwind_files
+        return unless use_tailwind?
+
+        base_path = "base/tailwind/"
+        copy_file("#{base_path}app/javascript/stylesheets/application.css",
+                  "app/javascript/stylesheets/application.css")
+      end
+
       def copy_packer_config
         base_path = "base/base/"
         config = "config/shakapacker.yml"
@@ -372,8 +398,8 @@ module ReactOnRails
                    end
 
         {
-          app_name: app_name,
-          docs_url: docs_url,
+          app_name:,
+          docs_url:,
           examples: home_page_examples,
           file_hints: home_page_file_hints,
           stack_badges: home_page_stack_badges,
@@ -962,9 +988,10 @@ module ReactOnRails
           # Note: files originally generated with --pro or --rsc will not match when the
           # current run omits those options; in that case, we preserve the directory.
           # Templates rely on config[:message] plus a small helper subset exposed by
-          # TemplateRenderContext (add_documentation_reference, use_pro?, use_rsc?,
-          # shakapacker_version_9_or_higher?). Missing method delegates raise
-          # NoMethodError and are caught below, treating the file as non-removable.
+          # TemplateRenderContext (add_documentation_reference, use_pro?, use_rsc?, use_tailwind?,
+          # shakapacker_version_9_or_higher?, rsc_plugin_class_name, rsc_plugin_import_path).
+          # Missing method delegates raise NoMethodError and are caught below, treating the
+          # file as non-removable.
           # Missing config hash keys return nil silently, so any new config key
           # required by templates must be added to template_doc_config above.
           # Use TemplateRenderContext#erb_binding to avoid leaking method-local
@@ -1009,13 +1036,13 @@ module ReactOnRails
         expected_configs = shakapacker_default_configs
 
         # Check if the content matches any of the known default configurations
-        expected_configs.any? { |config| content_matches_template?(content, config, strip_comments: strip_comments) }
+        expected_configs.any? { |config| content_matches_template?(content, config, strip_comments:) }
       end
 
       def content_matches_template?(content, template, strip_comments: false)
         # Normalize whitespace and compare
-        normalize_config_content(content, strip_comments: strip_comments) ==
-          normalize_config_content(template, strip_comments: strip_comments)
+        normalize_config_content(content, strip_comments:) ==
+          normalize_config_content(template, strip_comments:)
       end
 
       def normalize_config_content(content, strip_comments: false)
@@ -1221,8 +1248,9 @@ module ReactOnRails
 
         content = File.read(shakapacker_config_path)
 
-        # Already has an active (non-commented) precompile_hook configured? Don't overwrite.
-        return if content.match?(/^\s+precompile_hook:\s*['"][^'"]+['"]/)
+        # Don't materialize placeholders when any placeholder section already has
+        # a direct or inherited active precompile_hook.
+        return if active_precompile_hook_configured?(content)
 
         # Replace the commented placeholder with the actual value
         # Shakapacker 9.x default config has: # precompile_hook: ~

data/lib/generators/react_on_rails/demo_page_config.rb

@@ -5,12 +5,12 @@ module ReactOnRails
     module DemoPageConfig # rubocop:disable Metrics/ModuleLength
       def build_hello_world_view_config(component_name:, source_path:, landing_page:, redux:, rsc_demo:)
         {
-          component_name: component_name,
+          component_name:,
           title: redux ? "Redux SSR Demo" : "React SSR Demo",
-          intro: hello_world_intro(redux: redux),
-          highlights: hello_world_highlights(redux: redux),
-          file_hints: hello_world_file_hints(source_path: source_path, redux: redux),
-          quick_links: hello_world_quick_links(landing_page: landing_page, rsc_demo: rsc_demo),
+          intro: hello_world_intro(redux:),
+          highlights: hello_world_highlights(redux:),
+          file_hints: hello_world_file_hints(source_path:, redux:),
+          quick_links: hello_world_quick_links(landing_page:, rsc_demo:),
           learning_links: hello_world_learning_links
         }
       end
@@ -22,7 +22,7 @@ module ReactOnRails
                  "component response while only client islands ship JavaScript to the browser.",
           highlights: hello_server_highlights,
           file_hints: hello_server_file_hints,
-          quick_links: hello_server_quick_links(landing_page: landing_page, redux_demo: redux_demo),
+          quick_links: hello_server_quick_links(landing_page:, redux_demo:),
           learning_links: hello_server_learning_links
         }
       end

data/lib/generators/react_on_rails/generator_helper.rb

@@ -41,7 +41,7 @@ module GeneratorHelper
       result != false
     rescue StandardError => e
       say_status :warning, "Could not add packages via package_json gem: #{e.message}", :yellow
-      say_status :warning, "Will fall back to direct npm commands.", :yellow
+      say_status :warning, "Will fall back to direct package manager commands.", :yellow
       false
     end
   end
@@ -121,6 +121,13 @@ module GeneratorHelper
     options[:rsc]
   end
 
+  # Check if Tailwind CSS should be installed and wired into the generated example.
+  #
+  # @return [Boolean] true if --tailwind is set
+  def use_tailwind?
+    options[:tailwind]
+  end
+
   # Determine if the project is using rspack as the bundler.
   #
   # Detection priority:
@@ -197,6 +204,26 @@ module GeneratorHelper
     path.sub(%r{\Aconfig/webpack/}, "config/rspack/")
   end
 
+  # RSC client-manifest plugin class name for the active bundler.
+  # Rspack uses the native `RSCRspackPlugin`; webpack uses `RSCWebpackPlugin`.
+  # Both expose the same `{ isServer, clientReferences }` API and emit the same
+  # manifest schema, so only the import path and class name differ.
+  # Shared by the base webpack-config templates and the standalone RSC migration
+  # so both paths scaffold the bundler-correct plugin from one source of truth.
+  #
+  # @return [String] "RSCRspackPlugin" when rspack, "RSCWebpackPlugin" otherwise
+  def rsc_plugin_class_name
+    using_rspack? ? "RSCRspackPlugin" : "RSCWebpackPlugin"
+  end
+
+  # `react-on-rails-rsc` subpath that exports {#rsc_plugin_class_name}.
+  #
+  # @return [String] "react-on-rails-rsc/RspackPlugin" when rspack,
+  #   "react-on-rails-rsc/WebpackPlugin" otherwise
+  def rsc_plugin_import_path
+    using_rspack? ? "react-on-rails-rsc/RspackPlugin" : "react-on-rails-rsc/WebpackPlugin"
+  end
+
   # Detect the installed React version from package.json
   # Uses VERSION_PARTS_REGEX pattern from VersionChecker for consistency
   #
@@ -319,6 +346,24 @@ module GeneratorHelper
     @pro_gem_install_deferred = true
   end
 
+  # The other bundler's plugin class name — the one this project should NOT be using.
+  # Used to detect a config left in a mixed state (e.g. a legacy `RSCWebpackPlugin` surviving
+  # in an rspack project) so diagnostics can say "wrong bundler plugin" rather than "missing".
+  #
+  # @return [String] "RSCWebpackPlugin" when rspack, "RSCRspackPlugin" otherwise
+  def inactive_rsc_plugin_class_name
+    using_rspack? ? "RSCWebpackPlugin" : "RSCRspackPlugin"
+  end
+
+  # Import path for the inactive bundler's plugin — the counterpart to {#rsc_plugin_import_path},
+  # used when migrating a legacy config to the active bundler's plugin.
+  #
+  # @return [String] "react-on-rails-rsc/WebpackPlugin" when rspack,
+  #   "react-on-rails-rsc/RspackPlugin" otherwise
+  def inactive_rsc_plugin_import_path
+    using_rspack? ? "react-on-rails-rsc/WebpackPlugin" : "react-on-rails-rsc/RspackPlugin"
+  end
+
   # NOTE: only the `default:` section is inspected — same assumption as
   # rspack_configured_in_project?. Projects that set `javascript_transpiler`
   # only in per-environment sections (without a `default:` block) will not be

data/lib/generators/react_on_rails/generator_messages/ci_section.rb

@@ -15,7 +15,7 @@ module GeneratorMessages
       # Read package.json once and reuse for both package-manager detection and the
       # build:test script presence check to avoid a second I/O pass.
       package_json = read_package_json(app_root)
-      package_manager = detect_package_manager(app_root: app_root, package_json: package_json)
+      package_manager = detect_package_manager(app_root:, package_json:)
       ci_status = if ci_workflow_generated
                     "A GitHub Actions workflow has been generated at .github/workflows/ci.yml."
                   else
@@ -30,7 +30,7 @@ module GeneratorMessages
                         end
       manual_build_command = shakapacker_build_command(
         env: "RAILS_ENV=test NODE_ENV=test",
-        app_root: app_root,
+        app_root:,
         environment: "test"
       )
 

data/lib/generators/react_on_rails/generator_messages/package_manager_detection.rb

@@ -37,8 +37,8 @@ module GeneratorMessages
     # wants detection to fall through directly to lockfile heuristics.
     def detect_package_manager(app_root: Dir.pwd, package_json: PACKAGE_JSON_UNSET)
       detect_package_manager_with_source(
-        app_root: app_root,
-        package_json: package_json
+        app_root:,
+        package_json:
       ).first
     end
 
@@ -52,13 +52,13 @@ module GeneratorMessages
       return [env_package_manager, :env] if supported_package_manager?(env_package_manager)
 
       content = package_json_content(
-        app_root: app_root,
-        package_json: package_json
+        app_root:,
+        package_json:
       )
       pm_from_json = content ? package_manager_name_from_content(content) : nil
       return [pm_from_json, :package_json] if pm_from_json
 
-      pm_from_lockfile = detect_package_manager_from_lockfiles(app_root: app_root)
+      pm_from_lockfile = detect_package_manager_from_lockfiles(app_root:)
       return [pm_from_lockfile, :lockfile] if pm_from_lockfile
 
       ["npm", :default]
@@ -84,8 +84,8 @@ module GeneratorMessages
     # package_json: nil to preserve a cached missing/unreadable read.
     def package_manager_declared?(manager:, app_root: Dir.pwd, package_json: PACKAGE_JSON_UNSET)
       content = package_json_content(
-        app_root: app_root,
-        package_json: package_json
+        app_root:,
+        package_json:
       )
       return false unless content
 
@@ -99,12 +99,12 @@ module GeneratorMessages
     # that's not on disk (e.g. `packageManager: pnpm` without `pnpm-lock.yaml`, which
     # breaks `actions/setup-node`'s cache step).
     def lockfile_for_manager?(package_manager, app_root: Dir.pwd)
-      !lockfile_filename_for(package_manager, app_root: app_root).nil?
+      !lockfile_filename_for(package_manager, app_root:).nil?
     end
 
     def detect_package_manager_from_lockfiles(app_root: Dir.pwd)
       LOCKFILE_CANDIDATES_BY_MANAGER.keys.find do |pm|
-        lockfile_for_manager?(pm, app_root: app_root)
+        lockfile_for_manager?(pm, app_root:)
       end
     end
 

data/lib/generators/react_on_rails/generator_messages/shakapacker_status_section.rb

@@ -7,7 +7,7 @@ module GeneratorMessages
     private
 
     def build_shakapacker_status_section(shakapacker_just_installed: false, app_root: Dir.pwd)
-      version_warning = check_shakapacker_version_warning(app_root: app_root)
+      version_warning = check_shakapacker_version_warning(app_root:)
       if shakapacker_just_installed
         base = <<~SHAKAPACKER
 

data/lib/generators/react_on_rails/generator_messages.rb

@@ -58,13 +58,13 @@ module GeneratorMessages
                                            rsc: false, shakapacker_just_installed: false, landing_page: false,
                                            ci_workflow_generated: false, app_root: Dir.pwd)
       process_manager_section = build_process_manager_section
-      testing_section = build_testing_section(app_root: app_root)
-      ci_section = build_ci_section(app_root: app_root, ci_workflow_generated: ci_workflow_generated)
-      package_manager = detect_package_manager(app_root: app_root)
-      shakapacker_status = build_shakapacker_status_section(shakapacker_just_installed: shakapacker_just_installed,
-                                                            app_root: app_root)
-      render_example = build_render_example(component_name: component_name, route: route, rsc: rsc)
-      render_label = build_render_label(route: route, rsc: rsc)
+      testing_section = build_testing_section(app_root:)
+      ci_section = build_ci_section(app_root:, ci_workflow_generated:)
+      package_manager = detect_package_manager(app_root:)
+      shakapacker_status = build_shakapacker_status_section(shakapacker_just_installed:,
+                                                            app_root:)
+      render_example = build_render_example(component_name:, route:, rsc:)
+      render_label = build_render_label(route:, rsc:)
       normalized_route = route.to_s.sub(%r{\A/+}, "")
       visit_url = if landing_page || normalized_route.empty?
                     "http://localhost:3000"

data/lib/generators/react_on_rails/install_generator.rb

@@ -43,6 +43,12 @@ module ReactOnRails
                    desc: "Generate TypeScript files and install TypeScript dependencies. Default: false",
                    aliases: "-T"
 
+      # --tailwind
+      class_option :tailwind,
+                   type: :boolean,
+                   default: false,
+                   desc: "Install Tailwind CSS v4 and style the generated SSR example. Default: false"
+
       # --rspack / --no-rspack (Rspack is the default on fresh installs; --no-rspack selects Webpack)
       # IMPORTANT: do NOT add a `default:` here. The absence of a default is load-bearing — Thor
       # only includes :rspack in the options hash when the flag is explicitly passed, which is how
@@ -66,6 +72,15 @@ module ReactOnRails
                    default: false,
                    desc: "Skip warnings. Default: false"
 
+      # --agent-files / --no-agent-files
+      # Emits consumer-scoped AI-agent guidance (AGENTS.md) plus thin editor pointer
+      # files (CLAUDE.md, .cursor/rules/react-on-rails.mdc, .github/copilot-instructions.md).
+      # Default ON; pass --no-agent-files to skip. Existing files are never overwritten.
+      class_option :agent_files,
+                   type: :boolean,
+                   default: true,
+                   desc: "Write AI-agent guidance files (AGENTS.md + editor pointers). Default: true"
+
       # --pro
       class_option :pro,
                    type: :boolean,
@@ -183,6 +198,7 @@ module ReactOnRails
           add_package_json_scripts
           add_ci_workflow
           add_bin_scripts
+          add_agent_files
           add_post_install_message
         else
           error = <<~MSG.strip
@@ -227,7 +243,7 @@ module ReactOnRails
         # --pretend/--force/--skip must be forwarded explicitly at each boundary.
         invoke "react_on_rails:base", [],
                { typescript: options.typescript?, redux: options.redux?, rspack: using_rspack?,
-                 pro: use_pro?, rsc: use_rsc?, new_app: options.new_app?,
+                 pro: use_pro?, rsc: use_rsc?, tailwind: use_tailwind?, new_app: options.new_app?,
                  shakapacker_just_installed: shakapacker_just_installed?,
                  force: options[:force], skip: options[:skip], pretend: options[:pretend] }
 
@@ -237,6 +253,7 @@ module ReactOnRails
         # - Without --rsc: Normal behavior (HelloWorld or HelloWorldApp based on --redux)
         if options.redux?
           invoke "react_on_rails:react_with_redux", [], { typescript: options.typescript?,
+                                                          tailwind: use_tailwind?,
                                                           invoked_by_install: true,
                                                           new_app: options.new_app?,
                                                           rsc: use_rsc?,
@@ -246,6 +263,7 @@ module ReactOnRails
           # Only generate HelloWorld if RSC is not enabled
           # For RSC, HelloServer replaces HelloWorld as the example component
           invoke "react_on_rails:react_no_redux", [], { typescript: options.typescript?,
+                                                        tailwind: use_tailwind?,
                                                         new_app: options.new_app?,
                                                         force: options[:force], skip: options[:skip],
                                                         pretend: options[:pretend] }
@@ -265,6 +283,7 @@ module ReactOnRails
 
         invoke "react_on_rails:rsc", [], { typescript: options.typescript?, invoked_by_install: true,
                                            new_app: options.new_app?, redux: options.redux?,
+                                           tailwind: use_tailwind?,
                                            force: options[:force], skip: options[:skip],
                                            pretend: options[:pretend] }
       end
@@ -294,7 +313,7 @@ module ReactOnRails
         package_json = GeneratorMessages.read_package_json(destination_root)
         package_manager = GeneratorMessages.detect_package_manager(
           app_root: destination_root,
-          package_json: package_json
+          package_json:
         )
         # Scope the lockfile check to the detected manager: a generic "any lockfile exists" check
         # would emit `cache: "pnpm"` in CI when only `yarn.lock` is on disk, breaking setup-node.
@@ -307,16 +326,16 @@ module ReactOnRails
                                 GeneratorMessages.package_manager_declared?(
                                   app_root: destination_root,
                                   manager: "pnpm",
-                                  package_json: package_json
+                                  package_json:
                                 )
         has_active_record = File.exist?(File.join(destination_root, "config/database.yml"))
         has_rspec = File.exist?(File.join(destination_root, "spec/rails_helper.rb")) ||
                     File.exist?(File.join(destination_root, "spec/spec_helper.rb"))
         template("templates/base/base/.github/workflows/ci.yml.tt", ci_path,
-                 { package_manager: package_manager, has_lockfile: has_lockfile,
-                   pnpm_version_declared: pnpm_version_declared,
+                 { package_manager:, has_lockfile:,
+                   pnpm_version_declared:,
                    pnpm_fallback_version: CI_PNPM_FALLBACK_VERSION,
-                   has_active_record: has_active_record, has_rspec: has_rspec,
+                   has_active_record:, has_rspec:,
                    precompile_hook_command: shakapacker_precompile_hook_command(environment: "test") })
         @ci_workflow_generated = true
       end
@@ -442,7 +461,7 @@ module ReactOnRails
         content = JSON.parse(original_text)
         content["scripts"] = existing_scripts.merge(scripts_to_add)
         indent = original_text[/\A\{\n(\s+)/, 1] || "  "
-        "#{JSON.pretty_generate(content, indent: indent)}\n"
+        "#{JSON.pretty_generate(content, indent:)}\n"
       end
 
       def ensure_jsx_in_js_compatibility
@@ -622,6 +641,40 @@ module ReactOnRails
         File.chmod(0o755, *files_to_become_executable)
       end
 
+      # Consumer-scoped AI-agent guidance written into the generated app. The canonical
+      # AGENTS.md content lives in templates/agent_files/ and is the single source of truth;
+      # create-react-on-rails-app gets it for free because it delegates to this generator.
+      # Each file is copied only when absent so we never clobber an app's existing agent files.
+      AGENT_FILES = %w[
+        AGENTS.md
+        CLAUDE.md
+        .cursor/rules/react-on-rails.mdc
+        .github/copilot-instructions.md
+      ].freeze
+      private_constant :AGENT_FILES
+
+      def add_agent_files
+        return unless options.agent_files?
+
+        # AGENTS.md is the canonical file the editor pointers (CLAUDE.md, Cursor, Copilot) all
+        # reference. If the app already has its own AGENTS.md, it may document unrelated
+        # conventions, so leave it untouched AND skip the pointer files rather than emit editor
+        # guidance pointing at an AGENTS.md we did not write.
+        if File.exist?(File.join(destination_root, "AGENTS.md"))
+          say_status :skip, "AGENTS.md already exists; leaving it and the editor pointer files untouched", :yellow
+          return
+        end
+
+        AGENT_FILES.each do |relative_path|
+          if File.exist?(File.join(destination_root, relative_path))
+            say_status :skip, "#{relative_path} already exists; leaving it untouched", :yellow
+            next
+          end
+
+          copy_file("templates/agent_files/#{relative_path}", relative_path)
+        end
+      end
+
       def replace_stock_rails_bin_dev!
         @preserve_existing_bin_dev = false
 
@@ -690,8 +743,8 @@ module ReactOnRails
         end
 
         GeneratorMessages.add_info(GeneratorMessages.helpful_message_after_installation(
-                                     component_name: component_name,
-                                     route: route,
+                                     component_name:,
+                                     route:,
                                      pro: use_pro?,
                                      rsc: use_rsc?,
                                      shakapacker_just_installed: shakapacker_just_installed?,
@@ -722,6 +775,10 @@ module ReactOnRails
           flags << "--pro"
         end
 
+        # Preserve an explicit agent-files opt-out so the suggested re-run doesn't emit
+        # AGENTS.md/editor files a user deliberately skipped (--agent-files defaults to on).
+        flags << "--no-agent-files" unless options.agent_files?
+
         ["rails generate react_on_rails:install", *flags].join(" ")
       end