rails-ai-context 5.17.0 → 5.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebb8d4e0ebed93183c0c019071ee63d097fb8c7495f551393991000aa5d06e7b
-  data.tar.gz: 2141cf0a281a173da2f0fa34927be843f93600ced5cdd67ccd6eb4aeef261ce0
+  metadata.gz: 46645f9291dee2458c1a03529fcf888bfd4d11be1d742310f224ae439baed82f
+  data.tar.gz: 6c1a79f00117f9617970e5c0f1380337fdc17578fe350515d1a8d301a0fef3fd
 SHA512:
-  metadata.gz: e1bdda115ee2c82a43af9f6389ad18204629539e5867db0ae36d8c4fe86f50547084315470ed5842adccbced095026e2a220f32626d1c1e43600b595d7224afb
-  data.tar.gz: 197fe45172ce6888fd89ee63ecc505f5e014f1b3c759a918a7244025958ce9d17801f4bf1a0ac3ce401a93063b0f3d75998b4ec485f6bdbe4df9449be333920d
+  metadata.gz: 6ffd81a61373550ad0df085b3c01dc647de386bd79773b148711d8f040969f8a7f71fffb4e059539deef7285fc1fa21480761bd9f04cbaabd7aaaebab0e84e9d
+  data.tar.gz: c83fe3ae8dfa8bb663bba3b09dd6cd8b3b29939e2ae7ce6cf379cb9df0f739a2b21e86976a6741bee103240324f6e6118ba1fdf85b70d36927a702521e48a159

data/CHANGELOG.md

@@ -5,6 +5,115 @@ 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.19.0] - 2026-08-09
+
+### Added - 6 new tools surfacing previously unserved introspection (45 tools total)
+
+An audit found five introspectors whose data never reached the tool
+surface (three only served context files; `:autoload` and
+`:active_support` were unreachable entirely), plus one nervous-system
+gap nothing introspected. All six are now first-class tools, registered
+automatically in both MCP and CLI:
+
+- **`rails_get_i18n`** - default/available locales, backend, locale files with
+  key counts, per-locale coverage vs the default locale, and fallbacks
+  (data: `:i18n` introspector, previously serializer-only).
+- **`rails_get_mailers`** - every ActionMailer class with its delivery actions
+  and delivery method (data: `:jobs` introspector's mailer extraction,
+  previously serializer-only). Filter with `mailer:"UserMailer"`.
+- **`rails_get_engines`** - engines mounted in `config/routes.rb` with
+  known-engine descriptions, plus loaded engine classes with route/model
+  counts (data: `:engines` introspector, previously resource-only).
+- **`rails_get_autoload`** - Zeitwerk vs Classic mode, autoloaders with
+  collapsed/ignored dirs, autoload/eager-load paths, and custom inflections
+  (data: `:autoload` introspector, previously unreachable).
+- **`rails_get_active_support`** - concerns registry, deprecators,
+  MessageVerifier/MessageEncryptor usage, tagged logging, subscribed
+  `on_load` hooks, and cache store (data: `:active_support` introspector,
+  previously unreachable).
+- **`rails_get_env_config`** - per-environment configuration from
+  `config/environments/*.rb`: notable toggles (`force_ssl`, `eager_load`,
+  caching, log level, queue adapter, mailer delivery) and every config key
+  each environment sets. Backed by the new **EnvConfigIntrospector**
+  (40 introspectors total, wired into `PRESETS[:full]`; file-based, so it
+  also works in the static tier). Config keys and values are read with
+  `ConfigAssignmentListener`, so a multi-line value, an assignment nested in
+  a conditional, and the `Rails.application.config.x = y` form all read
+  correctly. The key list pages with `offset`/`limit`.
+
+### Fixed
+
+- **Engine-mounted MCP returns JSON-RPC errors instead of Rails 500s.**
+  `McpController#handle` had no rescue around `handle_request` - a
+  transport-level exception escaped into a generic Rails HTML 500, breaking
+  the client's JSON-RPC loop. It now answers 500 with a JSON-RPC `-32603`
+  body, mirroring `RailsAiContext::Middleware`.
+- **Standalone HTTP transport survives transport exceptions.** The Rack
+  lambda behind `rails-ai-context serve --transport http` let a
+  `handle_request` exception propagate to rackup (dropped connection). It
+  now returns the same JSON-RPC `-32603` body.
+- **MCP resources honor `max_tool_response_chars` without breaking the JSON
+  contract.** Static resource, model, and VFS routes payloads were emitted
+  unbounded (a huge schema or routes table rode a single JSON-RPC frame).
+  They now fit the cap by dropping whole elements from the data rather than
+  slicing the serialized string, so a capped payload still parses as the
+  `application/json` it is labeled. What was dropped is reported under a
+  `_truncated` key, which also counts any over-long string value that had to
+  be cut. New `RailsAiContext::JsonBudget` owns the reduction.
+- **A committed SSE stream is no longer overwritten by the error handler.**
+  `McpController#handle`'s rescue set a status, headers, and a JSON body on
+  responses that were already on the wire - closing a stream commits it, so
+  every streaming failure reached the rescue committed. Assigning a body
+  there swapped the stream out from under the thread draining it, turning a
+  truncated SSE response into a garbled one. Committed failures now re-raise
+  to `ActionController::Live`, which logs them with a backtrace and closes
+  the connection; uncommitted failures still get the JSON-RPC `-32603` body.
+- **`server.json` tool count** said 38 while the gem served 39; now tracks
+  the real count (45). Broken `RAILS_NERVOUS_SYSTEM.md` link in
+  `docs/INTROSPECTORS.md` replaced with a plain reference.
+
+## [5.18.0] - 2026-08-09
+
+### Added
+
+- **Three new Prism listeners.** `ConfigAssignmentListener` reads
+  `config.key = value` and `config.key.subkey = value` in initializers, matching
+  the root anywhere in the chain so `Rails.application.config.assets.paths`
+  resolves too. `ComponentStructureListener` reads ViewComponent and Phlex
+  structure: `renders_one`/`renders_many`, slot methods, constant tables,
+  `case @ivar` variant branching, and `CONST[@ivar]` indexing.
+  `ClassDefinitionListener` reads class definitions with their superclass.
+- **`docs/INTROSPECTORS.md` documents the listener catalogue**, how to add a
+  listener, and when regex is the right tool instead of the AST.
+
+### Changed
+
+- **Auth, component, channel, controller, inflection and initializer reading
+  moved from regex to the AST.** Devise and Doorkeeper settings, devise-jwt
+  detection, ViewComponent and Phlex structure, Action Cable `identified_by` /
+  `stream_from` / `stream_for` / `periodically`, `rate_limit` options, custom
+  inflections, CORS origins, RSpec helper `include`s, `DatabaseCleaner.strategy`
+  and model class detection are all read structurally now. Formatting that used
+  to defeat the patterns (multi-line arguments, adjacent string literals,
+  `%i[]` and `%w[]` forms) is read correctly.
+- **A filter's `if:` condition reports the action it names.** A lambda has no
+  literal value, so `if: -> { action_name == "create" }` used to surface as
+  `[INFERRED]`; it now reads `action_name == "create"`. Same key, same type.
+- **`rate_limit_parsed[:within]` no longer keeps a trailing comma.**
+  `within: 1.minute, only: :create` returned `"1.minute,"` and now returns
+  `"1.minute"`.
+- **Initializer `setup_calls` sees more.** The old pattern only matched a line
+  beginning with `config.`, so `Rails.application.config.x = y` and multi-line
+  chains were missed.
+- **Every remaining regex over Ruby source carries a note** saying why regex is
+  right there: non-Ruby files, mixed-extension globs, vocabulary matching, or
+  scope the listeners cannot see.
+
+### Fixed
+
+- **Dead namespace-tracking loop removed from `RakeTaskIntrospector`**, which
+  walked every line of every `.rake` file and discarded the result.
+
 ## [5.17.0] - 2026-08-09
 
 ### Added

data/CONTEXT.md

@@ -0,0 +1,17 @@
+# Context
+
+Terms this project uses in a narrower sense than everyday English. One entry per term that has caused a naming collision or an ambiguous read.
+
+## Environment
+
+Overloaded. Always qualify it; never use "environment" bare in a tool name, an introspector name, or a config key.
+
+**Process environment** - the environment variables a running app sees, plus the places they are declared (`ENV[]` call sites, `.env.example`, Dockerfile, credentials keys). Served by `rails_get_env`, read by `EnvIntrospector`.
+
+**Environment config** - what `config/environments/*.rb` declares per environment: the assigned `config.*` keys and the values of the notable toggles. Served by `rails_get_env_config`, read by `EnvConfigIntrospector`.
+
+**Environment** (unqualified, as data) - a single named Rails environment: development, production, staging. This is the only sense in which the bare word is allowed, and only as a value, never as a name. The `:environments` payload key means "the list of these", which is why it kept its name when the introspector was renamed.
+
+## Static tier
+
+The mode where the app did not boot, or `--no-boot` was passed. An introspector answers in this tier only if it defines `static_call`. Two shapes count as defining it: reading a different source (parsing `db/schema.rb` instead of querying the connection), and reading the same source a booted app would (a file-based introspector, where `static_call` is the same work under another name).

data/CONTRIBUTING.md

@@ -19,8 +19,8 @@ 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/             # 39 MCP tools with detail levels and pagination
+├── introspectors/     # 40 introspectors (schema, models, routes, etc.)
+├── tools/             # 45 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)
@@ -51,11 +51,13 @@ Listeners extract specific concerns (associations, validations, etc.) from the A
 1. Create `lib/rails_ai_context/introspectors/listeners/your_listener.rb` inheriting from `BaseListener`
 2. Implement `on_call_node_enter(node)` and/or `on_def_node_enter(node)` - only the events your concern needs
 3. Use `confidence_for(node)` from `BaseListener` to tag results `[VERIFIED]` or `[INFERRED]`
-4. Store results in `@results` (accessed via `#results`)
-5. Register the key/class pair in `SourceIntrospector::LISTENER_MAP`
-6. Write specs in `spec/lib/rails_ai_context/introspectors/listeners/your_listener_spec.rb`
+4. Store results in `@results` (accessed via `#results`) as plain hashes, never Prism nodes
+5. If your listener needs an event `SourceIntrospector.register_listener` doesn't already wire up, add it there
+6. Register the key/class pair in `SourceIntrospector::LISTENER_MAP` only if the listener should run on every model walk; listeners used by one introspector are passed to `SourceIntrospector.walk(path, key => Listener)` at the call site instead
+7. Write specs in `spec/lib/rails_ai_context/introspectors/listeners/your_listener_spec.rb`
+8. Add a row to the listener catalogue in `docs/INTROSPECTORS.md`
 
-See existing listeners in `lib/rails_ai_context/introspectors/listeners/` for reference patterns.
+See existing listeners in `lib/rails_ai_context/introspectors/listeners/` for reference patterns, and `docs/INTROSPECTORS.md` for the catalogue and the AST-vs-regex rule.
 
 ## Adding a CLI Tool Interface
 

data/README.md

@@ -68,7 +68,7 @@ rails-ai-context serve    # start MCP server
 
 </div>
 
-Now your AI doesn't guess - it **asks your app directly.** 39 tools and 5 resource templates that query your schema, models, routes, controllers, views, and conventions on demand. Model introspection uses Prism AST parsing - every result carries a `[VERIFIED]` or `[INFERRED]` confidence tag so AI knows what's ground truth and what needs runtime checking.
+Now your AI doesn't guess - it **asks your app directly.** 45 tools and 5 resource templates that query your schema, models, routes, controllers, views, and conventions on demand. Model introspection uses Prism AST parsing - every result carries a `[VERIFIED]` or `[INFERRED]` confidence tag so AI knows what's ground truth and what needs runtime checking.
 
 <br>
 
@@ -163,7 +163,7 @@ Native Rails controller transport. No separate process needed.
 
 ### CLI
 
-Same 39 tools, no server needed. Works in any terminal, any AI tool.
+Same 45 tools, no server needed. Works in any terminal, any AI tool.
 
 ```bash
 rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
@@ -245,7 +245,7 @@ rails 'ai:tool[stimulus]' controller=chart
 
 <br>
 
-## 39 Tools
+## 45 Tools
 
 Every tool is **read-only** and returns data verified against your actual app - not guesses, not training data.
 
@@ -331,6 +331,12 @@ Every tool is **read-only** and returns data verified against your actual app -
 | `get_service_pattern` | Interface, dependencies, side effects, callers |
 | `get_job_pattern` | Queue, retries, guard clauses, broadcasts, schedules |
 | `get_component_catalog` | ViewComponent/Phlex: props, slots, previews, sidecar assets |
+| `get_i18n` | Locales, translation files with key counts, per-locale coverage, fallbacks |
+| `get_mailers` | Mailer classes with delivery actions and delivery method |
+| `get_engines` | Mounted engines (with known-engine descriptions) + loaded engine classes |
+| `get_autoload` | Zeitwerk mode, autoload/eager-load paths, collapsed dirs, custom inflections |
+| `get_active_support` | Concerns registry, deprecators, MessageVerifier usage, on_load hooks, cache store |
+| `get_env_config` | Per-environment config: notable toggles + every config key each env sets |
 
 </details>
 
@@ -351,7 +357,7 @@ Every tool is **read-only** and returns data verified against your actual app -
 
 </details>
 
-> **[All 39 tools with parameters →](docs/TOOLS.md)** &nbsp;|&nbsp; **[Real-world recipes →](docs/RECIPES.md)**
+> **[All 45 tools with parameters →](docs/TOOLS.md)** &nbsp;|&nbsp; **[Real-world recipes →](docs/RECIPES.md)**
 
 <br>
 
@@ -397,12 +403,12 @@ Enabled by default. Disable with `config.anti_hallucination_rules = false` if yo
 
 ```mermaid
 graph TD
-    A["Your Rails App\nmodels + schema + routes + controllers + views + jobs"] -->|"39 introspectors"| B
+    A["Your Rails App\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B
 
     B["rails-ai-context\nPrism AST parsing · Cached · Confidence-tagged\nVFS: rails-ai-context:// URIs introspected fresh"]
 
-    B --> C["MCP Server\nstdio / HTTP\n39 tools · 5 templates"]
-    B --> D["CLI Tools\nRake / Thor\nSame 39 tools"]
+    B --> C["MCP Server\nstdio / HTTP\n45 tools · 5 templates"]
+    B --> D["CLI Tools\nRake / Thor\nSame 45 tools"]
     B --> E["Static Files\nCLAUDE.md · .cursor/rules/ · .cursorrules\n.github/instructions/"]
 
     style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
@@ -440,7 +446,7 @@ Both paths ask which AI tools you use (Claude Code, Cursor, GitHub Copilot, Open
 | In-Gemfile | Standalone | What it does |
 |:-----------|:-----------|:------------|
 | `rails ai:context` | `rails-ai-context context` | Generate context files |
-| `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any of the 39 tools |
+| `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any of the 45 tools |
 | `rails ai:tool` | `rails-ai-context tool --list` | List all available tools |
 | `rails ai:serve` | `rails-ai-context serve` | Start MCP server (stdio) |
 | `rails ai:doctor` | `rails-ai-context doctor` | Diagnostics + AI readiness score |
@@ -491,13 +497,13 @@ empty listings.
 | | |
 |:------|:------------|
 | **[Quickstart](docs/QUICKSTART.md)** | 5-minute getting started |
-| **[Tools Reference](docs/TOOLS.md)** | All 39 tools with every parameter |
+| **[Tools Reference](docs/TOOLS.md)** | All 45 tools with every parameter |
 | **[Recipes](docs/RECIPES.md)** | Real-world workflows and examples |
 | **[Custom Tools](docs/CUSTOM_TOOLS.md)** | Build and test your own MCP tools |
 | **[Configuration](docs/CONFIGURATION.md)** | 40+ config options with defaults |
 | **[AI Tool Setup](docs/SETUP.md)** | Claude, Cursor, Copilot, OpenCode, Codex |
 | **[Architecture](docs/ARCHITECTURE.md)** | System design and internals |
-| **[Introspectors](docs/INTROSPECTORS.md)** | All 39 introspectors and AST engine |
+| **[Introspectors](docs/INTROSPECTORS.md)** | All 40 introspectors and AST engine |
 | **[Security](docs/SECURITY.md)** | 4-layer SQL safety and file blocking |
 | **[CLI Reference](docs/CLI.md)** | Commands and argument syntax |
 | **[Standalone](docs/STANDALONE.md)** | Use without Gemfile entry |
@@ -509,7 +515,7 @@ empty listings.
 
 ## Build your own tools
 
-Register custom MCP tools alongside the 39 built-in ones:
+Register custom MCP tools alongside the 45 built-in ones:
 
 ```ruby
 # app/mcp_tools/rails_get_business_metrics.rb
@@ -547,7 +553,7 @@ if defined?(RailsAiContext)
   RailsAiContext.configure do |config|
     config.ai_tools   = %i[claude cursor] # Which AI tools to generate for
     config.tool_mode  = :mcp              # :mcp (default) or :cli
-    config.preset     = :full             # :full (39 introspectors) or :standard (17)
+    config.preset     = :full             # :full (40 introspectors) or :standard (17)
   end
 end
 ```
@@ -583,7 +589,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-2154 tests + 100-example e2e harness. 39 tools. 5 resource templates. 39 introspectors. Standalone or in-Gemfile.<br>
+2727 tests + 158-example e2e harness. 45 tools. 5 resource templates. 40 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/SECURITY.md

@@ -39,7 +39,7 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 
 ## Security Design
 
-- All 38 MCP tools are **read-only** and never modify your application or database.
+- All 45 MCP tools are **read-only** and never modify your application or database.
 - **Sensitive file blocking** - configurable `sensitive_patterns` blocks access to `.env`, `*.key`, `*.pem`, `credentials.yml.enc` across all search and read tools. Patterns are checked in `rails_search_code`, `rails_get_edit_context`, and all new tools.
 - **Path traversal protection** - all file-reading tools validate paths with `File.realpath()` against `Rails.root` to prevent directory escape.
 - **Command injection prevention** - code search uses `Open3.capture2` with array arguments (never shell strings). The `--` flag separator prevents pattern injection.

data/app/controllers/rails_ai_context/mcp_controller.rb

@@ -29,15 +29,7 @@ module RailsAiContext
     def handle
       status_code, rack_headers, body = self.class.mcp_transport.handle_request(request)
       self.status = status_code
-      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
-
+      apply_transport_headers(rack_headers)
       if body.respond_to?(:each)
         # Plain enumerable body (initialize, errors, JSON mode): join to a
         # string so Content-Length/ETag semantics stay conventional.
@@ -75,16 +67,66 @@ module RailsAiContext
       else
         self.response_body = body
       end
+    rescue => e
+      # Once the response is committed the status and headers are already on
+      # the wire, so a JSON-RPC frame written here cannot reach the client.
+      # Worse, assigning a body swaps the stream out from under the thread
+      # still draining the old one, turning a truncated SSE stream into a
+      # garbled one. The streaming branch's ensure always closes the stream,
+      # and closing commits, so every streaming failure lands here committed.
+      # Hand those to Live, which logs them with a backtrace and tears the
+      # connection down.
+      raise if response.committed?
+
+      # Mirror Middleware#json_rpc_error_response: a transport failure must
+      # still answer in JSON-RPC shape. Without this the exception escapes
+      # into a generic Rails 500 (HTML), breaking the client's JSON-RPC loop.
+      RailsAiContext.log_warn "[rails-ai-context] MCP request failed: #{e.class}: #{e.message}"
+      self.status = 500
+      response.headers["Content-Type"] = "application/json"
+      self.response_body = {
+        jsonrpc: "2.0",
+        error: { code: -32603, message: "Internal error: #{e.message}" },
+        id: nil
+      }.to_json
     end
 
     private
 
+    # Rack 3 transports name their headers in lowercase, and the MCP SDK
+    # switched to that in 1.0. Rails 7.0 keeps response headers in a
+    # case-sensitive Hash, so a lowercase "content-type" is invisible to the
+    # canonical lookup Rails makes when it commits, and it labels the response
+    # with its own text/html default - a correct JSON-RPC body under a type no
+    # client will parse. Rails 7.1 moved to case-insensitive Rack::Headers and
+    # does not have the problem. Only the type needs the canonical spelling,
+    # because Rails is the only reader that looks a header up by name; the
+    # value is passed through so nothing gains a charset it did not have.
+    def apply_transport_headers(rack_headers)
+      rack_headers.each do |name, value|
+        key = name.to_s.casecmp?("content-type") ? "Content-Type" : name
+        response.headers[key] = value
+      end
+    end
+
     def wait_for_stream_close
-      sleep 0.5 until response.stream.closed?
+      sleep 0.5 until stream_finished?
     rescue IOError
       nil
     end
 
+    # A client hangup aborts the buffer instead of closing it, so `closed?`
+    # alone leaves this thread parked until the transport's next keepalive
+    # write notices the hangup - up to the keepalive interval per dropped
+    # client. Live's buffer reports the hangup through `connected?`; the plain
+    # buffer used off the streaming path does not define it, so ask first.
+    def stream_finished?
+      stream = response.stream
+      return true if stream.closed?
+
+      stream.respond_to?(:connected?) && !stream.connected?
+    end
+
     class << self
       # Class-level memoization - transport persists across requests.
       # Thread-safe: MCP::Server and transport are stateless for reads.

data/docs/ARCHITECTURE.md

@@ -18,19 +18,19 @@ graph TD
         A["models + schema + routes + controllers + views + jobs + config"]
     end
 
-    A -->|"39 introspectors"| gem
+    A -->|"40 introspectors"| gem
 
     subgraph gem["rails-ai-context"]
         direction TB
 
         subgraph engine["Introspection Engine"]
             direction LR
-            I["Introspectors\n39 modules\nPresets\nCached"]
-            AST["AST Engine\nPrism\n21 listeners\nConfidence tags"]
+            I["Introspectors\n40 modules\nPresets\nCached"]
+            AST["AST Engine\nPrism\n24 listeners\nConfidence tags"]
             H["Hydration Layer\nSchema hints\ninjected into\ntool responses"]
         end
 
-        engine --> R["Tool Registry\n39 tools auto-discovered via inherited\n+ custom_tools - skip_tools = active tools"]
+        engine --> R["Tool Registry\n45 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 39 tools\nNo server needed"]
+        CLI["CLI Runner\nRake / Thor\nSame 45 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 (39 modules)
+        Cache->>App: introspect (40 modules)
         App-->>Cache: structured data
         Cache-->>TR: fresh context
     end
@@ -101,7 +101,7 @@ flowchart LR
 
 ### Introspectors (`lib/rails_ai_context/introspectors/`)
 
-39 modules that extract structured data from your Rails app. Each introspector:
+40 modules that extract structured data from your Rails app. Each introspector:
 
 - Returns a Hash (never raises - wraps errors in `{ error: msg }`)
 - Is registered in `INTROSPECTOR_MAP` with a symbol key
@@ -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 39 tools available as MCP and CLI
+- Same 45 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 39 tools annotated as non-destructive. Defense-in-depth for query tool.
+2. **Read-only tools** - All 45 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

@@ -17,7 +17,7 @@
 | In-Gemfile (Rake) | `rails ai:` | `rails 'ai:tool[schema]' table=users` |
 | Standalone (Thor) | `rails-ai-context` | `rails-ai-context tool schema --table users` |
 
-Both provide the same 39 tools and functionality.
+Both provide the same 45 tools and functionality.
 
 ---
 
@@ -40,7 +40,7 @@ rails-ai-context serve --transport http --port 6029   # HTTP transport
 
 ### `tool`
 
-Run any of the 39 MCP tools from the terminal.
+Run any of the 45 MCP tools from the terminal.
 
 ```bash
 # Rake syntax

data/docs/COMPATIBILITY.md

@@ -80,6 +80,7 @@ that define a `static_call` path can answer without a booted app:
 | `routes` | `config/routes.rb` parsed with a dedicated Prism listener |
 | `models` | `app/models/**/*.rb` (plus packs/engines/extra paths) parsed, not constantized |
 | `controllers` | `app/controllers/**/*.rb` (plus packs/engines/extra paths) parsed, not constantized |
+| `env_config` | `config/environments/*.rb` read from disk - file-based, so the static tier serves the same data as a booted app |
 
 The other 34 introspectors (views, jobs, gems, turbo, i18n, active_storage,
 auth, api, and the rest) have no static path and report `{ unavailable: reason
@@ -167,11 +168,11 @@ Proof sources:
    prints to stdout, writes via the `STDOUT` constant, hangs past the
    timeout) plus `spec/e2e/static_tier_spec.rb` ("broken-boot app over the
    CLI", "broken-boot app over MCP stdio", "syntax error in one model file").
-8. No introspector outside the five in the operating-tiers table defines
+8. No introspector outside the six in the operating-tiers table defines
    `static_call` (`lib/rails_ai_context/introspectors/view_introspector.rb`
    has none); `Introspector#run_introspector` reports `{ unavailable: reason
    }` for every such section regardless of shape.
-9. `spec/e2e/empty_app_spec.rb` - all 39 built-in tools swept against an app
+9. `spec/e2e/empty_app_spec.rb` - all 45 built-in tools swept against an app
    with no scaffold, no models, no controllers beyond
    `ApplicationController`, no routes beyond root.
 10. `spec/e2e/massive_app_spec.rb` - `schema`, `model_details`, and `routes`

data/docs/CONFIGURATION.md

@@ -56,7 +56,7 @@ preset: full
 
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
-| `preset` | Symbol | `:full` | `:full` (39 introspectors) or `:standard` (17 introspectors) |
+| `preset` | Symbol | `:full` | `:full` (40 introspectors) or `:standard` (17 introspectors) |
 | `context_mode` | Symbol | `:compact` | `:compact` (context files capped at ~150 lines) or `:full` (no line cap) |
 | `introspectors` | Array of symbols | (from preset) | Override the introspector list directly |
 | `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only, no root CLAUDE.md/AGENTS.md |
@@ -69,7 +69,7 @@ preset: full
 |:-------|:-----|:--------|:-----------|:------------|
 | `server_name` | String | `"rails-ai-context"` | - | MCP server name |
 | `cache_ttl` | Integer | `60` | Must be positive | Cache time-to-live in seconds |
-| `max_tool_response_chars` | Integer | `200_000` | Must be positive | Safety cap for tool response length |
+| `max_tool_response_chars` | Integer | `200_000` | Must be positive | Safety cap for tool responses and MCP resource payloads. An over-cap resource keeps its JSON shape: whole elements are dropped and reported under a `_truncated` key |
 | `live_reload` | Symbol/Boolean | `:auto` | - | `:auto` (uses `listen` gem if available), `true`, or `false` |
 | `live_reload_debounce` | Float | `1.5` | - | Seconds to wait before processing file changes |
 | `auto_mount` | Boolean | `false` | - | Auto-mount Rack middleware for HTTP transport |
@@ -166,7 +166,7 @@ preset: full
 
 ## Presets
 
-### `:full` (default) - 39 introspectors
+### `:full` (default) - 40 introspectors
 
 All available introspectors. Maximum context.
 

data/docs/CUSTOM_TOOLS.md

@@ -2,7 +2,7 @@
 
 # Custom Tools
 
-**Build your own MCP tools that run alongside the 39 built-in ones.**
+**Build your own MCP tools that run alongside the 45 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 39 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 45 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 39 tools from the terminal, no server needed
+3. **CLI** - Same 45 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 39 tools. Just re-run the install/init to update MCP config files.
+Yes, freely. Both generate identical context files and provide the same 45 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 39 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 45 built-in tools.
 
 ### Can I remove built-in tools?
 
@@ -99,7 +99,7 @@ PostgreSQL, MySQL, and SQLite. Each gets database-specific safety mechanisms (re
 
 ### What's the difference between `:full` and `:standard` preset?
 
-- **`:full`** (default) - 39 introspectors. Full context for every aspect of your app.
+- **`:full`** (default) - 40 introspectors. Full context for every aspect of your app.
 - **`:standard`** - 17 introspectors. Faster, covers the essentials (schema, models, routes, controllers, tests, etc.).
 
 ### What's `:compact` vs `:full` context mode?