rails-ai-context 5.16.1 → 5.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91f2141cb80001b16aa88dc0512da99e1f8b72069716920ddf93ac5011c0074b
-  data.tar.gz: fd468f67533f4e7d5f9a00f27af3508a3fe1df2834321a66ad7411d8e4e83701
+  metadata.gz: ebb8d4e0ebed93183c0c019071ee63d097fb8c7495f551393991000aa5d06e7b
+  data.tar.gz: 2141cf0a281a173da2f0fa34927be843f93600ced5cdd67ccd6eb4aeef261ce0
 SHA512:
-  metadata.gz: 59a7f897a5241af025bf4b383d60b12548f08a6fdaf7c80cb0acb398b5984134367bf01b8fc9441a842fd99c197bea59e325b3fa3365ef274249a4e80e7a6306
-  data.tar.gz: 2adc3898c6fd3df5026d59a8aef9d4141ee53d902f36797b64c5fce2e1a4698144cb25212a7a14478b10124afba6cde680c8cbb78dfbdb791fbcf9a16f03ad5b
+  metadata.gz: e1bdda115ee2c82a43af9f6389ad18204629539e5867db0ae36d8c4fe86f50547084315470ed5842adccbced095026e2a220f32626d1c1e43600b595d7224afb
+  data.tar.gz: 197fe45172ce6888fd89ee63ecc505f5e014f1b3c759a918a7244025958ce9d17801f4bf1a0ac3ce401a93063b0f3d75998b4ec485f6bdbe4df9449be333920d

data/.rubocop.yml

@@ -11,13 +11,6 @@ AllCops:
 Style/Documentation:
   Enabled: false
 
-Metrics/MethodLength:
-  Max: 25
-
-Metrics/ClassLength:
-  Max: 200
-
-Metrics/BlockLength:
-  Exclude:
-    - "spec/**/*"
-    - "*.gemspec"
+# rubocop-rails-omakase disables the whole Metrics department. Setting Max on a
+# disabled cop does not re-enable it, so size limits here would enforce nothing.
+# Turning it on would need ~40 existing files brought under the limit first.

data/AGENTS.md

@@ -0,0 +1,15 @@
+# rails-ai-context
+
+## Agent skills
+
+### Issue tracker
+
+Issues live as GitHub issues on `crisnahine/rails-ai-context`, driven with the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical roles, each label string equal to its name (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

data/CHANGELOG.md

@@ -5,6 +5,134 @@ 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.17.0] - 2026-08-09
+
+### Added
+
+- **`config.query_allowed_columns`** exempts a column name from the built-in
+  sensitive list used by `rails_query`. The rejection message told you to
+  subtract from `query_redacted_columns`, which could never work: that list is
+  unioned with a frozen suffix list, so an app with its own
+  `oauth_applications.secret` had no way to query it.
+
+### Fixed
+
+- **Documented security behaviour now matches the code.** The ReDoS timeout on
+  user-supplied regexes needs `Regexp.timeout`, which Ruby 3.1 does not have,
+  so `SECURITY.md` no longer promises it unconditionally on a version the gem
+  still supports. Layer 4 was documented as post-execution redaction; it has
+  rejected the query outright since 5.8.1, which is what the doc now says.
+- **`config.introspectors = %i[source]` no longer appears to be supported.**
+  `SourceIntrospector` was listed in the introspector table but is
+  infrastructure, not a registered introspector, so configuring it raised
+  `ConfigurationError`.
+- **Corrected documented defaults**, which had drifted: `sensitive_patterns` is
+  27 patterns not 8, `excluded_middleware` 25 not 24, `excluded_filters` 5 not
+  3, and the listener count is 21. `extra_app_paths` and
+  `instrumentation_include_arguments` were undocumented.
+- **Secondary database dumps report their own generated columns.** Parsing
+  `db/queue_schema.rb` read generated columns from the primary `db/schema.rb`
+  instead of the dump being parsed.
+- **Polymorphic foreign keys no longer always report a missing index.** The
+  compound check compared one joined string against two column names, so it
+  could never match an existing index.
+- **A column is no longer treated as indexed because a wider column name is.**
+  Index matching compared substrings, so an index on `user_id` counted as
+  covering `id`.
+
+### Changed
+
+- **schema.rb is read through one AST-backed reader.** `SchemaIntrospector`,
+  `PerformanceIntrospector` and `ConventionIntrospector` each parsed the dump
+  line by line with their own `create_table` regex; they now share
+  `SchemaReader`, built on the existing `SchemaDslListener`, as do the static
+  tier's table parse and the check-constraint, enum and generated-column
+  reads that each walked the dump separately.
+- **The static schema tier reports four things differently.** Where no live
+  connection is available and `db/schema.rb` is parsed instead: a `t.references`
+  or `t.belongs_to` column is reported by its foreign key name (`author_id`,
+  not `author`), which is what the live tier has always reported; a column
+  default written as a proc reports its source rather than being omitted; a
+  default split across lines is picked up; and an expression index declared at
+  the top level is flagged `expression: true`, as an in-table one already was.
+- **`rails_validate`'s Rails-aware rules moved to `ValidateSemantics`.** The
+  tool entry point kept syntax validation and orchestration; the 15 lint rules
+  now live in their own class. Behaviour is unchanged.
+- **`detail` has a type.** `DetailLevel` defines the three levels, their
+  ordering and normalization. An unrecognised value now reads as `standard`
+  rather than silently selecting whichever branch happened to be last.
+- **Soft-delete detection prefers the schema.** A `deleted_at` column in the
+  dump now drives the `soft_delete` convention, instead of matching the word
+  anywhere in model source. Apps dumping `structure.sql` keep the old source
+  match, and the `acts_as_paranoid` / `discard` macro check is unchanged.
+
+## [5.16.2] - 2026-07-17
+
+### Fixed
+
+- **Standalone static tier works when installed via `gem install`.**
+  `tool <name> --no-boot`, `tool <name> --help`, and `tool --list` outside
+  an app all died with `cannot load such file -- active_support/...`. The
+  RubyGems binstub eagerly activates the whole dependency tree, so the
+  exe's framework-path strip left every rails-family spec still flagged as
+  activated and `Gem.try_activate` refused to re-add the stripped paths.
+  The exe now stashes the stripped specs and splices their load paths back
+  at every app-less require site (Bundler-pinned paths still win after a
+  boot). Verified through the real binstub in an empty directory, in an
+  app whose Gemfile does not include the gem, and on the boot-failed
+  static fallback.
+- **Engine-mounted MCP survives mcp SDK 0.24.** The SDK's SSE writer now
+  calls `stream.flush` after every event, and
+  `ActionController::Live::Buffer` defines no `flush` - every SSE-mode
+  `tools/call` through `mount RailsAiContext::Engine` 500'd on all
+  supported Rails versions (the payload still arrived, then the request
+  died). The controller now hands the transport a flush-capable stream.
+  Verified with live curl sessions on booted Rails 7.1 and 8.1 apps.
+- **Engine-mounted GET streams actually stay open.** The transport
+  registers the server-push stream and returns; Live then closed the
+  response as soon as the action returned, so the SSE channel died
+  instantly, `notifications/tools/list_changed` could never be delivered,
+  and (once held open) clients would have waited up to 30s for response
+  headers. The action now commits headers immediately with an SSE comment
+  and holds the thread until the transport or the client closes the
+  stream. SETUP.md documents the one-thread-per-connected-client cost.
+- **Helpers keep their namespaces.** `app/helpers/admin/dashboard_helper.rb`
+  was reported as `DashboardHelper`, and looking it up by its real constant
+  name `Admin::DashboardHelper` failed. Module names now derive from the
+  path under `app/helpers` (`app/helpers/concerns` stays its own root,
+  matching the railties autoload glob), and exact path matches win before
+  basename fallbacks so a top-level helper is not shadowed by a namespaced
+  one.
+- **`rails_validate` checks qualified render targets in Ruby files.**
+  `render partial: "posts/missing"` in a controller or service passed
+  `level:"rails"` silently (the partial check only ran for ERB). Bare
+  `render "posts/show"` keeps template semantics in Ruby files, so the
+  controller template-render idiom is not false-flagged. Tool descriptions
+  now state exactly which column references are checked
+  (validates/permit/callbacks).
+- **`rails_review_changes` describes untracked files.** New files rendered
+  as empty headings (a fresh app right after `rails new` plus install
+  showed 20 of them); they now read `_new file, N lines_`, and only the
+  HEAD flow makes that claim (a committed-then-reverted file against an
+  older ref reads `_no diff available_`).
+- **Views resource resolves extension-less paths.** Reading
+  `rails-ai-context://views/posts/index` now serves
+  `posts/index.html.erb`; a same-named directory no longer defeats the
+  lookup, and sensitive-file candidates are rejected so the
+  not-found/not-allowed message split cannot act as an existence oracle
+  for secrets placed under `app/views`.
+- **Resource templates accept both URI schemes.** `rails://` and
+  `rails-ai-context://` now both resolve for the controllers, views, and
+  routes templates, and contents echo the URI the client requested.
+- **`preset` output no longer scrambles under pipes** in either CLI:
+  all framing (banner, separators, "Running:" labels) goes to stderr and
+  stdout carries pure tool output.
+- **Context files stop leaking internal tokens.** Architecture sections
+  showed raw keys (`concerns_models`, `pwa`, `solid_queue`) next to
+  humanized labels; every token the convention introspector emits now has
+  a label. Stale doc counts corrected across README and docs (39 tools,
+  25 doctor checks).
+
 ## [5.16.1] - 2026-07-12
 
 ### Fixed

data/CONTRIBUTING.md

@@ -20,7 +20,7 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 lib/rails_ai_context/
 ├── cli/               # CLI tool runner (tool_runner.rb) - executes MCP tools from rake/Thor
 ├── introspectors/     # 39 introspectors (schema, models, routes, etc.)
-├── tools/             # 38 MCP tools with detail levels and pagination
+├── tools/             # 39 MCP tools with detail levels and pagination
 ├── serializers/       # Per-assistant formatters + shared ToolGuideHelper
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── live_reload.rb     # MCP live reload (file watcher + cache invalidation)

data/README.md

@@ -21,7 +21,7 @@
 <br>
 [![Ruby](https://img.shields.io/badge/Ruby-3.1%20%7C%203.2%20%7C%203.3%20%7C%203.4-CC342D)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.0%20%7C%207.1%20%7C%207.2%20%7C%208.0%20%7C%208.1-CC0000)](https://github.com/crisnahine/rails-ai-context)
-[![Tests](https://img.shields.io/badge/Tests-2501%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
+[![Tests](https://img.shields.io/badge/Tests-2608%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 </div>
@@ -245,7 +245,7 @@ rails 'ai:tool[stimulus]' controller=chart
 
 <br>
 
-## 38 Tools
+## 39 Tools
 
 Every tool is **read-only** and returns data verified against your actual app - not guesses, not training data.
 
@@ -509,7 +509,7 @@ empty listings.
 
 ## Build your own tools
 
-Register custom MCP tools alongside the 38 built-in ones:
+Register custom MCP tools alongside the 39 built-in ones:
 
 ```ruby
 # app/mcp_tools/rails_get_business_metrics.rb

data/app/controllers/rails_ai_context/mcp_controller.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "delegate"
+
 module RailsAiContext
   # Rails controller for serving MCP over Streamable HTTP.
   # Alternative to the Rack middleware - integrates with Rails routing,
@@ -16,10 +18,25 @@ module RailsAiContext
     # supported Rails versions.
     include ActionController::Live
 
+    # The MCP SDK's SSE writer calls stream.flush after every event, but
+    # Live's buffer writes straight through to the client and defines no
+    # flush - the NoMethodError would 500 the request after the payload was
+    # already delivered and tear down long-lived GET streams.
+    class FlushableStream < SimpleDelegator
+      def flush; end
+    end
+
     def handle
       status_code, rack_headers, body = self.class.mcp_transport.handle_request(request)
       self.status = status_code
-      rack_headers.each { |k, v| response.headers[k] = v }
+      rack_headers.each do |k, v|
+        # mcp >= 1.0 returns Rack 3-style lowercase header keys. Rails 7.0's
+        # response header hash is case-sensitive (Rack 2), so a lowercase
+        # "content-type" never registers and Rails falls back to text/html on
+        # an otherwise valid JSON body. Write it with the canonical case.
+        key = k.casecmp("content-type").zero? ? "Content-Type" : k
+        response.headers[key] = v
+      end
 
       if body.respond_to?(:each)
         # Plain enumerable body (initialize, errors, JSON mode): join to a
@@ -29,8 +46,25 @@ module RailsAiContext
         body.close if body.respond_to?(:close)
         self.response_body = chunks.join
       elsif body.respond_to?(:call)
+        stream = response.stream
+        stream = FlushableStream.new(stream) unless stream.respond_to?(:flush)
         begin
-          body.call(response.stream)
+          body.call(stream)
+          # A GET opens the server-push channel: the transport registers the
+          # stream and returns, expecting it to outlive this call. Live closes
+          # the response when the action returns, so hold the thread until the
+          # transport's keepalive (or the client) closes the stream. Live also
+          # sends headers only on the first write - the transport writes
+          # nothing until its first keepalive ping, so commit with an SSE
+          # comment up front or clients sit waiting on headers.
+          if request.get?
+            begin
+              stream.write(": connected\n\n")
+            rescue IOError
+              nil
+            end
+            wait_for_stream_close
+          end
         ensure
           begin
             response.stream.close
@@ -43,6 +77,14 @@ module RailsAiContext
       end
     end
 
+    private
+
+    def wait_for_stream_close
+      sleep 0.5 until response.stream.closed?
+    rescue IOError
+      nil
+    end
+
     class << self
       # Class-level memoization - transport persists across requests.
       # Thread-safe: MCP::Server and transport are stateless for reads.

data/docs/ARCHITECTURE.md

@@ -25,12 +25,12 @@ graph TD
 
         subgraph engine["Introspection Engine"]
             direction LR
-            I["Introspectors\n31 modules\nPresets\nCached"]
-            AST["AST Engine\nPrism\n20 listeners\nConfidence tags"]
+            I["Introspectors\n39 modules\nPresets\nCached"]
+            AST["AST Engine\nPrism\n21 listeners\nConfidence tags"]
             H["Hydration Layer\nSchema hints\ninjected into\ntool responses"]
         end
 
-        engine --> R["Tool Registry\n38 tools auto-discovered via inherited\n+ custom_tools - skip_tools = active tools"]
+        engine --> R["Tool Registry\n39 tools auto-discovered via inherited\n+ custom_tools - skip_tools = active tools"]
     end
 
     R --> MCP
@@ -40,7 +40,7 @@ graph TD
     subgraph outputs["Output"]
         direction LR
         MCP["MCP Server\nstdio / HTTP\nResources\nVFS URIs"]
-        CLI["CLI Runner\nRake / Thor\nSame 38 tools\nNo server needed"]
+        CLI["CLI Runner\nRake / Thor\nSame 39 tools\nNo server needed"]
         S["Serializers\n14 modules\nStatic files\nPer-AI-tool"]
     end
 
@@ -73,7 +73,7 @@ sequenceDiagram
     alt cache hit (TTL + fingerprint valid)
         Cache-->>TR: cached context
     else cache miss
-        Cache->>App: introspect (31 modules)
+        Cache->>App: introspect (39 modules)
         App-->>Cache: structured data
         Cache-->>TR: fresh context
     end
@@ -115,8 +115,8 @@ The `Introspector` orchestrator runs configured introspectors and merges results
 **Prism AST parsing** replaced all regex-based Ruby source parsing in v5.2.0.
 
 - **AstCache** - Thread-safe parse cache (`Concurrent::Map`), keyed by path + SHA256 + mtime
-- **SourceIntrospector** - Single-pass Prism Dispatcher walks the AST once, feeds events to all 7 listeners simultaneously
-- **7 Listeners** - Associations, Validations, Scopes, Enums, Callbacks, Macros, Methods
+- **SourceIntrospector** - Single-pass Prism Dispatcher walks the AST once, feeding every registered listener simultaneously
+- **21 Listeners** - Associations, Validations, Scopes, Enums, Callbacks, Macros and Methods are the default map for model analysis; the rest are used through targeted walks over schema dumps, migrations, Gemfiles, rake tasks and initializers
 - **Confidence** - Every result carries `[VERIFIED]` (static literals) or `[INFERRED]` (dynamic expressions)
 
 ### Tool Registry (`lib/rails_ai_context/tools/base_tool.rb`)
@@ -192,7 +192,7 @@ Thor-based CLI that works standalone (no Gemfile entry):
 
 - `ToolRunner` - Parses CLI args, resolves tool names, executes tools, formats output
 - Supports `--json` mode for machine-readable output
-- Same 38 tools available as MCP and CLI
+- Same 39 tools available as MCP and CLI
 
 ### Caching
 
@@ -215,7 +215,7 @@ SHA256-based change detection:
 ## Key design decisions
 
 1. **Official MCP SDK** - Not a custom protocol. Uses `mcp` gem's `MCP::Tool`, `MCP::Server`, transports.
-2. **Read-only tools** - All 38 tools annotated as non-destructive. Defense-in-depth for query tool.
+2. **Read-only tools** - All 39 tools annotated as non-destructive. Defense-in-depth for query tool.
 3. **Graceful degradation** - Works without database (parses schema.rb as text), without Brakeman, without ripgrep, without listen gem.
 4. **Zeitwerk autoloading** - Files loaded on-demand. No `require_relative` in the gem.
 5. **Diff-aware generation** - Context file regeneration skips unchanged files using fingerprinting.

data/docs/CLI.md

@@ -40,7 +40,7 @@ rails-ai-context serve --transport http --port 6029   # HTTP transport
 
 ### `tool`
 
-Run any of the 38 MCP tools from the terminal.
+Run any of the 39 MCP tools from the terminal.
 
 ```bash
 # Rake syntax
@@ -93,7 +93,7 @@ rails-ai-context context --format claude # Specific format
 
 ### `doctor`
 
-Run 23 diagnostic checks and report AI readiness score.
+Run the diagnostic checks and report an AI readiness score.
 
 ```bash
 rails ai:doctor

data/docs/CONFIGURATION.md

@@ -91,8 +91,8 @@ preset: full
 | `excluded_models` | Array | 8 framework models | Models to skip during introspection |
 | `excluded_controllers` | Array | 2 framework controllers | Controllers to skip |
 | `excluded_route_prefixes` | Array | 6 framework prefixes | Route prefixes to skip |
-| `excluded_filters` | Array | 3 framework filters | Controller filters to skip |
-| `excluded_middleware` | Array | 24 framework middleware | Middleware to skip in listing |
+| `excluded_filters` | Array | 5 framework filters | Controller filters to skip |
+| `excluded_middleware` | Array | 25 framework middleware | Middleware to skip in listing |
 | `excluded_paths` | Array | `["node_modules", "tmp", "log", "vendor", ".git", "doc", "docs"]` | Paths excluded from search |
 | `excluded_association_names` | Array | 7 framework associations | Association names to hide from model output |
 | `excluded_concerns` | Array of Regex | Framework concerns | Concerns to skip (supports regex) |
@@ -116,6 +116,16 @@ preset: full
 | `search_extensions` | Array | `["rb", "js", "erb", "yml", "yaml", "json", "ts", "tsx", "vue", "svelte", "haml", "slim"]` | File extensions to search |
 | `concern_paths` | Array | `["app/models/concerns", "app/controllers/concerns"]` | Paths to scan for concerns |
 | `frontend_paths` | Array | `nil` (auto-detect) | Override frontend file paths |
+| `extra_app_paths` | Array | `[]` | Extra directories under the app root to treat as application code |
+
+### Instrumentation
+
+| Option | Type | Default | Description |
+|:-------|:-----|:--------|:------------|
+| `instrumentation_include_arguments` | Boolean | `false` | Include tool arguments in instrumentation events |
+
+> [!WARNING]
+> `instrumentation_include_arguments` forwards raw tool arguments to your subscribers, which for `rails_query` means the SQL text and for other tools can mean environment variable names. Leave it off unless your subscriber is as trusted as your logs.
 
 ### Database Query Safety
 
@@ -123,7 +133,8 @@ preset: full
 |:-------|:-----|:--------|:-----------|:------------|
 | `query_timeout` | Integer | `5` | - | SQL query timeout in seconds |
 | `query_row_limit` | Integer | `100` | 1–1000 | Maximum rows returned |
-| `query_redacted_columns` | Array | 10+ patterns | - | Column names/suffixes to redact |
+| `query_redacted_columns` | Array | 14 patterns | - | Column names that cause a query to be rejected |
+| `query_allowed_columns` | Array | `[]` | - | Column names exempted from the built-in sensitive list |
 | `allow_query_in_production` | Boolean | `false` | - | Allow `rails_query` tool in production |
 
 ### Logs
@@ -136,7 +147,7 @@ preset: full
 
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
-| `sensitive_patterns` | Array | 8 patterns | File patterns blocked from search/read (`.env*`, `*.key`, `*.pem`, `credentials.yml.enc`, etc.) |
+| `sensitive_patterns` | Array | 27 patterns | File patterns blocked from search/read (`.env*`, `*.key`, `*.pem`, `config/credentials.yml.enc`, `.ssh/*`, etc.) |
 
 ### Extensibility
 

data/docs/CUSTOM_TOOLS.md

@@ -2,7 +2,7 @@
 
 # Custom Tools
 
-**Build your own MCP tools that run alongside the 38 built-in ones.**
+**Build your own MCP tools that run alongside the 39 built-in ones.**
 
 [Tools Reference](TOOLS.md) · [Configuration](CONFIGURATION.md) · [Architecture](ARCHITECTURE.md) · [FAQ](FAQ.md)
 
@@ -11,7 +11,7 @@
 ---
 
 > [!NOTE]
-> Custom tools have full access to your Rails environment - ActiveRecord, services, mailers, everything. They appear alongside the 38 built-in tools in both MCP and CLI.
+> Custom tools have full access to your Rails environment - ActiveRecord, services, mailers, everything. They appear alongside the 39 built-in tools in both MCP and CLI.
 
 ## Creating a custom tool
 

data/docs/FAQ.md

@@ -25,7 +25,7 @@ Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI. Each gets tailored
 No. The gem works three ways:
 1. **MCP server** - AI calls tools via the protocol (best experience)
 2. **Static files** - Generated context files (CLAUDE.md, .cursor/rules/, etc.)
-3. **CLI** - Same 38 tools from the terminal, no server needed
+3. **CLI** - Same 39 tools from the terminal, no server needed
 
 ### Is this safe for production?
 
@@ -47,7 +47,7 @@ Yes. The gem gracefully degrades - it parses `db/schema.rb` as text when no data
 
 ### Can I switch between Gemfile and standalone?
 
-Yes, freely. Both generate identical context files and provide the same 38 tools. Just re-run the install/init to update MCP config files.
+Yes, freely. Both generate identical context files and provide the same 39 tools. Just re-run the install/init to update MCP config files.
 
 ### Do I need to commit the generated files?
 
@@ -69,7 +69,7 @@ Start with `rails_onboard` for an app overview, `rails_analyze_feature` for feat
 
 ### Can I add my own tools?
 
-Yes. See [Custom Tools](CUSTOM_TOOLS.md). Create an `MCP::Tool` subclass, register it via `config.custom_tools`, and it appears alongside the 38 built-in tools.
+Yes. See [Custom Tools](CUSTOM_TOOLS.md). Create an `MCP::Tool` subclass, register it via `config.custom_tools`, and it appears alongside the 39 built-in tools.
 
 ### Can I remove built-in tools?
 

data/docs/GUIDE.md

@@ -18,7 +18,7 @@
 | Guide | Description |
 |:------|:------------|
 | [Quickstart](QUICKSTART.md) | Get running in 5 minutes |
-| [Tools Reference](TOOLS.md) | All 38 MCP tools with parameters |
+| [Tools Reference](TOOLS.md) | All 39 MCP tools with parameters |
 | [Recipes](RECIPES.md) | Real-world workflows and examples |
 | [Custom Tools](CUSTOM_TOOLS.md) | Build your own MCP tools |
 | [Configuration](CONFIGURATION.md) | Every config option |
@@ -283,7 +283,7 @@ rails ai:context:claude           # Use this instead (no quoting needed)
 
 ## CLI Tools
 
-All 38 MCP tools can be run directly from the terminal - no MCP server or AI client needed.
+All 39 MCP tools can be run directly from the terminal - no MCP server or AI client needed.
 
 ### Rake
 
@@ -349,7 +349,7 @@ The `tool_mode` is selected during `rails generate rails_ai_context:install`.
 
 ## MCP Tools - Full Reference
 
-All 38 tools are **read-only** and **idempotent** - they never modify your application or database.
+All 39 tools are **read-only** and **idempotent** - they never modify your application or database.
 
 ### rails_get_schema
 
@@ -1169,7 +1169,7 @@ if defined?(RailsAiContext)
 end
 ```
 
-Both transports are **read-only** - they expose the same 38 tools and never modify your app.
+Both transports are **read-only** - they expose the same 39 tools and never modify your app.
 
 ### Controller Transport (Alternative)
 

data/docs/INTROSPECTORS.md

@@ -94,7 +94,6 @@ end
 
 | Introspector | Key | What it extracts |
 |:-------------|:----|:-----------------|
-| SourceIntrospector | `:source` | Prism AST: associations, validations, scopes, enums, callbacks, macros, methods |
 | MigrationIntrospector | `:migrations` | Migration files, versions, reversibility |
 | SeedsIntrospector | `:seeds` | Seed file analysis |
 | DatabaseStatsIntrospector | `:database_stats` | Table sizes, row counts, index stats |
@@ -170,9 +169,11 @@ These introspectors map directly onto [`RAILS_NERVOUS_SYSTEM.md`](../RAILS_NERVO
 
 ## AST-based introspection
 
-The **SourceIntrospector** uses Prism AST parsing for model analysis. It runs a single-pass Dispatcher that walks the AST once and feeds events to 7 listeners simultaneously:
+The **SourceIntrospector** uses Prism AST parsing for model analysis. It is infrastructure shared by the introspectors above rather than an introspector you can enable: there is no `:source` key for `config.introspectors`.
 
-### 7 Prism listeners
+It runs a single-pass Dispatcher that walks the AST once and feeds events to all registered listeners simultaneously. Model analysis uses the seven below by default; the other fourteen listener classes are used through targeted walks (schema dumps, migrations, Gemfiles, rake tasks, initializers, and so on), for 21 in total.
+
+### The 7 default Prism listeners
 
 | Listener | What it detects |
 |:---------|:---------------|

data/docs/QUICKSTART.md

@@ -62,7 +62,7 @@ The install generator created:
 ## Verify it works
 
 ```bash
-# Check AI readiness (23 diagnostic checks)
+# Check AI readiness (25 diagnostic checks)
 rails ai:doctor          # In-Gemfile
 rails-ai-context doctor  # Standalone
 

data/docs/SECURITY.md

@@ -11,11 +11,11 @@
 ---
 
 > [!CAUTION]
-> This gem is designed for **development environments**. The query tool is disabled in production by default. Sensitive files are blocked. All 38 tools are read-only.
+> This gem is designed for **development environments**. The query tool is disabled in production by default. Sensitive files are blocked. All 39 tools are read-only.
 
 ## Design principles
 
-1. **Read-only by design** - All 38 tools are annotated as non-destructive in the MCP protocol
+1. **Read-only by design** - All 39 tools are annotated as non-destructive in the MCP protocol
 2. **Defense in depth** - Multiple security layers, not single points of failure
 3. **Sensitive data blocking** - Configurable patterns prevent access to secrets
 4. **Offline by default** - No network calls except optional `rails_search_docs` with `fetch: true`
@@ -33,8 +33,9 @@ flowchart LR
     L1 -->|"Blocked:\nINSERT, DROP,\nUNION SELECT..."| R1[Rejected]
     L1 -->|SELECT only| L2{Layer 2\nDatabase Read-Only}
     L2 -->|"SET TRANSACTION\nREAD ONLY\n+ timeout"| L3{Layer 3\nRow Limit}
-    L3 -->|"Cap: 1000 rows\nDefault: 100"| L4{Layer 4\nColumn Redaction}
-    L4 -->|"password_digest\napi_key → [REDACTED]"| OK[Safe Result]
+    L3 -->|"Cap: 1000 rows\nDefault: 100"| L4{Layer 4\nSensitive Columns}
+    L4 -->|"names password_digest,\napi_key, ..."| R1
+    L4 -->|"no sensitive column"| OK[Safe Result]
 
     style R1 fill:#e74c3c,stroke:#c0392b,color:#fff
     style OK fill:#27ae60,stroke:#1e8449,color:#fff
@@ -75,13 +76,19 @@ All queries execute inside a transaction, then rollback (even if they could writ
 - Configurable: `config.query_row_limit` (hard cap: 1000)
 - Applied as `LIMIT` clause appended to query
 
-### Layer 4 - Column redaction
+### Layer 4 - Sensitive column rejection
 
-Sensitive column values are replaced with `[REDACTED]`:
+A query that names a sensitive column is **rejected before execution**, not redacted after it:
 
 **Default redacted patterns:** `password_digest`, `encrypted_password`, `password_hash`, `reset_password_token`, `confirmation_token`, `unlock_token`, `otp_secret`, `session_data`, `secret_key`, `api_key`, `api_secret`, `access_token`, `refresh_token`, `jti`
 
-Redaction matches by **name** and **suffix** - `SELECT password_digest AS pd` still redacts `pd` because the column name is tracked through the query result.
+Matching is by name, case-insensitive and word-bounded, against both the defaults above and `config.query_redacted_columns`. `SELECT password_digest AS pd FROM users` is blocked outright: post-execution redaction reads the column names the database returns, which the caller controls through aliases and expressions, so it cannot be relied on.
+
+If one of your own columns merely looks sensitive (an `oauth_applications.secret`, say), exempt it by name:
+
+```ruby
+config.query_allowed_columns = %w[secret]
+```
 
 ### Environment guard
 
@@ -96,15 +103,16 @@ The `rails_search_code` and file-reading tools block access to sensitive files:
 
 ### Default patterns
 
-```
-.env*
-*.key
-*.pem
-credentials.yml.enc
-master.key
-secret_key_base
-config/secrets.yml
-config/credentials/*
+```text
+.env .env.*
+config/master.key
+config/credentials.yml.enc config/credentials/*.yml.enc
+config/database.yml config/secrets.yml
+config/cable.yml config/storage.yml
+config/mongoid.yml config/redis.yml
+*.pem *.key *.p12 *.pfx *.jks *.keystore
+**/id_rsa **/id_ed25519 **/id_ecdsa **/id_dsa
+.ssh/* .aws/credentials .aws/config .netrc .pgpass .my.cnf
 ```
 
 ### AI context file exclusions
@@ -158,7 +166,7 @@ File type parameters accept only alphanumeric characters.
 
 ## Regex injection prevention
 
-User-supplied regex patterns have a 1-second timeout:
+On Ruby 3.2 and newer, user-supplied regex patterns have a 1-second timeout:
 
 ```ruby
 Regexp.new(pattern, timeout: 1)
@@ -166,6 +174,9 @@ Regexp.new(pattern, timeout: 1)
 
 Complex patterns that would cause catastrophic backtracking raise `RegexpError` instead of hanging.
 
+> [!WARNING]
+> `Regexp.timeout` does not exist on Ruby 3.1, which this gem still supports. There the timeout is skipped, and a pattern crafted to backtrack catastrophically can hang the process serving the tool. If you expose `rails_search_code` to input you do not control, run it on Ruby 3.2 or newer.
+
 ---
 
 ## Safe file reading
@@ -207,7 +218,7 @@ When using HTTP transport (Rack middleware or McpController):
 
 - **Default bind**: `127.0.0.1` (localhost only - not exposed to network)
 - **`auto_mount` is `false` by default** - must be explicitly enabled
-- **Doctor checks** warn if `auto_mount` is true (security flag)
+- **Doctor checks** fail if `auto_mount` is true in production, and report it as enabled elsewhere
 
 The McpController uses thread-safe transport initialization with mutex synchronization.