rails-ai-context 5.27.0 → 5.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44038590682c51bc7722a4a5b587ee31b5b78f3842575b6386390a584038b81e
-  data.tar.gz: 4c7de07da1f44144291ba86e9bfc34ab3a3da893c0a159b8cfe99de284d3d3be
+  metadata.gz: 78848e75315236681b6b31bba337665e75a143d862d2d1ff828f48f50b1756f5
+  data.tar.gz: 8af5164b8ee4ea9900d82450d2a74905dcf1b831c02d7ba95c5c869274c18e9e
 SHA512:
-  metadata.gz: b581d96cb4ff655823a103c21527a53ddb71c3cb36d644a59485a796693001e247f6480b381d1f54ea8ec0995e175aa0389109fe1155bfbeea2dfeefd5566d9c
-  data.tar.gz: 61c4aa682dd49afaf780652300f41de2216a0bfbe0b6ed7e6ec188237c63eade5036fe2051ba6771f89e96803a0971811230e532a7c623d7a25d0bfb1f069df8
+  metadata.gz: 6dbfa116e75a4675314e6c4a06ada6c2c7d7b8c7f0d9fb5ca0abe9945add65f1729b0101200debf5c25ea2190e66b57f41761b4307d8414d77ccfc62dc292e9d
+  data.tar.gz: 86984bc5566480da28d88b7ef475138bb85c9ba459fcd87e58f8a4afd03239a365ee30d032412701291ec0bd60f7f0e0cccfa882fee0150e6baed74c966a33b1

data/CHANGELOG.md

@@ -5,6 +5,195 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.28.0] - 2026-09-22
+
+Thirty-six changes an architecture survey of v5.27.0 asked for, nine of them
+defects where a user got a wrong answer, plus what three review rounds found in
+the fixes themselves.
+
+### Added
+
+- **Services, helpers, jobs and concerns are found wherever the app keeps
+  them.** The four tools globbed `app/<kind>` off the app root, so a packwerk
+  app whose services live under `packs/billing/app/services` was told it had no
+  services directory and may not use the pattern. Directory discovery reads
+  `PathResolver.dirs_for`, which already resolved packs, engines and
+  `extra_app_paths` for the payload side. `ConcernPaths.resolve` and
+  `ActiveSupportIntrospector` read the same resolver, so a concern's listing,
+  its lookup and its "Used By" line now agree on one app. Counts move on any
+  app with packs or engines. Each walk names the directory a file came from, so
+  two files of the same basename under different roots no longer collide, and a
+  tool that finds nothing names all three directory patterns it searched
+  instead of the conventional one alone.
+- **`RailsAiContext.debug_fail`.** About 258 rescue bodies in `lib/`
+  hand-rolled the same three lines: rescue the error, write a `DEBUG`-gated
+  warning to stderr, return a fallback. They call one method now, with every
+  message string and every fallback value unchanged. `exe/rails-ai-context`
+  shims it beside `log_warn`, because the standalone install path loads seven
+  files by hand and a converted rescue inside `install_mode.rb` would otherwise
+  raise `NoMethodError` after the removed-tool cleanup had already deleted
+  files.
+- **`PackageJson`.** GemLock's twin for the node side: `package.json` parsed
+  once per root, `dependencies` merged with `devDependencies`, capped by
+  `configuration.max_file_size` rather than by a constant no caller can reach,
+  and empty for anything it cannot read. A scope named after the package
+  counts, so an app reaching tailwind through `@tailwindcss/vite` keeps its
+  answer.
+
+### Removed
+
+- **`config.job_processor`, gone from `.ai-context.json` and from
+  `get_config`.** `ConfigIntrospector` parsed `config/sidekiq.yml` a second
+  time to publish it, and nothing read it: no renderer, no spec, no template.
+  The two readers disagreed, so a `:queues:` block written with weights,
+  `- [critical, 2]`, lost `critical` on the config side and kept it on the jobs
+  side, and one sidekiq.yml shipped two queue lists in one payload. The same
+  concurrency and queues stay under `jobs.sidekiq_config`, which
+  `get_job_pattern` already consumes, and `config.queue_adapter` still names
+  the adapter. Both sections sit in the standard and full presets, so no preset
+  loses the fact.
+- **`action_bindings` and `outlet_controllers`, gone from every Stimulus
+  controller entry.** Filling `action_bindings` read every ERB, HAML and Slim
+  file under `app/views` and `app/components` on every generation, and
+  `outlet_controllers` restated the outlets list one line above it. Nothing in
+  `lib/` read either key: `get_stimulus` renders outlets, and the compact
+  serializer touches the section through `controllers` and `total_controllers`.
+  Both keys leave the artifact, and one full pass over the view and component
+  trees leaves every generation.
+- **`Serializers::SectionGuard`, `DetailLevel::SCHEMA_ENUM` and
+  `Install::Program.select_tool_mode`.** SectionGuard was 15 lines forwarding
+  to `Tools::SectionFetch.usable?`; both callers sat in `SchemaAdapter`, which
+  is not a serializer, and `RouteCoverage` already called SectionFetch
+  directly. SCHEMA_ENUM went with its last reference when
+  `DetailLevel.schema(description)` replaced the same four-line input-schema
+  hash in 21 tools; every published schema is byte-identical, and
+  `rails_onboard` keeps its own literal because its levels are quick, standard
+  and full. `select_tool_mode` was a shim for `select_setup(surface).tool_mode`
+  with no caller left in `lib/`, and it cannot express the MCP-config-only
+  mode. `ModelIntrospector#sti_bases` and
+  `ControllerIntrospector#extract_permit_details` go with them; only their own
+  recursion and their own specs were calling them.
+
+### Changed
+
+- **`.github/instructions/rails-context.instructions.md` prints every gem
+  category.** `.first(6)` on the grouped Hash returned the first six pairs, so
+  the seventh category onward was dropped with nothing saying so, while
+  `.cursor/rules/rails-project.mdc` rendered the same grouping uncapped. One
+  payload, two gem lists.
+- **`.cursor/rules/rails-project.mdc` bolds `Global before_actions:`** like the
+  Claude and Copilot files. The three serializers each hand-wrote the same
+  ten-step overview and had drifted; `StackOverviewHelper#overview_lines`
+  states the body once and each renderer keeps only its frontmatter, title and
+  MCP hint.
+- **Puma settings are read inside blocks.** The hand-rolled recursion stopped
+  at the top level, so a `workers` line guarded by an environment conditional,
+  which is what the generated `puma.rb` ships, was invisible and the answer
+  read as no workers configured. `MethodCallListener` sees a receiverless call
+  at any depth. The cost of the widening is that nesting no longer hides a
+  setting, so a name set twice reports the last one wherever it sits. Also
+  `threads ENV.fetch("RAILS_MIN_THREADS") { 5 }, ENV.fetch("RAILS_MAX_THREADS")
+  { 5 }` reports 5 and 5 where it reported nothing, and the digit match is
+  anchored away from word characters, so `ENV.fetch("PORT_2", 3000)` no longer
+  reads as 2.
+- **`get_conventions`' frontend stack string reads parsed dependencies.**
+  `detect_frontend_stack` matched bare substrings against the raw file, with no
+  quotes at all, so `vite-plugin-ruby` on its own reported Vite. The markers
+  carry alternates where an exact name would have lost an answer the substring
+  caught: svelte or `@sveltejs/kit`, `@hotwired/turbo` or
+  `@hotwired/turbo-rails`.
+- **`api_introspector`'s codegen list reads parsed dependencies.** It searched
+  the file for the quoted tool name, so `openapi-typescript`, `orval` or
+  `@graphql-codegen/cli` named anywhere in `package.json`, an `overrides` block
+  included, counted as a client generator the app runs.
+- **`rails_generate_test` resolves a controller by the rule
+  `rails_get_controllers` uses.** It camelized the string and looked the result
+  up, so with `Admin::GiftCardsController` as the only gift-card controller,
+  `rails_get_controllers(controller: "gift_cards")` resolved and
+  `rails_generate_test(controller: "gift_cards")` answered "not found".
+  `Payload.find_controller` answers for both, with the camelize kept as the
+  fallback for a payload carrying no controllers at all.
+
+### Fixed
+
+Nine defects the survey confirmed against v5.27.0, and the defects three review
+rounds found in the work that fixed them.
+
+- **`onboard(detail: "quick")` no longer prints a guessed domain noun.** Eleven
+  ordered regexes read model, job and service names and stated the result as
+  plain fact with no confidence marker, so one model named `Message` made an
+  app "a messaging app". Quick mode now states what it measured: versions,
+  table, model and job counts, the frontend and the test framework.
+- **`api_namespaces` invented a namespace and missed one.** The two tiers
+  derived the list their own way. The booted regex kept a trailing slash on
+  `/api/users`, matched unanchored so `namespace :admin { namespace :api }`
+  reported `/api/v1` for an app that serves `/admin/api/v1`, and dropped a
+  route sitting at exactly `/api`. The static spelling got the segment boundary
+  wrong, so `/apidocs` reported `/api`. Both tiers read one anchored form.
+- **Turbo drive settings were double-counted for layouts.** `app/views/layouts`
+  was walked again after `app/views/**/*` had already reached it. The permanent
+  element pass threw its duplicate away through `uniq`; the drive settings did
+  not, so one attribute in a layout and one in a view printed as 3.
+- **The asset pipeline reported the wrong bundler and CSS framework.** Three
+  readers asked whether a package was present by searching the raw file for its
+  quoted name, so an app pinning CVE fixes in an `overrides` block was told
+  esbuild is its bundler and postcss its CSS framework, while the one reader
+  that parsed the file called the same app vite. Both answers landed in one
+  payload.
+- **`analyze_feature`'s Jobs, Mailers and Channels sections came from a glob.**
+  Each job's queue was read off its own `queue_as`, so a job inheriting the
+  queue from `ApplicationJob` was reported on a queue it does not use. The
+  three sections read the payload now, which carries what the booted tier
+  resolved, mailer actions and channel stream methods included. A section whose
+  payload entry is not there, because the `:jobs` introspector is off, is left
+  out rather than rendered from a directory walk.
+- **`performance_check` attributed queries to methods that are not actions.** A
+  `def` inside a nested class became a call site, and a one-line
+  `private def set_post` leaked its body into the action above it.
+  `ActionResolver` answers what an action is here, as it does everywhere else.
+  A second collision went with it: each body was found by searching the whole
+  file for the first `def <name>`, so a nested class defining the same name
+  earlier handed back its body and the real action was never scanned. The body
+  is cut from the lines the owner-filtered walk recorded, and `get_controllers`
+  and `get_context` share the seam. An empty owner filter falls back to the
+  line scan rather than answering nothing, and `def self.index` no longer
+  stands in for `def index`.
+- **A model whose only rule is `validate :method` printed its bullets under the
+  wrong heading.** `## Validations` was emitted only when the reflected list
+  had entries, and the custom bullets come from a second list that is disjoint
+  from it on both tiers, so they landed under Associations.
+- **Two ERB readers missed `<%== ... %>` and read a commented ivar as used.**
+  `check_instance_variable_usage` and `extract_local_variable_references` each
+  carried their own copy of the tag regex, byte for byte the same and neither
+  matching `ErbSource::TAG`. Both read `<%[=\-]?`, one optional character, so
+  `<%== title %>` parsed as a body of "= title" and the local never reached a
+  partial's expected locals. The comment skip was a second answer too:
+  `get_partial_interface` re-implemented it and `validate_semantics` never had
+  one, so `<%# @ghost %>` was reported as an ivar used in the view and not set
+  in the controller. Both readers ask `ErbSource` now.
+- **`rails_get_controllers` refused a name the VFS resource accepts.** VFS
+  resolved five ways, the tool two, so `controller: "gift_cards"` failed
+  against `Admin::GiftCardsController` while the resource answered off the same
+  payload. Both read `Payload.find_controller`, so a route key, an unambiguous
+  basename and the singularize and classify spellings now resolve in the tool
+  too.
+- **Two files behind one name no longer hide each other.** Once services,
+  helpers and concerns were read from packs and engines, a name could have more
+  than one file behind it. The ambiguous-service list printed
+  `app/services/<path>` for files that live under a pack, so two candidates
+  printed as two identical lines naming a file that exists in neither, and the
+  suggestion that followed handed back the name it had just refused. Paths
+  print from the app root, and a narrowing suggestion is offered only when some
+  candidate's relative path is unique. `rails_get_helper_methods` rendered the
+  first match as the whole module and listed the others under "Also defined
+  in" even when they declare different modules, so a file declaring
+  `Reports::DashboardHelper` was named under an `Admin::DashboardHelper`
+  heading; matches are split by the module each file declares.
+  `rails_get_concern` broke on the first directory that resolved, so an app
+  with both `app/models/concerns/trackable.rb` and
+  `app/controllers/concerns/trackable.rb` saw only the controller one. Every
+  "available" list is deduplicated where it is built.
+
 ## [5.27.0] - 2026-09-22
 
 ### Added

data/docs/ARCHITECTURE.md

@@ -110,11 +110,12 @@ flowchart LR
 
 The `Introspector` orchestrator runs configured introspectors and merges results.
 
-Three modules answer questions every introspector used to answer for itself:
+Four modules answer questions every introspector used to answer for itself:
 
 - **SourceScan** - one walk over a kind of app source, across every directory `PathResolver` resolves: `paths` stats, `each` reads, `classes` names by the declared constant
 - **EagerLoad** - loads a directory's constants for a booted-tier walk, one file at a time, so an unloadable file costs only itself
 - **GemLock** - which gems the app resolved and at what version, read once per lockfile and matched by exact name across GEM, GIT and PATH
+- **PackageJson** - which npm packages the app depends on, read once per `package.json`: present means named in `dependencies` or `devDependencies`, so an `overrides` pin is not a dependency, and `@tailwindcss/vite` counts as tailwindcss
 
 Two more answer a question a tool asks:
 
@@ -198,7 +199,6 @@ Result: controller and view tools automatically include relevant schema informat
 | `ToolGuideHelper` | MCP/CLI tool reference sections |
 | `TestCommandDetection` | Test framework detection |
 | `SectionFacts` | The facts every surface states about an app - auth, assets, associations, the filter chain, an unread entry's row, the static-tier notice - each rendered in one place |
-| `SectionGuard` | Whether a section resolved, so a refused one is not rendered |
 | `SectionMarkerWriter` | Writes a managed section into a file the user also owns |
 | `ContextModeDispatch` | Picks full or compact rendering for a run |
 

data/exe/rails-ai-context

@@ -592,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/rails_ai_context/action_filters.rb

@@ -345,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/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

@@ -444,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/fingerprinter.rb

@@ -156,8 +156,7 @@ module RailsAiContext
         return false unless spec
         spec.source.is_a?(Bundler::Source::Path)
       rescue => e
-        $stderr.puts "[rails-ai-context] local_gem_path? failed: #{e.message}" if ENV["DEBUG"]
-        false
+        RailsAiContext.debug_fail(e, false, label: "local_gem_path?")
       end
     end
   end

data/lib/rails_ai_context/hydrators/controller_hydrator.rb

@@ -16,8 +16,7 @@ module RailsAiContext
 
         ModelHints.resolve(model_names, context: context)
       rescue => e
-        $stderr.puts "[rails-ai-context] ControllerHydrator failed: #{e.message}" if ENV["DEBUG"]
-        HydrationResult.new
+        RailsAiContext.debug_fail(e, HydrationResult.new, label: "ControllerHydrator")
       end
 
       # Detect model names referenced in a controller source file using Prism AST.
@@ -28,8 +27,7 @@ module RailsAiContext
         Introspectors::ListenerRegistration.dispatcher_for(listener).dispatch(parse_result.value)
         listener.results
       rescue => e
-        $stderr.puts "[rails-ai-context] detect_model_references failed: #{e.message}" if ENV["DEBUG"]
-        []
+        RailsAiContext.debug_fail(e, [], label: "detect_model_references")
       end
       private_class_method :detect_model_references
     end

data/lib/rails_ai_context/hydrators/schema_hint_builder.rb

@@ -13,7 +13,7 @@ module RailsAiContext
         schema_data = context[:schema]
         return nil unless models_data.is_a?(Hash) && schema_data.is_a?(Hash)
 
-        model_key = Tools::BaseTool.fuzzy_find_key(models_data.keys, model_name)
+        model_key = Payload.fuzzy_find_key(models_data.keys, model_name)
         return nil unless model_key
 
         model_info = models_data[model_key]

data/lib/rails_ai_context/hydrators/view_hydrator.rb

@@ -17,8 +17,7 @@ module RailsAiContext
         ModelHints.resolve(model_names, context: context,
           describe: ->(name) { "@#{name.underscore} used in view but '#{name}' model not found" })
       rescue => e
-        $stderr.puts "[rails-ai-context] ViewHydrator failed: #{e.message}" if ENV["DEBUG"]
-        HydrationResult.new
+        RailsAiContext.debug_fail(e, HydrationResult.new, label: "ViewHydrator")
       end
 
       # Convert an instance variable name to a model name by convention.

data/lib/rails_ai_context/install/cleanup.rb

@@ -15,26 +15,42 @@ module RailsAiContext
       # @param keeping [Array<Symbol>] the tools still selected, whose files
       #   must survive even when a dropped tool names the same path
       # @param root [String, Pathname] project root
-      # @return [Array<String>] the paths removed, directories marked with a
-      #   trailing slash so callers can print them the way they always have
+      # @return [Hash] { removed: [paths], failed: [paths] }, directories
+      #   marked with a trailing slash so callers can print them the way they
+      #   always have. Both rm calls swallow their errors, so a path is only
+      #   reported removed once it is gone.
       def remove(tools:, keeping:, root:)
         kept = Array(keeping).flat_map { |key| AiTool.find(key)&.context_paths || [] }.to_set
+        removed = []
+        failed = []
 
-        Array(tools).flat_map { |key|
+        Array(tools).each do |key|
           paths = AiTool.find(key)&.context_paths || []
-          paths.filter_map { |relative| remove_path(relative, root) unless kept.include?(relative) }
-        }
+          paths.each do |relative|
+            next if kept.include?(relative)
+
+            label, gone = remove_path(relative, root)
+            next unless label
+
+            (gone ? removed : failed) << label
+          end
+        end
+
+        { removed: removed, failed: failed }
       end
 
+      # @return [Array(String, Boolean), nil] the path's label and whether it
+      #   is gone, or nil when there was nothing there to remove. A directory
+      #   whose children went but which itself survives counts as not gone.
       def remove_path(relative, root)
         full = File.join(root.to_s, relative)
 
         if File.directory?(full)
           FileUtils.rm_rf(full)
-          "#{relative}/"
+          [ "#{relative}/", !File.exist?(full) ]
         elsif File.exist?(full)
           FileUtils.rm_f(full)
-          relative
+          [ relative, !File.exist?(full) ]
         end
       end
       private_class_method :remove_path

data/lib/rails_ai_context/install/program.rb

@@ -72,13 +72,6 @@ module RailsAiContext
         setup
       end
 
-      # The tool-mode half of the same question, for a caller that predates
-      # the setup struct. It cannot express "MCP config only", so every
-      # entry point in this gem calls `select_setup` instead.
-      def select_tool_mode(surface)
-        select_setup(surface).tool_mode
-      end
-
       def setup_label(setup)
         return "MCP config only (no context files)" unless setup.context_files
 
@@ -118,14 +111,15 @@ module RailsAiContext
         to_remove.each do |key|
           tool = AiTool.find(key)
 
-          removed_paths = Cleanup.remove(tools: [ key ], keeping: selected.map(&:to_sym), root: root)
-          removed_paths.each { |path| surface.say "  Removed #{path}", :warn }
+          outcome = Cleanup.remove(tools: [ key ], keeping: selected.map(&:to_sym), root: root)
+          outcome[:removed].each { |path| surface.say "  Removed #{path}", :ok }
+          outcome[:failed].each { |path| surface.say "Could not remove #{path} - check its permissions", :warn }
 
           # Merge-safe MCP config cleanup - removes only the rails-ai-context entry
           cleaned = RailsAiContext::McpConfigGenerator.remove(tools: [ key ], output_dir: root.to_s)
-          cleaned.each { |f| surface.say "  Removed MCP entry from #{relative_to(f, root)}", :warn }
+          cleaned.each { |f| surface.say "  Removed MCP entry from #{relative_to(f, root)}", :ok }
 
-          surface.say "  #{tool.name} files removed", :ok if tool
+          surface.say "  #{tool.name} files removed", :ok if tool && outcome[:failed].empty?
         end
       end
 
@@ -147,6 +141,9 @@ module RailsAiContext
 
         File.open(gitignore, "a") { |f| lines.each { |line| f.puts line } }
         surface.say "Updated .gitignore", :ok
+      rescue SystemCallError, IOError => e
+        RailsAiContext.log_warn "[rails-ai-context] could not write .gitignore: #{e.message}"
+        surface.say "Could not update .gitignore - add .ai-context.json and .codex/config.toml by hand", :warn
       end
 
       # `standalone: nil` lets the generator detect the install mode from
@@ -159,6 +156,9 @@ module RailsAiContext
         result = generator.call
         result[:written].each { |f| surface.say "Created/Updated #{relative_to(f, root)}", :ok }
         result[:skipped].each { |f| surface.say "#{relative_to(f, root)} unchanged - skipped", :muted }
+        result[:failed].each do |f|
+          surface.say "Could not write #{relative_to(f, root)} - that tool will not auto-discover the MCP server", :warn
+        end
         surface.say "Skipped MCP config files (CLI-only mode)", :muted if tool_mode == :cli
         result
       end

data/lib/rails_ai_context/install_mode.rb

@@ -28,8 +28,7 @@ module RailsAiContext
       lock = RailsAiContext::GemLock.for(root)
       lock.missing? ? false : !lock.present?("rails-ai-context")
     rescue => e
-      $stderr.puts "[rails-ai-context] standalone install detection failed: #{e.message}" if ENV["DEBUG"]
-      false
+      RailsAiContext.debug_fail(e, false, label: "standalone install detection")
     end
   end
 end

data/lib/rails_ai_context/introspectors/action_mailbox_introspector.rb

@@ -51,8 +51,7 @@ module RailsAiContext
           entry[:callbacks] = callbacks if callbacks.any?
           entry
         rescue => e
-          $stderr.puts "[rails-ai-context] extract_mailboxes failed: #{e.message}" if ENV["DEBUG"]
-          nil
+          RailsAiContext.debug_fail(e, nil, label: "extract_mailboxes")
         end.compact.sort_by { |m| m[:name] }
       end
     end