rails-ai-context 5.26.0 → 5.28.0

data/exe/rails-ai-context

@@ -191,6 +191,16 @@ class RailsAiContextCLI < Thor
       end
       ::RailsAiContext::LegacyCleanup.prompt_legacy_files(cleanup_tools, root: Dir.pwd)
 
+      # An explicit --format names a file, so it is written either way. With
+      # no format and an MCP-only install there is nothing to write, and the
+      # rake surface says the same thing in the same words.
+      if options[:format].nil? && !::RailsAiContext.configuration.context_files
+        $stderr.puts "MCP-only install (config.context_files = false): no context files written."
+        $stderr.puts "Run `rails-ai-context context --format claude` to write one anyway, " \
+                     "or set config.context_files = true."
+        return
+      end
+
       $stderr.puts "Introspecting Rails app..."
 
       # An explicit --format overrides the recorded selection.
@@ -264,6 +274,8 @@ class RailsAiContextCLI < Thor
 
     desc "init", "Set up rails-ai-context for standalone use (creates .rails-ai-context.yml and .mcp.json)"
     option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
+    option :mcp_only, type: :boolean, default: false,
+      desc: "Write the MCP config and nothing else: no CLAUDE.md, AGENTS.md, rules files or .ai-context.json"
     def init
       unless entry_boot.app_present?(Dir.pwd, allow_source_only: true)
         $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
@@ -278,7 +290,9 @@ class RailsAiContextCLI < Thor
 
       # --- Prompts (no Rails needed) ---
       ai_tools = prompt_ai_tools
-      tool_mode = prompt_tool_mode
+      setup = prompt_setup
+      tool_mode = setup.tool_mode
+      context_files = setup.context_files
 
       # --- Cleanup removed tools ---
       cleanup_removed_tools(previous_tools, ai_tools) if previous_tools&.any?
@@ -287,13 +301,13 @@ class RailsAiContextCLI < Thor
       ::RailsAiContext::LegacyCleanup.prompt_legacy_files(ai_tools, root: Dir.pwd)
 
       # --- Record the selection (YAML, plus the initializer line) ---
-      record_selection(ai_tools, tool_mode)
+      record_selection(ai_tools, tool_mode, context_files)
 
       # --- Write per-tool MCP config files (MCP mode only) ---
       write_mcp_configs(ai_tools, tool_mode)
 
       # --- Add .ai-context.json to .gitignore ---
-      add_to_gitignore
+      add_to_gitignore(context_files)
 
       # --- Boot Rails, load config, generate context ---
       # The config files are already on disk by now, so failing here leaves the
@@ -301,12 +315,17 @@ class RailsAiContextCLI < Thor
       # what you run on a repo you have just cloned.
       boot_rails!(command: "init", allow_static: true)
 
-      $stderr.puts ""
-      $stderr.puts "Generating AI context files..."
-      print_context_result(::RailsAiContext.generate_context(format: ai_tools))
+      if context_files
+        $stderr.puts ""
+        $stderr.puts "Generating AI context files..."
+        print_context_result(::RailsAiContext.generate_context(format: ai_tools))
+      else
+        $stderr.puts ""
+        $stderr.puts "MCP-only setup: no context files written."
+      end
 
       # --- Instructions ---
-      show_standalone_instructions(ai_tools, tool_mode)
+      show_standalone_instructions(ai_tools, tool_mode, context_files)
     end
 
     desc "preset NAME", "Run a multi-tool preset (architecture, debugging, migration)"
@@ -367,8 +386,12 @@ class RailsAiContextCLI < Thor
       ::RailsAiContext::Install::Program.select_ai_tools(program_surface)
     end
 
-    def prompt_tool_mode
-      ::RailsAiContext::Install::Program.select_tool_mode(program_surface)
+    def prompt_setup
+      if options[:mcp_only]
+        return ::RailsAiContext::Install::Program::Setup.new(:mcp, false)
+      end
+
+      ::RailsAiContext::Install::Program.select_setup(program_surface)
     end
 
     def read_previous_ai_tools
@@ -381,14 +404,17 @@ class RailsAiContextCLI < Thor
       )
     end
 
-    def add_to_gitignore
-      ::RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Dir.pwd)
+    def add_to_gitignore(context_files = true)
+      ::RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Dir.pwd,
+                                                       context_files: context_files)
     end
 
-    def record_selection(ai_tools, tool_mode)
+    def record_selection(ai_tools, tool_mode, context_files = true)
       result = ::RailsAiContext::Install::SelectionRecord.write(
-        ai_tools, root: Dir.pwd, extra_yaml: { "tool_mode" => tool_mode.to_s }
+        ai_tools, root: Dir.pwd,
+        extra_yaml: { "tool_mode" => tool_mode.to_s, "context_files" => context_files }
       )
+      ::RailsAiContext::Install::SelectionRecord.write_context_files(context_files, root: Dir.pwd)
 
       ::RailsAiContext::Install::SelectionRecord.messages(result).each do |level, text|
         $stderr.puts(level == :warn ? "Warning: #{text}" : text)
@@ -402,7 +428,7 @@ class RailsAiContextCLI < Thor
       )
     end
 
-    def show_standalone_instructions(ai_tools, tool_mode)
+    def show_standalone_instructions(ai_tools, tool_mode, context_files = true)
       $stderr.puts ""
       $stderr.puts "=" * 50
       $stderr.puts " rails-ai-context initialized!"
@@ -411,11 +437,15 @@ class RailsAiContextCLI < Thor
       $stderr.puts "Your setup:"
       ::RailsAiContext::Install::AiTool.all.each do |tool|
         next unless ai_tools.include?(tool.key)
-        $stderr.puts "  #{tool.name.ljust(16)} -> #{tool.files}"
+        $stderr.puts "  #{tool.name.ljust(16)} -> #{context_files ? tool.files : 'MCP config only'}"
+      end
+      unless context_files
+        $stderr.puts ""
+        $stderr.puts "  Left alone on purpose: CLAUDE.md, AGENTS.md, the rules directories and .ai-context.json."
       end
       $stderr.puts ""
       $stderr.puts "Commands:"
-      $stderr.puts "  rails-ai-context context    # Regenerate context files"
+      $stderr.puts "  rails-ai-context context    # Regenerate context files" if context_files
       $stderr.puts "  rails-ai-context tool NAME  # Run any of the #{RailsAiContext::CountPhrase.call(builtin_tool_count, "tool")}"
       if tool_mode == :mcp
         $stderr.puts "  rails-ai-context serve      # Start MCP server"
@@ -562,11 +592,20 @@ class RailsAiContextCLI < Thor
         install/program mcp_config_generator legacy_cleanup
       ].each { |file| require_relative "../lib/rails_ai_context/#{file}" }
 
-      return if ::RailsAiContext.respond_to?(:log_warn)
+      # Both are defined in the entry file, which is the thing that must not
+      # load yet. With no Rails in the process log_warn only writes to stderr.
+      unless ::RailsAiContext.respond_to?(:log_warn)
+        ::RailsAiContext.define_singleton_method(:log_warn) { |message| $stderr.puts(message) }
+      end
+
+      return if ::RailsAiContext.respond_to?(:debug_fail)
 
-      # Defined in the entry file, which is the thing that must not load yet.
-      # With no Rails in the process it only writes to stderr.
-      ::RailsAiContext.define_singleton_method(:log_warn) { |message| $stderr.puts(message) }
+      # Every rescue in the files above routes through this, so without it a
+      # rescue that fires raises NoMethodError over the error it was catching.
+      ::RailsAiContext.define_singleton_method(:debug_fail) do |error, fallback = nil, label:|
+        $stderr.puts("[rails-ai-context] #{label} failed: #{error.message}") if ENV["DEBUG"]
+        fallback
+      end
     end
 end
 

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -38,6 +38,9 @@ module RailsAiContext
       class_option :defaults, type: :boolean, default: false,
         desc: "Skip all interactive prompts and use each prompt's documented default (for CI/non-interactive use)"
 
+      class_option :mcp_only, type: :boolean, default: false,
+        desc: "Write the MCP config and nothing else: no CLAUDE.md, AGENTS.md, rules files or .ai-context.json"
+
       BARE_GUARD_PATTERN = RailsAiContext::Install::InitializerFile::BARE_GUARD
 
       def select_ai_tools
@@ -54,8 +57,16 @@ module RailsAiContext
         )
       end
 
-      def select_tool_mode
-        @tool_mode = RailsAiContext::Install::Program.select_tool_mode(program_surface)
+      def select_setup
+        if options[:mcp_only]
+          @tool_mode = :mcp
+          @context_files = false
+          return
+        end
+
+        setup = RailsAiContext::Install::Program.select_setup(program_surface)
+        @tool_mode = setup.tool_mode
+        @context_files = setup.context_files
       end
 
       def create_mcp_config
@@ -79,6 +90,11 @@ module RailsAiContext
             #   :mcp - MCP primary + CLI fallback (default, requires `rails ai:serve`)
             #   :cli - CLI only (no MCP server needed, uses `rails 'ai:tool[NAME]'`)
             # config.tool_mode = :mcp
+
+            # Whether this gem writes context files at all. false is MCP-only:
+            # the server and the CLI still answer, and CLAUDE.md, AGENTS.md,
+            # the rules directories and .ai-context.json are left alone.
+            # config.context_files = true
         SECTION
         "Introspection" => <<~SECTION,
             # ── Introspection ─────────────────────────────────────────────────
@@ -261,11 +277,7 @@ module RailsAiContext
         # Always write uncommented so re-install can detect previous selection
         tools_line = RailsAiContext::Install::SelectionRecord.initializer_line(@selected_formats)
 
-        tool_mode_line = if @tool_mode == :cli
-          "  config.tool_mode = :cli    # CLI only (no MCP server needed)"
-        else
-          "  config.tool_mode = :mcp   # MCP primary + CLI fallback"
-        end
+        tool_mode_line = build_tool_mode_line
 
         content = "# frozen_string_literal: true\n\nRailsAiContext.configure do |config|\n"
 
@@ -280,6 +292,7 @@ module RailsAiContext
             #   :mcp - MCP primary + CLI fallback (default, requires `rails ai:serve`)
             #   :cli - CLI only (no MCP server needed, uses `rails 'ai:tool[NAME]'`)
           #{tool_mode_line}
+          #{build_context_files_line}
 
         SECTION
 
@@ -312,7 +325,11 @@ module RailsAiContext
         existing, changed = update_config_line(existing, "config.tool_mode", build_tool_mode_line)
         changes << "tool_mode" if changed
 
-        # 3. Add any missing config sections
+        # 3. Record whether this install writes context files at all
+        existing, changed = update_config_line(existing, "config.context_files", build_context_files_line)
+        changes << "context_files" if changed
+
+        # 4. Add any missing config sections
         CONFIG_SECTIONS.each do |name, section_content|
           marker = "── #{name}"
           next if existing.include?(marker)
@@ -423,6 +440,20 @@ module RailsAiContext
         end
       end
 
+      # Written uncommented either way, so a re-run reads the same answer the
+      # last one recorded.
+      def build_context_files_line
+        if context_files?
+          "  config.context_files = true   # write CLAUDE.md, AGENTS.md and rules files"
+        else
+          "  config.context_files = false  # MCP only: no context files are written"
+        end
+      end
+
+      def context_files?
+        @context_files.nil? ? true : @context_files
+      end
+
       def read_previous_ai_tools
         RailsAiContext::Install::SelectionRecord.read(root: Rails.root)
       end
@@ -435,7 +466,7 @@ module RailsAiContext
         # comment behind. One writer per file, and it is not this call.
         result = RailsAiContext::Install::SelectionRecord.write(
           @selected_formats, root: Rails.root,
-          extra_yaml: { "tool_mode" => @tool_mode.to_s },
+          extra_yaml: { "tool_mode" => @tool_mode.to_s, "context_files" => context_files? },
           initializer: false
         )
 
@@ -445,7 +476,8 @@ module RailsAiContext
       end
 
       def add_to_gitignore
-        RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Rails.root)
+        RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Rails.root,
+                                                        context_files: context_files?)
       end
 
       def install_validation_hook
@@ -505,6 +537,12 @@ module RailsAiContext
       end
 
       def generate_context_files
+        unless context_files?
+          say ""
+          say "MCP-only install: no context files written.", :yellow
+          return
+        end
+
         say ""
         say "Generating AI context files...", :yellow
 
@@ -540,7 +578,12 @@ module RailsAiContext
         say "Your setup:", :yellow
         RailsAiContext::Install::AiTool.all.each do |tool|
           next unless @selected_formats.include?(tool.key)
-          say "  ✅ #{tool.name.ljust(16)} -> #{tool.files}"
+          files = context_files? ? tool.files : "MCP config only"
+          say "  ✅ #{tool.name.ljust(16)} -> #{files}"
+        end
+        unless context_files?
+          say ""
+          say "  Left alone on purpose: CLAUDE.md, AGENTS.md, the rules directories and .ai-context.json.", :yellow
         end
         say ""
         say "Commands:", :yellow

data/lib/rails_ai_context/action_filters.rb

@@ -55,7 +55,11 @@ module RailsAiContext
         .reject { |f| inherited_skips.include?(f[:name].to_s) && !f[:declared] }
       # Keyed by kind and name: `after_action :audit` and `before_action :audit`
       # are two entries in the chain and Rails runs both.
-      declared_on = parent.to_h { |f| [ entry_key(f), f[:from] ] }
+      # The whole ancestor entry, not only its `from:`: an entry the walk
+      # could not attribute carries `provenance` instead, and merging only
+      # `from` dropped that on the tier the label exists for.
+      attribution_of = parent.to_h { |f| [ entry_key(f), f.slice(:from, :provenance) ] }
+      declared_on = attribution_of
       declared_names = declared.map { |f| entry_key(f) }.to_set
 
       # A filter this body declares is its own, whatever an ancestor declares
@@ -66,7 +70,7 @@ module RailsAiContext
       inherited = mark_conditional_skips(
         parent.reject { |f| declared_names.include?(entry_key(f)) } +
           applicable.select(&inherited_here)
-            .map { |f| f.merge(from: declared_on[entry_key(f)]) }, conditions, action
+            .map { |f| f.except(:from, :provenance).merge(attribution_of[entry_key(f)]) }, conditions, action
       )
 
       { own: own,
@@ -178,11 +182,17 @@ module RailsAiContext
       attributed = Set.new
       conditions = {}
       declares = Set.new
+      # Where in the walk each entry was first seen, so the list can be
+      # emitted root first while the order inside one class is kept.
+      positions = {}
+      evidence = {}
+      depth = 0
       dropped = skipped.map(&:to_s).to_set
       name = Introspectors::ActionResolver.resolve_entry_name(controllers, parent_class, within)
 
       while name && !seen.include?(name)
         seen << name
+        depth += 1
         info = controllers[name]
         source = info.is_a?(Hash) ? nil : base_controller_source(name, root)
         info ||= { filters: Introspectors::ControllerFilters.from_source(source) } if source
@@ -201,29 +211,56 @@ module RailsAiContext
         # the walk did see is never mistaken for a skip of a declaration it
         # could not. A skip record is not a sighting, hence the reject above.
         declares.merge(carried.map { |f| f[:name].to_s })
+        # Whether this class's own body was read at all. Without that, an
+        # unmarked filter is a filter nobody could check, not one a gem
+        # installed - an engine's ApplicationController and a concern-only
+        # payload both land there, and dropping their attribution would lose
+        # the answer rather than correct it.
+        body_known = carried.any? { |f| f[:declared] }
         carried.select { |f| applies?(f, action) }
           .reject { |f| dropped.include?(f[:name].to_s) }
-          .each { |f| record_attribution(found, attributed, f, name) }
+          .each { |f| record_attribution(found, attributed, f, name, positions, depth, evidence, body_known) }
 
         name = Introspectors::ActionResolver.resolve_entry_name(controllers, info[:parent_class], name)
       end
 
-      [ found.values, dropped, conditions, declares ]
+      [ run_order(found, attributed, positions, evidence), dropped, conditions, declares ]
     end
 
     # The closest ancestor carrying a filter keeps its constraints, but a
     # booted ancestor carries names it only inherits, so `from:` moves on to
     # the first ancestor whose own body declared it.
-    def record_attribution(found, attributed, filter, ancestor)
+    def record_attribution(found, attributed, filter, ancestor, positions = {}, depth = 0,
+                           evidence = {}, body_known = false)
       key = entry_key(filter)
       if found.key?(key)
         found[key] = found[key].merge(from: ancestor) if filter[:declared] && !attributed.include?(key)
       else
         found[key] = filter.merge(from: ancestor)
+        positions[key] = depth
+        evidence[key] = body_known
       end
       attributed << key if filter[:declared]
     end
 
+    # Rails runs the root's callbacks first, so the inherited list reads that
+    # way: the walk's class order reversed, each class's own order kept. A
+    # filter no ancestor's body declares is installed from somewhere else -
+    # a gem's `on_load :action_controller` block, the framework, a concern -
+    # and crediting it to the nearest app class sent an agent to a file that
+    # never mentions it.
+    def run_order(found, attributed, positions, evidence = {})
+      found.keys
+        .each_with_index
+        .sort_by { |key, index| [ -positions.fetch(key, 0), index ] }
+        .map do |key, _|
+          entry = found[key]
+          next entry if attributed.include?(key) || !evidence[key]
+
+          entry.merge(from: nil, provenance: "not declared in the controller chain").compact
+        end
+    end
+
     # One entry in the chain. A skip names a filter by name, and a chain entry
     # is a kind and a name: a class can declare both `before_action :audit` and
     # `after_action :audit`, and both run.
@@ -308,8 +345,7 @@ module RailsAiContext
           end
       end.uniq { |skip| skip[:name] }
     rescue => e
-      $stderr.puts "[rails-ai-context] ActionFilters skip_source_records failed: #{e.message}" if ENV["DEBUG"]
-      []
+      RailsAiContext.debug_fail(e, [], label: "ActionFilters skip_source_records")
     end
 
     # ApplicationController is deliberately not in the listing: it would sit in

data/lib/rails_ai_context/boot_manager.rb

@@ -39,11 +39,32 @@ module RailsAiContext
         status == :booted
       end
 
-      # One-line summary safe to relay to an AI client or a terminal.
+      # Bundler::GemRequireError names the gem it failed to require and
+      # nothing about why; the incompatibility that actually raised is in
+      # `cause`. Walk to the deepest one, capped so a cycle cannot hang.
+      def root_cause
+        cause = error&.cause
+        10.times do
+          break unless cause&.cause
+
+          cause = cause.cause
+        end
+        cause
+      end
+
+      # One-line summary safe to relay to an AI client or a terminal. It
+      # carries the cause too: the footer this feeds is the only place most
+      # callers ever see, and a gem name with no reason is not actionable.
       def failure_summary
         return nil if booted?
 
-        "#{error.class}: #{error.message.to_s.lines.first&.strip}"
+        summary = one_line(error)
+        cause = root_cause
+        cause ? "#{summary} (cause: #{one_line(cause)})" : summary
+      end
+
+      def one_line(e)
+        "#{e.class}: #{e.message.to_s.lines.first&.strip}"
       end
 
       # An unguarded `RailsAiContext.configure` in config/initializers has

data/lib/rails_ai_context/cli/entry_boot.rb

@@ -129,6 +129,12 @@ module RailsAiContext
         messages << "  #{result.failure_summary}"
         if ENV["DEBUG"]
           Array(result.error.backtrace).first(15).each { |line| messages << "    #{line}" }
+          # The wrapper's frames stop at the require; the frames that name the
+          # incompatible call are the cause's.
+          if (cause = result.root_cause)
+            messages << "  Raised by:"
+            Array(cause.backtrace).first(15).each { |line| messages << "    #{line}" }
+          end
         else
           messages << "  Run with DEBUG=1 for the full backtrace."
         end

data/lib/rails_ai_context/cli/tool_runner.rb

@@ -218,9 +218,9 @@ module RailsAiContext
                 # `--files=a.rb b.rb` is the same call as `--files a.rb b.rb`;
                 # honouring only one of the two spellings docs/CLI.md teaches
                 # left the other still dropping every file after the first.
-                trailing = collect_array_values(args, i + 1)
+                trailing, consumed = array_values(args, i + 1)
                 result[key] = Array(coerce_value(value, prop, key)) + trailing
-                i += 1 + values_consumed(args, i + 1)
+                i += 1 + consumed
                 next
               end
               result[key] = coerce_value(value, prop, key)
@@ -244,21 +244,12 @@ module RailsAiContext
                 next
               end
 
-              if prop[:type] == "array"
-                values = collect_array_values(args, i + 1)
-                unless values.empty?
-                  result[key] = values
-                  i += 1 + values_consumed(args, i + 1)
-                  next
-                end
-              end
-
               # A bare `--files` with nothing after it is a mistake, not a
               # request for `files: true` - an array param holding a Boolean
               # reaches the tool as a type it never accepts.
               if prop[:type] == "array"
-                result[key] = []
-                i += 1
+                result[key], consumed = array_values(args, i + 1)
+                i += 1 + consumed
                 next
               end
 
@@ -335,15 +326,12 @@ module RailsAiContext
       # stopping at a rake-style `key=value` token so `--include a model=Post`
       # does not swallow the second parameter. Each token is still
       # comma-split, so the documented `a.rb,b.rb` form keeps working and
-      # mixing the two spellings does not fabricate a path.
-      def collect_array_values(args, from)
-        args[from..].to_a
-            .take_while { |a| !a.start_with?("--") && !a.include?("=") }
-            .flat_map { |a| Array(coerce_value(a, { type: "array" })) }
-      end
-
-      def values_consumed(args, from)
-        args[from..].to_a.take_while { |a| !a.start_with?("--") && !a.include?("=") }.size
+      # mixing the two spellings does not fabricate a path. The token count
+      # comes back with the values because the cursor advances by tokens: a
+      # comma token yields more values than it consumed.
+      def array_values(args, from)
+        tokens = args[from..].to_a.take_while { |a| !a.start_with?("--") && !a.include?("=") }
+        [ tokens.flat_map { |a| Array(coerce_value(a, { type: "array" })) }, tokens.size ]
       end
 
       # Coerce a string value to the type specified in the JSON Schema property.

data/lib/rails_ai_context/concern_macros.rb

@@ -88,8 +88,7 @@ module RailsAiContext
         # A permission bit, a directory in place of a file and a bug in a
         # listener all land in `unresolved` alike, so the cause is worth
         # saying where the booted walk already says it.
-        $stderr.puts "[rails-ai-context] concern introspection failed for #{path}: #{e.message}" if ENV["DEBUG"]
-        nil
+        RailsAiContext.debug_fail(e, nil, label: "concern introspection of #{path}")
       end
 
       def tagged(entry, concern_name)

data/lib/rails_ai_context/concern_paths.rb

@@ -23,7 +23,12 @@ module RailsAiContext
       configured = RailsAiContext.configuration.concern_paths
       dirs =
         if configured.nil?
-          Dir.glob(File.join(root, "app", "*", "concerns"))
+          # Every app tree the app has, not just the one at the root: a
+          # packwerk pack or an in-repo engine keeps its own app/*/concerns.
+          # `dirs_for` cannot take the glob directly - it tests each candidate
+          # with `Dir.exist?`, which a literal `app/*/concerns` never passes -
+          # so the app trees are resolved first and globbed here.
+          PathResolver.dirs_for(root, "app").flat_map { |app_dir| Dir.glob(File.join(app_dir, "*", "concerns")) }
         else
           # A path that is already absolute is taken as given; `File.join`
           # would graft it onto the root and point at nothing.

data/lib/rails_ai_context/configuration.rb

@@ -13,7 +13,7 @@ module RailsAiContext
 
     # All YAML-supported keys (explicit allowlist for safety)
     YAML_KEYS = %i[
-      ai_tools tool_mode preset context_mode generate_root_files claude_max_lines
+      ai_tools tool_mode preset context_mode context_files generate_root_files claude_max_lines
       anti_hallucination_rules
       server_name cache_ttl max_tool_response_chars
       live_reload live_reload_debounce auto_mount http_path http_bind http_port
@@ -256,6 +256,12 @@ module RailsAiContext
     # for the security review that changed the default.
     attr_accessor :instrumentation_include_arguments
 
+    # Whether this gem writes context files at all. False is MCP-only: the
+    # server and the CLI still answer, and no CLAUDE.md, AGENTS.md, rules
+    # file or .ai-context.json is written or touched. Narrower than
+    # `generate_root_files`, which still writes the split rule files.
+    attr_accessor :context_files
+
     # Whether to generate root-level context files (CLAUDE.md, AGENTS.md, etc.)
     # When false, only generates split rule files (.claude/rules/, .cursor/rules/, etc.)
     attr_accessor :generate_root_files
@@ -408,6 +414,7 @@ module RailsAiContext
       @live_reload              = :auto
       @live_reload_debounce     = 1.5
       @instrumentation_include_arguments = false
+      @context_files            = true
       @generate_root_files      = true
       @anti_hallucination_rules = true
       @max_file_size            = 5_000_000

data/lib/rails_ai_context/detail_level.rb

@@ -15,10 +15,13 @@ module RailsAiContext
 
     ORDER = { SUMMARY => 0, STANDARD => 1, FULL => 2 }.freeze
 
-    # The enum tools publish in their input schema, so the advertised values
-    # and the normalizer cannot drift apart. Spelling the values in a tool
-    # instead fails the enum-ownership spec.
-    SCHEMA_ENUM = ALL
+    # The `detail` property tools publish in their input schema. Tools pass
+    # their own wording and get the type and the enum from here, so the
+    # advertised values and the normalizer cannot drift apart. Spelling the
+    # values in a tool instead fails the enum-ownership spec.
+    def self.schema(description)
+      { type: "string", enum: ALL, description: description }
+    end
 
     def self.valid?(detail)
       ALL.include?(detail.to_s)

data/lib/rails_ai_context/doctor.rb

@@ -197,6 +197,10 @@ module RailsAiContext
     end
 
     def check_context_freshness
+      # An MCP-only install asked for no context files, so their absence is
+      # the configuration working, not something to fix.
+      return nil unless RailsAiContext.configuration.context_files
+
       ai_tools = configured_ai_tools
 
       # Find the first existing context file or split rule directory for configured tools
@@ -440,8 +444,7 @@ module RailsAiContext
           fix: introspector_failure_hint(failures))
       end
     rescue StandardError, ScriptError => e
-      $stderr.puts "[rails-ai-context] check_introspector_health failed: #{e.message}" if ENV["DEBUG"]
-      nil
+      RailsAiContext.debug_fail(e, nil, label: "check_introspector_health")
     end
 
     MAX_SHOWN_FAILURES = 3

data/lib/rails_ai_context/erb_source.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # The Ruby inside ERB tags. Two readers need it for different reasons - a
+  # template's ivars, and the ENV names a `.yml` or a view reads - and a
+  # second copy of the tag regex is a second answer to "what is a tag".
+  module ErbSource
+    TAG = /<%={0,2}-?(.*?)-?%>/m
+
+    module_function
+
+    # @return [Boolean] whether the source carries any ERB tag at all
+    def tagged?(source)
+      source.to_s.include?("<%")
+    end
+
+    # The tag bodies, joined. Order is kept; line numbers are not.
+    def tag_bodies(source)
+      source.to_s.scan(TAG).flatten.join("\n")
+    end
+
+    # The same Ruby with everything outside the tags blanked rather than
+    # dropped, so a line number in the result is still the line in the file.
+    # A `<%#` comment is blanked too.
+    def ruby_in_place(source)
+      text = source.to_s
+      out = +""
+      last = 0
+      text.to_enum(:scan, TAG).each do
+        match = Regexp.last_match
+        out << blank(text[last...match.begin(0)])
+        body = match[1].to_s
+        out << (body.lstrip.start_with?("#") ? blank(body) : body)
+        last = match.end(0)
+      end
+      out << blank(text[last..].to_s)
+      out
+    end
+
+    def blank(text)
+      text.gsub(/[^\n]/, " ")
+    end
+    private_class_method :blank
+  end
+end