rails-ai-context 5.15.0 → 5.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0250405dffbfbb2100bf513cc75840ae980f68970e1a76911c4b2cc5ba3fac77
-  data.tar.gz: 25606a4264641a0a1be621bb30f3476c9ce1ecc1fd8dc37f7719ab15acee5e14
+  metadata.gz: 59c335a48ab2976318ed2fc58d1cce4e2153c0db0144b61ca8d902f160bbeb76
+  data.tar.gz: 334cc340093515797006c8326b47fa97721c9e66f07f940f3ec0864db2ae241a
 SHA512:
-  metadata.gz: 88b6c43ddb2d47e8c7d428e0188fc9060584252d7457bcd5d5b580cba6029a73f383684582d04228c79aee1a5c014f5d65494439697e718d38844900a3b5890a
-  data.tar.gz: 00e2c762d693c804f0260b5e0d054ffb0443afd8271299a8711638f23b7a6aeaeaee68ea833ed788225086fc38ddb289b5de562fb3e5379d78e8a84cd6c75f3b
+  metadata.gz: f0e5532e52f873a3cb659dbf90fde582974f4840609f0c8365318f5b862659475484232e9ead3fd0074ec1a079db565cd8046a157ceb4f1bc1099b08877feded
+  data.tar.gz: e6bd4fe02b30344a494a8af944ab6ca94e07f944d143d99bd4f116ca3f15099a5fbbe840b38c1b186398c43c3b23825889fd4b852593fc09342edc50910cd4e9

data/CHANGELOG.md

@@ -5,6 +5,228 @@ 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.16.0] - 2026-07-12
+
+### Fixed
+
+- **HTTP engine mount works again.** `mount RailsAiContext::Engine, at: "/mcp"`
+  500'd with `uninitialized constant McpController`: the engine is not
+  namespace-isolated, so its route needed the fully-qualified
+  `rails_ai_context/mcp#handle` controller path. Verified with a real curl
+  MCP session (initialize + session-id + tools/call) against a booted app.
+- **`config.custom_tools` is usable as documented.** Referencing an
+  `app/mcp_tools/` class constant in the initializer aborted boot with
+  `NameError` (app/ constants are not autoloadable while initializers run),
+  and a class-name string crashed every CLI tool invocation with
+  `undefined method 'tool_name' for an instance of String`. Entries may now
+  be classes or class-name strings; strings resolve lazily after boot, and
+  invalid entries are warn-skipped everywhere (server, CLI runner,
+  TestHelper) instead of taking down unrelated tools. Docs and the
+  initializer template now show the string form.
+- **Mailers are no longer invisible in development.** `extract_mailers` read
+  `ActionMailer::Base.descendants` without the eager-load fallback that
+  channels already had, so every dev-mode run reported zero mailers
+  (`ai:inspect`, context files, onboard).
+- **TestHelper is self-sufficient.** `require "rails_ai_context/test_helper"`
+  alone raised `uninitialized constant RailsAiContext::Tools` - the common
+  case, since a `group: :development` install is never Bundler-required in
+  the test environment. The helper now requires the gem core itself; docs
+  explain custom-tool name lookup in the test environment.
+- **`claude_max_lines` counts physical lines.** Dual MCP/CLI tool examples
+  embed newlines inside single entries, so a default-capped CLAUDE.md could
+  ship 161 real lines with no trim marker. The cap (and the trim) now apply
+  to physical lines of the managed block.
+- **turbo_map no longer flags correct wiring.** `broadcast_append_to post`
+  against `turbo_stream_from @post` warned "no matching turbo_stream_from";
+  stream matching now strips the ivar sigil before comparing.
+- **frontend_stack's Turbo wiring line can actually render.** It read
+  `turbo[:broadcasts]`/`[:frames]` - keys the introspector never emits
+  (`model_broadcasts`/`turbo_frames`) - so the line was dead code for every
+  app; callback-style `broadcast_*_to` calls are now also detected.
+- **generate_test emits runnable tests for arg-taking scopes.** A scope like
+  `scope :by_status, ->(s) { ... }` produced `Post.by_status` (ArgumentError
+  at runtime); scope lambdas' required params are now captured through the
+  AST layer and such scopes get an `assert_respond_to` test with a
+  fill-in-the-args call site. Verified by running the generated file for real.
+- **job_pattern keeps `wait:` in retry configuration.** One ordered regex
+  dropped whichever of `wait:`/`attempts:` came first in `retry_on`; the two
+  options are now scanned independently.
+- **get_env skips comment lines.** `# ENV["WEB_CONCURRENCY"]` in the stock
+  puma.rb comment was reported as a real environment variable.
+- **diagnose omits an empty "Next Steps" section** instead of rendering a
+  bare header when no file/method context was parsed.
+- **analyze_feature lists jbuilder templates and record renders**
+  (`render @post` / `render post`), matching what get_view reports.
+- **service_pattern surfaces mailer dependencies** (`PostMailer.published_email`
+  style calls) and recognizes `perform_now`.
+- **README observability example reads `event.payload[:duration]`** - the
+  bridge emits a zero-width event, so `event.duration` is always ~0ms.
+- Singular/plural agreement in tool output ("1 result", "1 site",
+  "1 broadcast", "1 line", "1 table", "1 controller", "1 migration file").
+- edit_context's footer no longer suggests pasting the line-numbered block
+  verbatim as an Edit old_string.
+- **A syntax-broken model or controller file no longer kills the process in
+  the runtime tier.** Eager loading aborts at the first bad file with a
+  `SyntaxError` - a `ScriptError`, which sailed past every bare `rescue` and
+  took down the MCP server mid-session and every model-touching rake task.
+  Introspection now rescues `ScriptError` at the dispatch level, eager
+  loading falls back to per-constant loading, and `discover_models`
+  tolerates unloadable classes - one broken file costs exactly that file,
+  matching the static tier's contract.
+- **Standalone CLI no longer mixes framework versions.** The RubyGems
+  binstub activates the newest installed railties before the app's
+  Gemfile.lock pins its own, leaving newer framework paths in $LOAD_PATH:
+  every generated fact reported the wrong Rails version (e.g. 8.1.3 for an
+  8.0.5 app) with "already initialized constant" warnings polluting all
+  output. The exe now strips Rails-family gem paths at startup; the app's
+  bundle is the only framework source.
+- **`--app-path` and `--environment` work after the tool name** (`tool
+  schema --table notes --app-path /x`), matching the `--json`/`--no-boot`
+  passthrough handling. Previously they were silently discarded and the
+  command ran against the wrong directory.
+- **structure.sql parsing: single-line CREATE TABLE statements** (the shape
+  sqlite's `.schema` emits) no longer lose every column but the first;
+  bodies are split on top-level commas before per-line parsing.
+- **structure.sql parsing: foreign keys land on the right table.** The
+  `ALTER TABLE ... FOREIGN KEY` regex could span statement boundaries and
+  attribute a FK to whichever table had the first `ADD CONSTRAINT`.
+- **structure.sql parsing: NOT NULL columns are no longer reported as
+  nullable** (nullability was simply not extracted).
+- **Runtime-only tools refuse in the static tier.** After a mid-boot
+  failure, `runtime_info` and `query` ran against the half-initialized app
+  and returned live, unmarked data contradicting the static-tier banner in
+  the same response; both now answer `[UNAVAILABLE: static tier]` with the
+  boot-failure reason. This also removes a raw NameError leak in
+  runtime_info's Cache section and query's wrong `--skip-active-record`
+  blame under `--no-boot`.
+- **The static-tier banner carries the literal `[STATIC]` tag** that README
+  and COMPATIBILITY.md promise.
+- **doctor's "Secrets in .gitignore" check understands globs.** Rails 8.1
+  generates `/config/*.key`; the substring check false-failed every default
+  8.1 app and docked its readiness score.
+- **model_details carries confidence tags**: `[VERIFIED]` on the runtime
+  model header, per-scope `[VERIFIED]`/`[INFERRED]` from the AST layer
+  (README promised tags this tool never rendered).
+- **Route stats agree across generated context files.** CLAUDE.md counted
+  all routes over app controllers while copilot-instructions counted all
+  routes over all controllers ("35 across 1" vs "35 across 18"); every
+  serializer now reports app routes across app controllers with the
+  framework-inclusive total alongside.
+- **get_routes counts engine mounts.** Verbless rack mounts (propshaft's
+  `/assets`) vanished from both the app list and the excluded-framework
+  count; the header now reports them explicitly.
+- **Mongoid apps are detected from the Gemfile too** (previously only
+  Gemfile.lock or config/mongoid.yml), so a fresh checkout without a
+  lockfile gets honest Mongoid treatment instead of ActiveRecord answers.
+- **`extra_app_paths` accepts entries ending in `/app`** (`custom/app`
+  previously globbed `custom/app/app/models` and silently missed).
+- **analyze_feature no longer invents model names** ("user, payment, order")
+  on apps with zero models.
+- **A missing schema is "unavailable", not "failed".** A greenfield app's
+  `context` output framed the absent db/schema.rb as "introspection failed";
+  absent data sources now use the `[UNAVAILABLE]` vocabulary.
+- **conventions: `create!` flows are no longer attributed the save-and-branch
+  skeleton**, zero-signal test files are no longer credited as pattern
+  sources, and empty custom-directory descriptions drop the dangling dash.
+- **get_config names the environment its values reflect** (cache store,
+  queue adapter, and Action Cable differ per environment).
+- **get_env skips ERB-only false positives from comments** and standalone
+  `doctor` writes its report to stdout (`doctor > report.txt` works).
+- docs: TROUBLESHOOTING covers RubyGems' "Resolving dependencies..." stdout
+  pollution of the MCP stdio stream and its fixes; a new doctor check ("MCP
+  stdio hygiene") detects the condition by re-running gem activation the way
+  an MCP client's binstub launch does.
+- **Static schema answers include the implicit id primary key**, typed per
+  the adapter in config/database.yml (bigint everywhere, integer on SQLite);
+  composite-primary-key tables (`primary_key: [...]`) are left to their
+  explicitly dumped columns instead of gaining a phantom id.
+- **Static schema answers name their source dialect and migration state**:
+  structure.sql parses report "Dialect", "Schema version" (from the
+  schema_migrations insert tail), and the exact pending migration files;
+  schema.rb parses report version plus files newer than it. Secondary
+  database dumps compare against their own db/<name>_migrate directories.
+- Review-round regression fixes (found by adversarial review of this batch):
+  the missing-schema `{unavailable:}` result no longer leaks blank
+  "- Database:" lines into generated context files; the gitignore matcher
+  honors git's basename rule (`*.key`, bare `master.key`); multi-line
+  `retry_on` declarations keep their continuation-line options; a
+  syntax-broken `custom_tools` string entry warn-skips instead of crashing
+  the server and CLI; the Turbo broadcast scan ignores comments and method
+  definitions; redirect and lambda routes are not counted as engine mounts.
+- Second review-round fixes: the gitignore security check honors `!`
+  negation patterns (a re-included secret now correctly fails the check);
+  `SafeFile.read` scrubs invalid UTF-8 so one bad byte in one file can no
+  longer raise out of any scan (previously it could erase every model's
+  Turbo broadcasts, or crash `get_turbo_map` outright); legacy zero-padded
+  migration versions (`001_` storing version "1") no longer read as
+  forever-pending; the synthesized primary-key type is resolved per
+  database from config/database.yml (a mixed postgres/sqlite multi-db app
+  types each dump correctly); endless-method broadcasts
+  (`def refresh = broadcast_replace_to(...)`) are detected while trailing
+  `#comments` (with or without spaces) are not, in both the introspector
+  and get_turbo_map's own scanners; `retry_on` options inside trailing
+  comments are not reported as real retry config; the doctor stdio-hygiene
+  probe launches from Bundler's original environment (a configured bundle
+  path no longer produces a spurious warning); a custom tool whose class
+  body raises during autoload is reported as broken rather than
+  "class not found"; the schema_migrations INSERT regex and the
+  section-usability predicate each have a single home.
+- Third review-round fixes: source-line scans (Turbo broadcasts, retry_on
+  options) strip comments with a string-aware walker (`SourceLine`) instead
+  of a regex, so a `#` inside a string literal (`"#comments"`, `"##{id}"`)
+  no longer truncates the line and drops real calls, while comment text
+  still never reads as code - including comments after a continuation comma
+  in multi-line `retry_on`; `def self.broadcast_*_to` definitions are not
+  counted as broadcast calls; the doctor gitignore check now models git's
+  negation semantics (dir-only `!*/` entries, no re-inclusion under an
+  excluded parent, negations must match the file itself) - verified against
+  `git check-ignore` on a 16-case battery; the database.yml block lookup
+  no longer bleeds across whitespace-only lines into a sibling database's
+  adapter; and a custom tool whose body references a missing constant that
+  shares a name segment with the entry is no longer misreported as
+  "class not found".
+- Fourth review-round fixes: the gitignore check now evaluates paths the
+  way git does (ancestor-directory recursion with last-match-wins instead
+  of descend globbing), closing a false-SAFE case where `config/` followed
+  by `!config/` read as still covering config/master.key - verified 25/25
+  against `git check-ignore`, including `**/`, whitelist preludes, and
+  re-included directories; it also honors case-insensitive filesystems the
+  way core.ignorecase does. `SourceLine.strip_comment` gained %-literal
+  support (`%w[cs#billing]` is content, `n % 2` is not a literal), an
+  O(n) walk (a 400k-char multibyte line dropped from 27s to 51ms), and a
+  no-`#` fast path. Broadcast def-blanking handles constant receivers
+  (`def User.broadcast_updates_to`) and multiple defs per line; multi-line
+  broadcast extraction reads comment-stripped context; `::`-prefixed
+  custom_tools entries classify correctly; config/database.yml is read
+  once, CRLF-normalized, per introspection run.
+- Sixth-through-eighth review-round fixes (call-site scanning converged
+  after three more single-finding rounds): classic one-line methods
+  (`def x; broadcast_y_to(...); end`) contribute their body while
+  visibility-prefixed definitions (`private def`, `private_class_method
+  def`) contribute nothing; `;`/`=` inside string keyword defaults
+  (`sep: "; "`, `label: "a=b"`) and inside `#{...}` interpolation (with
+  nested quoted strings) no longer delimit a signature. A final review
+  round at a realistic-Rails bar returned zero findings.
+- Fifth review-round fixes: comment stripping is now a whole-fragment
+  state machine (`SourceLine.strip_comments`) - literal state carries
+  across newlines, so a comment mid-way through a multi-line broadcast
+  call is removed while a string spanning lines keeps its tail; backtick
+  command literals (with interpolation) are modeled; singleton broadcast
+  definitions on any receiver (`def record.broadcast_status_to`,
+  `def self::...`) are excluded from broadcast detection; database.yml
+  without a final newline still resolves its last block's adapter; and
+  the case-insensitivity probe works for app roots with caseless names
+  (all-digit directories).
+
+### Changed
+
+- Standalone `doctor` writes its report to stdout (previously stderr), so
+  `doctor > report.txt` captures it; update scripts that redirected `2>`.
+- Custom tools resolved through the CLI are now validated as `MCP::Tool`
+  subclasses, matching what the MCP server has always enforced; duck-typed
+  tool classes that only ever worked via `rails-ai-context tool` are
+  warn-skipped with the reason.
+
 ## [5.15.0] - 2026-07-11
 
 ### Added

data/README.md

@@ -523,7 +523,7 @@ class RailsGetBusinessMetrics < MCP::Tool
 end
 
 # config/initializers/rails_ai_context.rb
-config.custom_tools = [RailsGetBusinessMetrics]
+config.custom_tools = ["RailsGetBusinessMetrics"]
 ```
 
 Test with the built-in `TestHelper` (works with RSpec and Minitest):
@@ -562,7 +562,8 @@ Every MCP tool call fires an `ActiveSupport::Notifications` event:
 
 ```ruby
 ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
-  Rails.logger.info "[MCP] #{event.payload[:method]} - #{event.duration}ms"
+  ms = (event.payload[:duration].to_f * 1000).round
+  Rails.logger.info "[MCP] #{event.payload[:tool_name]} - #{ms}ms"
 end
 ```
 

data/config/routes.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 RailsAiContext::Engine.routes.draw do
-  match "/", to: "mcp#handle", via: :all
+  # The engine is not namespace-isolated, so the controller must be
+  # referenced by its full path or Rails resolves a top-level McpController.
+  match "/", to: "rails_ai_context/mcp#handle", via: :all
 end

data/docs/CUSTOM_TOOLS.md

@@ -75,13 +75,20 @@ Add your tool classes to the configuration:
 # config/initializers/rails_ai_context.rb
 if defined?(RailsAiContext)
   RailsAiContext.configure do |config|
-    config.custom_tools = [RailsGetBusinessMetrics]
+    config.custom_tools = ["RailsGetBusinessMetrics"]
   end
 end
 ```
 
 Custom tools appear alongside built-in tools in the MCP server and CLI.
 
+Use the class *name* as a string: classes under `app/` (including
+`app/mcp_tools/`) are not autoloadable while initializers run, so a bare
+constant reference there aborts boot with a `NameError`. String entries are
+resolved after the app finishes booting. A bare constant still works for
+classes already loaded when the initializer runs (e.g. defined in `lib/`
+and required manually).
+
 ## Using BaseTool features
 
 For access to caching, pagination, and helper methods, you can use `RailsAiContext::Tools::BaseTool` utilities directly:
@@ -111,7 +118,14 @@ end
 
 ## Testing custom tools
 
-Use the built-in `TestHelper` module:
+Use the built-in `TestHelper` module.
+
+With the gem in `group: :development`, the initializer's guard makes
+`config.custom_tools` a no-op in the test environment, so name-based lookup
+(`execute_tool("rails_get_business_metrics")`) won't find custom tools
+there. Either install the gem with `group: %i[development test]`, or pass
+the class itself: `execute_tool(RailsGetBusinessMetrics)`. Built-in tools
+resolve by name in any environment.
 
 ### With RSpec
 
@@ -191,7 +205,7 @@ If a custom tool replaces a built-in one, exclude the original:
 
 ```ruby
 RailsAiContext.configure do |config|
-  config.custom_tools = [MyBetterSecurityScan]
+  config.custom_tools = ["MyBetterSecurityScan"]
   config.skip_tools   = %w[rails_security_scan]
 end
 ```

data/docs/TROUBLESHOOTING.md

@@ -100,6 +100,23 @@ For Codex CLI specifically, the env section in `.codex/config.toml` must match y
 2. Check schema exists: `ls db/schema.rb` or `ls db/structure.sql`
 3. Run doctor: `rails ai:doctor`
 
+### MCP client reports a JSON parse error on the first line ("Resolving dependencies...")
+
+RubyGems can print `Resolving dependencies...` to stdout while activating the
+standalone `rails-ai-context` binary - before any gem code runs - which breaks
+the pure-JSON stdio framing. This happens when gem activation needs the full
+dependency resolver: typically a `GEM_PATH` that is missing part of the
+dependency graph, or launching from inside another Bundler project's
+directory. Fixes:
+
+1. Launch `rails-ai-context serve` with the app root as the working directory
+   (the generated MCP configs do this by default).
+2. Make sure `GEM_PATH` covers the complete default gem path
+   (`gem env path`), not just `gem env gemdir` - Ruby's bundled gems
+   (racc, etc.) live in a separate directory.
+3. In-Gemfile installs are immune: `bundle exec rails-ai-context serve`
+   activates through the lockfile.
+
 ### MCP server responds slowly
 
 - Check `config.cache_ttl` - lower values mean more frequent re-introspection

data/exe/rails-ai-context

@@ -11,6 +11,24 @@
 # correctly, and clearing specs breaks gems that look up their own path at runtime
 # (e.g., MCP SDK reads Gem.loaded_specs["json-schema"].full_gem_path).
 if defined?(Gem) && Gem.respond_to?(:loaded_specs) && !ENV["BUNDLE_BIN_PATH"]
+  # Also strip the Rails-family gems' lib paths. Leaving them in $LOAD_PATH
+  # lets the app's boot resolve framework files from the NEWEST installed
+  # versions instead of the app's Gemfile.lock pins, producing a mixed
+  # framework tree: wrong Rails.version in every generated fact and
+  # "already initialized constant" double-load warnings. Every Rails app's
+  # bundle provides these; in app-less modes a require re-activates them
+  # fresh. Non-framework tooling deps (mcp and friends) must keep their
+  # paths - Bundler.setup during app boot locks out late RubyGems
+  # activation, and restore_standalone_environment! splices them back.
+  rails_family = %w[
+    rails railties activesupport activemodel activerecord actionpack
+    actionview actionmailer activejob actioncable activestorage
+    actionmailbox actiontext
+  ].freeze
+  Gem.loaded_specs.each_value do |spec|
+    next if spec.default_gem? || !rails_family.include?(spec.name)
+    spec.full_require_paths.each { |path| $LOAD_PATH.delete(path) }
+  end
   Gem.loaded_specs.delete_if { |_, spec| !spec.default_gem? }
 end
 
@@ -74,6 +92,12 @@ class RailsAiContextCLI < Thor
       no_boot = options[:no_boot]
       no_boot = true if args.delete("--no-boot")
 
+      # Same for the value-taking class options: after the tool name they
+      # arrive as plain args, and dropping them silently sends the command
+      # at the wrong app (or wrong RAILS_ENV).
+      @app_path_override = extract_value_flag!(args, "--app-path")
+      @environment_override = extract_value_flag!(args, "--environment")
+
       boot_rails!(allow_static: true, no_boot: no_boot)
 
       runner = ::RailsAiContext::CLI::ToolRunner.new(name, args, json_mode: json_mode)
@@ -173,17 +197,19 @@ class RailsAiContextCLI < Thor
     def doctor
       boot_rails!(context: "doctor")
       result = ::RailsAiContext::Doctor.new.run
+      # The report is the command's product - it belongs on stdout so
+      # `doctor > report.txt` captures it. stderr stays for errors only.
       result[:checks].each do |check|
         icon = case check.status
         when :pass then "PASS"
         when :warn then "WARN"
         when :fail then "FAIL"
         end
-        $stderr.puts "  [#{icon}] #{check.name}: #{check.message}"
-        $stderr.puts "         Fix: #{check.fix}" if check.fix
+        puts "  [#{icon}] #{check.name}: #{check.message}"
+        puts "         Fix: #{check.fix}" if check.fix
       end
-      $stderr.puts ""
-      $stderr.puts "AI Readiness Score: #{result[:score]}/100"
+      puts ""
+      puts "AI Readiness Score: #{result[:score]}/100"
 
       failed = result[:checks].count { |c| c.status == :fail }
       if options[:strict] && failed > 0
@@ -590,12 +616,29 @@ class RailsAiContextCLI < Thor
     # capture references BEFORE Rails boot runs and re-register them afterwards.
     STANDALONE_REQUIRED_GEMS = %w[mcp json-schema addressable public_suffix].freeze
 
+    # Pull a value-taking flag (--flag VALUE or --flag=VALUE) out of the
+    # pass-through args that stop_on_unknown_option! leaves after the tool
+    # name. Returns the value, or nil when the flag isn't present.
+    def extract_value_flag!(args, flag)
+      if (idx = args.index(flag))
+        args.delete_at(idx)
+        return args.delete_at(idx)
+      end
+      if (pair = args.find { |a| a.start_with?("#{flag}=") })
+        args.delete(pair)
+        return pair.split("=", 2)[1]
+      end
+      nil
+    end
+
     def boot_rails!(context: nil, allow_static: false, no_boot: false)
-      app_root = File.expand_path(options[:app_path] || Dir.pwd)
+      app_path_opt = @app_path_override || options[:app_path]
+      environment_opt = @environment_override || options[:environment]
+      app_root = File.expand_path(app_path_opt || Dir.pwd)
       # Relative paths inside the app (log/, tmp/, sqlite files) assume the
       # process cwd is the app root, so honor --app-path by moving there.
-      Dir.chdir(app_root) if options[:app_path]
-      ENV["RAILS_ENV"] = options[:environment] if options[:environment]
+      Dir.chdir(app_root) if app_path_opt
+      ENV["RAILS_ENV"] = environment_opt if environment_opt
 
       if allow_static && (no_boot || options[:no_boot])
         enter_static_tier!("static mode requested with --no-boot")

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

@@ -284,7 +284,7 @@ module RailsAiContext
         "Extensibility" => <<~SECTION,
             # ── Extensibility ─────────────────────────────────────────────────
             # Register additional MCP tool classes alongside the #{RailsAiContext::Server.builtin_tools.size} built-in tools
-            # config.custom_tools = [MyApp::CustomTool]
+            # config.custom_tools = ["MyApp::CustomTool"]  # class name as string - resolved after boot
 
             # Exclude specific built-in tools by name
             # config.skip_tools = %w[rails_security_scan]

data/lib/rails_ai_context/app_kind.rb

@@ -13,10 +13,19 @@ module RailsAiContext
       return true if File.exist?(File.join(root, "config", "mongoid.yml"))
 
       lock = File.join(root, "Gemfile.lock")
-      return false unless File.exist?(lock)
+      if File.exist?(lock)
+        content = RailsAiContext::SafeFile.read(lock)
+        return !!content&.include?("    mongoid (")
+      end
 
-      content = RailsAiContext::SafeFile.read(lock)
-      !!content&.include?("    mongoid (")
+      # No lockfile yet (fresh checkout, bare directory): fall back to the
+      # Gemfile's own declaration so the app still gets Mongoid treatment
+      # instead of misleading ActiveRecord answers.
+      gemfile = File.join(root, "Gemfile")
+      return false unless File.exist?(gemfile)
+
+      content = RailsAiContext::SafeFile.read(gemfile)
+      !!content&.match?(/^\s*gem\s+["']mongoid["']/)
     end
   end
 end

data/lib/rails_ai_context/cli/tool_runner.rb

@@ -70,7 +70,7 @@ module RailsAiContext
       def self.available_tools
         skip = RailsAiContext.configuration.skip_tools
         tools = Server.builtin_tools
-        tools += RailsAiContext.configuration.custom_tools
+        tools += Server.resolve_custom_tools
         return tools if skip.empty?
         tools.reject { |t| skip.include?(t.tool_name) }
       end

data/lib/rails_ai_context/doctor.rb

@@ -27,6 +27,7 @@ module RailsAiContext
       check_prism
       check_brakeman
       check_live_reload
+      check_stdio_activation_hygiene
       check_security_gitignore
       check_security_auto_mount
       check_performance_schema_size
@@ -152,7 +153,7 @@ module RailsAiContext
       migrate_dir = File.join(app.root, "db/migrate")
       if Dir.exist?(migrate_dir) && Dir.glob(File.join(migrate_dir, "*.rb")).any?
         count = Dir.glob(File.join(migrate_dir, "*.rb")).size
-        Check.new(name: "Migrations", status: :pass, message: "#{count} migration files", fix: nil)
+        Check.new(name: "Migrations", status: :pass, message: "#{count} migration #{count == 1 ? 'file' : 'files'}", fix: nil)
       else
         Check.new(name: "Migrations", status: :warn, message: "No migrations", fix: nil)
       end
@@ -343,6 +344,46 @@ module RailsAiContext
         fix: "Check mcp gem: `bundle info mcp`")
     end
 
+    # RubyGems prints "Resolving dependencies..." to STDOUT when activating
+    # this gem needs the full resolver (split/incomplete GEM_PATH, conflicting
+    # candidate versions). That happens before any gem code runs and corrupts
+    # the MCP stdio stream's pure-JSON framing. Re-run the activation the way
+    # the standalone binstub does and flag anything that lands on stdout.
+    # In-Gemfile installs activate through the lockfile and are immune.
+    def check_stdio_activation_hygiene
+      return Check.new(name: "MCP stdio hygiene", status: :pass,
+        message: "in-Gemfile install activates via bundler (no resolver output)", fix: nil) unless InstallMode.standalone?
+
+      require "open3"
+      # An MCP client launches the binstub from a clean shell; simulate that
+      # exactly. The booted app's Bundler has mutated this process's env
+      # (RUBYOPT gets -rbundler/setup; with a configured bundle path even
+      # GEM_HOME/GEM_PATH point into vendor/bundle), so start from Bundler's
+      # snapshot of the pre-boot environment when it is available.
+      base_env = defined?(Bundler) && Bundler.respond_to?(:original_env) ? Bundler.original_env : ENV.to_h
+      %w[RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLER_SETUP BUNDLE_PATH].each { |k| base_env.delete(k) }
+      stdout, _stderr, status = Open3.capture3(
+        base_env, Gem.ruby, "--disable-gems", "-e",
+        "require 'rubygems'; gem 'rails-ai-context'",
+        unsetenv_others: true
+      )
+      if status.success? && stdout.empty?
+        Check.new(name: "MCP stdio hygiene", status: :pass,
+          message: "gem activation is silent on stdout", fix: nil)
+      elsif stdout.empty?
+        Check.new(name: "MCP stdio hygiene", status: :warn,
+          message: "gem activation exited #{status.exitstatus} (stdout clean)",
+          fix: "Run `gem list rails-ai-context` and reinstall if missing")
+      else
+        Check.new(name: "MCP stdio hygiene", status: :fail,
+          message: "gem activation writes to stdout (#{stdout.lines.first.to_s.strip.truncate(60)}) - this corrupts the MCP stdio stream",
+          fix: "GEM_PATH is split or incomplete; use the full `gem env path` (see TROUBLESHOOTING: MCP client reports a JSON parse error)")
+      end
+    rescue => e
+      Check.new(name: "MCP stdio hygiene", status: :warn,
+        message: "could not verify activation hygiene: #{e.message.truncate(60)}", fix: nil)
+    end
+
     # ── Introspector health ───────────────────────────────────────────
 
     def check_introspector_health
@@ -467,8 +508,8 @@ module RailsAiContext
 
       gitignore = File.read(gitignore_path)
       issues = []
-      issues << ".env exists but not in .gitignore" if sensitive_files.include?(".env") && !gitignore.include?(".env")
-      issues << "config/master.key not in .gitignore" if sensitive_files.include?("config/master.key") && !gitignore.include?("master.key")
+      issues << ".env exists but not in .gitignore" if sensitive_files.include?(".env") && !gitignore_covers?(gitignore, ".env")
+      issues << "config/master.key not in .gitignore" if sensitive_files.include?("config/master.key") && !gitignore_covers?(gitignore, "config/master.key")
 
       if issues.empty?
         Check.new(name: "Secrets in .gitignore", status: :pass, message: "Sensitive files properly gitignored", fix: nil)
@@ -479,6 +520,83 @@ module RailsAiContext
       end
     end
 
+    # Substring checks miss glob entries (Rails 8.1 generates `/config/*.key`
+    # rather than a literal master.key line), so match .gitignore patterns
+    # the way git does: anchored when the pattern contains a slash (* stops
+    # at separators), basename-at-any-depth when it doesn't, last-match-wins
+    # ordering, and git's negation rules - a `pattern/` entry only concerns
+    # directories, a negation must match the file itself (not a container),
+    # and a file cannot be re-included while a parent directory is excluded.
+    def gitignore_covers?(content, path)
+      gitignore_path_ignored?(parse_gitignore_rules(content), path, dir: false)
+    end
+
+    def parse_gitignore_rules(content)
+      content.each_line.filter_map do |line|
+        pattern = line.strip
+        next if pattern.empty? || pattern.start_with?("#")
+
+        negation = pattern.start_with?("!")
+        pattern = pattern.delete_prefix("!")
+        dir_only = pattern.end_with?("/")
+        anchored = pattern.chomp("/").include?("/")
+        pattern = pattern.delete_prefix("/").chomp("/")
+        next if pattern.empty?
+
+        { negation: negation, dir_only: dir_only, anchored: anchored, pattern: pattern }
+      end
+    end
+
+    # Mirrors git's evaluation order: if any ancestor directory ends up
+    # ignored (itself evaluated with the same rules, negations included),
+    # everything beneath it is ignored and cannot be re-included. Otherwise
+    # the path is judged by the last rule matching the path ITSELF - there
+    # is no "descend" globbing, which is what made `config/` + `!config/`
+    # (a re-included directory) falsely read as still covering its files.
+    def gitignore_path_ignored?(rules, path, dir:)
+      return true if gitignore_parent_ignored?(rules, path)
+
+      ignored = false
+      rules.each do |rule|
+        # `pattern/` entries concern directories only, in both polarities.
+        next if rule[:dir_only] && !dir
+        next if rule[:negation] && !ignored
+
+        ignored = !rule[:negation] if gitignore_pattern_matches?(rule, path)
+      end
+      ignored
+    end
+
+    def gitignore_parent_ignored?(rules, path)
+      parts = path.split("/")[0..-2]
+      parents = parts.each_index.map { |i| parts[0..i].join("/") }
+      parents.any? { |parent| gitignore_path_ignored?(rules, parent, dir: true) }
+    end
+
+    def gitignore_pattern_matches?(rule, path)
+      flags = File::FNM_PATHNAME | File::FNM_DOTMATCH
+      flags |= File::FNM_CASEFOLD if gitignore_case_insensitive?
+      if rule[:anchored]
+        File.fnmatch?(rule[:pattern], path, flags) || path == rule[:pattern]
+      else
+        File.fnmatch?(rule[:pattern], File.basename(path), flags)
+      end
+    end
+
+    # git sets core.ignorecase from the filesystem; mirror it by probing
+    # whether the .gitignore file itself resolves case-insensitively
+    # (APFS/NTFS default). The .gitignore basename always carries cased
+    # letters, unlike the app root (which can be all digits).
+    def gitignore_case_insensitive?
+      return @gitignore_case_insensitive if defined?(@gitignore_case_insensitive)
+
+      gitignore = File.join(app.root.to_s, ".gitignore")
+      swapped = File.join(app.root.to_s, ".GITIGNORE")
+      @gitignore_case_insensitive = File.exist?(gitignore) && File.identical?(gitignore, swapped)
+    rescue StandardError
+      @gitignore_case_insensitive = false
+    end
+
     def check_security_auto_mount
       config = RailsAiContext.configuration
       if config.auto_mount && defined?(Rails.env) && Rails.env.production?

data/lib/rails_ai_context/introspector.rb

@@ -29,7 +29,10 @@ module RailsAiContext
       config.introspectors.each do |name|
         introspector = resolve_introspector(name)
         context[name] = run_introspector(introspector)
-      rescue => e
+      rescue StandardError, ScriptError => e
+        # ScriptError included: a syntax-broken app file surfacing through
+        # eager loading must cost one section, not the whole process (the
+        # MCP server would otherwise die mid-session).
         context[name] = { error: e.message }
         RailsAiContext.log_warn "[rails-ai-context] #{name} introspection failed: #{e.message}"
       end