rails-ai-context 5.14.0 → 5.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab9892f397e65d076b20e20f7a01da83cd70b1bfb2a2d71fe9949e09616d7bdb
-  data.tar.gz: 3f5021a82283731cc7ea915bfbab0b11f06950d5bbc9fd9b656ca70fe43d6cc9
+  metadata.gz: 59c335a48ab2976318ed2fc58d1cce4e2153c0db0144b61ca8d902f160bbeb76
+  data.tar.gz: 334cc340093515797006c8326b47fa97721c9e66f07f940f3ec0864db2ae241a
 SHA512:
-  metadata.gz: e5f33eee0cbaedf8d21d6983e8672b72de97f58baab5a4c12ced685389d8e78b103f3f55974ba30a9d786e200ee5609ef3930a156614e502caafe80a56222e77
-  data.tar.gz: bcb99dcf463633f7762636ee7a75b247fde3e2438e2eddfb76e977014d84bb2ab65bc6f88d0df6932f5e16adfa3d533712bab8f36fa96f45bd442b990cd7f448
+  metadata.gz: f0e5532e52f873a3cb659dbf90fde582974f4840609f0c8365318f5b862659475484232e9ead3fd0074ec1a079db565cd8046a157ceb4f1bc1099b08877feded
+  data.tar.gz: e6bd4fe02b30344a494a8af944ab6ca94e07f944d143d99bd4f116ca3f15099a5fbbe840b38c1b186398c43c3b23825889fd4b852593fc09342edc50910cd4e9

data/CHANGELOG.md

@@ -5,6 +5,279 @@ 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
+
+- Static tier: `serve` and `tool` fall back to source-file analysis when the
+  app cannot boot, instead of exiting. Routes (new `config/routes.rb` Prism
+  walker), models, controllers, schema, and migrations answer statically;
+  other sections report `[UNAVAILABLE]` with the reason; every response
+  carries a tier banner.
+- CLI flags: `--no-boot` (serve/tool), `--app-path` (all app-reading
+  commands), and `--environment` (all commands).
+- `[STATIC]` and `[UNAVAILABLE: <reason>]` confidence tags.
+- structure.sql parsing is dialect-aware: MySQL (backticks, inline
+  KEY/CONSTRAINT definitions, ENGINE trailers) and SQLite (quoted
+  identifiers, IF NOT EXISTS) now parse; output gains a `dialect` key.
+- Shape-aware discovery: models and controllers are found in packwerk
+  `packs/`, in-repo `engines/`, and configured `extra_app_paths`.
+- Multi-database schema dumps (`db/*_schema.rb`, `db/*_structure.sql`)
+  reported under `secondary_databases`.
+- Mongoid detection: honest `[UNAVAILABLE]` schema signal and basic static
+  model extraction (fields, embeds, store_in) for Mongoid apps.
+- API-only apps get explicit "not applicable" answers from view/frontend
+  tools instead of empty listings.
+- **Loud Rails 9 warning in the standalone CLI.** In-Gemfile installs already
+  fail Bundler resolution against Rails 9 (`railties < 9.0`); the standalone
+  CLI has no such check, so it used to boot silently against an untested
+  Rails version. It now prints a stderr warning naming the installed Rails
+  version and pointing at checking for a newer gem release.
+- **`docs/COMPATIBILITY.md`** publishes the supported-version matrix, the CI
+  version grid, the RUNTIME/STATIC tier contract with the confidence-tag
+  vocabulary, and a shape-by-introspector matrix that cites the spec or QA
+  run proving every cell.
+
+### Changed
+
+- Boot failure in `tool`/`serve` no longer exits 1; it degrades to the
+  static tier with a stderr notice. `doctor` keeps requiring a bootable app.
+- CI runs Rails 8.x on Ruby 3.2 again. The exclusion assumed Rails 8
+  required Ruby 3.3+; both railties 8.0.5 and 8.1.3 declare
+  `required_ruby_version >= 3.2.0`.
+
+### Fixed
+
+- `config.auto_mount = true` set in a user initializer now takes effect
+  (the middleware initializer ran before user initializers loaded).
+- `prism` and `concurrent-ruby` are now capped below their next majors
+  (`< 2.0`, `< 3.0`) instead of an open-ended floor.
+- A syntax error in one model file now costs exactly that model - the rest
+  of the models section, and every other section, still answers normally
+  (verified end-to-end in the static tier).
+
 ## [5.14.0] - 2026-07-11
 
 ### Added

data/README.md

@@ -448,6 +448,44 @@ Both paths ask which AI tools you use (Claude Code, Cursor, GitHub Copilot, Open
 
 <br>
 
+## Static tier: works even when the app can't boot
+
+`rails-ai-context` attempts a full boot for live reflection. When boot fails
+(missing ENV vars, unreachable services, a broken initializer) the `serve`
+and `tool` commands fall back to the **static tier** instead of dying:
+routes come from parsing `config/routes.rb`, schema from `db/schema.rb` /
+`db/structure.sql` / migrations, models and controllers from their source
+files. Every response carries a banner explaining the degradation, static
+data is tagged `[STATIC]`, and sections that genuinely need a booted app
+report `[UNAVAILABLE]` with the reason.
+
+Flags:
+
+- `--no-boot` (serve, tool) - skip the boot attempt entirely and serve
+  static analysis. Fast, and immune to boot-time side effects.
+- `--app-path PATH` (all app-reading commands) - run against a Rails app in
+  another directory.
+- `--environment ENV` (all commands) - set RAILS_ENV for the boot attempt.
+
+`rails-ai-context doctor` still requires a bootable app: its job is
+diagnosing why boot fails.
+
+<br>
+
+## App shapes
+
+Beyond the conventional layout, code is discovered in packwerk packs
+(`packs/*/app/*`), in-repo engines (`engines/*/app/*`), and any directories
+listed in `extra_app_paths` in `.rails-ai-context.yml`. Rails multi-database
+schema dumps (`db/queue_schema.rb` and friends) are reported under a
+`Secondary databases` section. Mongoid apps get an honest
+`[UNAVAILABLE]` schema signal plus basic static model data (fields, embedded
+relations) instead of misleading empty output, and API-only apps get
+"not applicable" answers from view and frontend tools instead of silent
+empty listings.
+
+<br>
+
 ## Documentation
 
 | | |
@@ -465,6 +503,7 @@ Both paths ask which AI tools you use (Claude Code, Cursor, GitHub Copilot, Open
 | **[Standalone](docs/STANDALONE.md)** | Use without Gemfile entry |
 | **[Troubleshooting](docs/TROUBLESHOOTING.md)** | Common issues and fixes |
 | **[FAQ](docs/FAQ.md)** | Frequently asked questions |
+| **[Compatibility](docs/COMPATIBILITY.md)** | Supported versions, operating tiers, and the shape matrix with proof sources |
 
 <br>
 
@@ -484,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):
@@ -523,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/COMPATIBILITY.md

@@ -0,0 +1,219 @@
+<div align="center" markdown="1">
+
+# Compatibility
+
+**What's actually supported, what's actually proven, and where each claim comes from.**
+
+[Architecture](ARCHITECTURE.md) · [Introspectors](INTROSPECTORS.md) · [Troubleshooting](TROUBLESHOOTING.md) · [FAQ](FAQ.md)
+
+</div>
+
+---
+
+Every claim below cites the spec file or release that proves it. No entry in this
+document is aspirational.
+
+## Supported versions
+
+- **Ruby:** 3.1 - 4.0 (gemspec: `required_ruby_version >= 3.1.0`, no upper cap)
+- **Rails (railties):** 7.0 - 8.1 (gemspec: `railties >= 7.0, < 9.0`)
+- **mcp gem:** `>= 0.8, < 2.0`
+- **thor:** `>= 1.0, < 3.0`
+- **prism:** `>= 0.28, < 2.0`
+- **concurrent-ruby:** `>= 1.2, < 3.0`
+
+The gemspec's `railties` bound is wider than the CI matrix: point releases inside
+7.0-8.1 and any future 8.x minor satisfy Bundler's constraint without a gem
+release, but only the combinations in the table below are actually exercised by
+CI.
+
+### CI matrix
+
+Source: `.github/workflows/ci.yml`. 17 of 25 possible Ruby x Rails combinations
+run (`fail-fast: false`, so one failing cell doesn't hide the rest):
+
+| Ruby \ Rails | 7.0 | 7.1 | 7.2 | 8.0 | 8.1 |
+|:---|:---:|:---:|:---:|:---:|:---:|
+| 3.1 | yes | yes | yes | - | - |
+| 3.2 | - | yes | yes | yes | yes |
+| 3.3 | - | yes | yes | yes | yes |
+| 3.4 | - | yes | yes | yes | yes |
+| 4.0 | - | - | - | yes | yes |
+
+- Rails 7.0 runs only on Ruby 3.1 (7.0 predates upstream Ruby 3.2+ support).
+- Rails 8.0/8.1 run on Ruby 3.2+ (both declare `required_ruby_version >= 3.2.0`
+  upstream; they never needed 3.3).
+- Ruby 4.0 runs only against Rails 8.0/8.1 (7.x has no upstream Ruby 4
+  support).
+- RuboCop runs once inside the matrix (Ruby 3.3 / Rails 8.0) and again in a
+  dedicated `lint` job pinned to Ruby 3.3.
+
+### Rails 9
+
+Not supported, and the two install paths fail differently:
+
+- **In-Gemfile:** the gemspec's `railties < 9.0` constraint makes `bundle
+  install`/`bundle exec` fail dependency resolution outright when the host
+  app's Gemfile locks Rails 9 - the gem never loads.
+- **Standalone:** the CLI pre-loads the gem into its own `GEM_HOME` before the
+  host app boots, so no Bundler constraint applies. `exe/rails-ai-context`
+  prints a stderr warning after a successful boot when
+  `Rails::VERSION::MAJOR >= 9`, naming the installed Rails version and
+  pointing at checking for a newer gem release. Introspection itself is
+  untested on Rails 9 either way.
+
+## Operating tiers
+
+Two tiers, both reachable over the CLI and MCP (stdio and HTTP):
+
+**RUNTIME** - the app booted. Introspectors read live Rails reflection
+(ActiveRecord connections, `Rails.application.routes`, loaded classes) plus the
+Prism AST layer for source-level facts (scopes, callbacks, strong params).
+
+**STATIC** - the app didn't boot, or `--no-boot` was passed. Only introspectors
+that define a `static_call` path can answer without a booted app:
+
+| Introspector | Static source |
+|:---|:---|
+| `schema` | `db/schema.rb` / `db/structure.sql` / migration files |
+| `migrations` | migration file list + `db/structure.sql`'s trailing `schema_migrations` insert |
+| `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 |
+
+The other 34 introspectors (views, jobs, gems, turbo, i18n, active_storage,
+auth, api, and the rest) have no static path and report `{ unavailable: reason
+}` in this tier - by construction, not by shape: `Introspector#run_introspector`
+(`lib/rails_ai_context/introspector.rb`) falls back to the same message
+regardless of what triggered the static tier.
+
+`doctor` never enters the static tier - its job is diagnosing why boot failed,
+so it always requires a bootable app.
+
+Boot failure degrades `serve`/`tool` to the static tier automatically (proven
+across four boot-failure modes - raises, prints to stdout, writes via the
+`STDOUT` constant, and hangs past the timeout - in
+`spec/e2e/boot_resilience_spec.rb`); `--no-boot` forces it without attempting a
+boot at all (`spec/e2e/static_tier_spec.rb`).
+
+### Confidence vocabulary
+
+Source: `lib/rails_ai_context/confidence.rb`.
+
+| Tag | Meaning |
+|:---|:---|
+| `[VERIFIED]` | Runtime-confirmed value, or a static literal the AST resolves with certainty |
+| `[STATIC]` | Derived from source files without a booted app - trustworthy structure, not runtime-confirmed |
+| `[INFERRED]` | Heuristic: a dynamic expression, metaprogramming, or a runtime-only construct the AST can't fully resolve |
+| `[UNAVAILABLE: reason]` | The data source is absent entirely |
+
+`[VERIFIED]`/`[INFERRED]` are per-value tags applied inside the schema, model,
+route, controller, and mailbox-routing introspectors as they walk the AST
+(`Confidence.for_node`). `[STATIC]`/`[UNAVAILABLE]` are whole-response tags:
+`[STATIC]` marks any answer that came from the static tier; `[UNAVAILABLE]`
+marks a section with no static path, or (in either tier) a data source that
+genuinely doesn't exist for this app.
+
+## Shape matrix
+
+Rows are app shapes; columns are schema, models, routes, and controllers
+(the four whose static behavior varies by shape), plus views for contrast.
+`n/a` means the shape doesn't change that introspector's behavior - see
+the stock full-stack row for its baseline proof. Reference numbers point at
+the proof list below the table.
+
+| Shape | Schema | Models | Routes | Controllers | Views |
+|:---|:---|:---|:---|:---|:---|
+| Stock full-stack (`schema.rb`) | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime only [2] |
+| API-only | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime + static [1] | runtime, "not applicable" [3] |
+| `structure.sql` - PostgreSQL dialect | static [4] | n/a | n/a | n/a | n/a |
+| `structure.sql` - MySQL/Trilogy dialect | static [4] | n/a | n/a | n/a | n/a |
+| `structure.sql` - SQLite dialect | static [4] | n/a | n/a | n/a | n/a |
+| Multi-DB `solid_*` schema dumps | static, `secondary_databases` [5] | n/a | n/a | n/a | n/a |
+| Packwerk `packs/` | n/a | static [5] | n/a | n/a | n/a |
+| In-repo `engines/` | n/a | n/a | n/a | static [5] | n/a |
+| Mongoid | `[UNAVAILABLE]`, honest signal [6] | static (fields + embeds) [6] | n/a | n/a | n/a |
+| Broken-boot (any full-stack app) | static [7] | static, per-file isolation [7] | static [7] | static [7] | `[UNAVAILABLE]` [8] |
+| Packs + engines under `--no-boot` | n/a | static [5] | n/a | static [5] | n/a |
+| Empty/greenfield app (no scaffold) | graceful, no crash [9] | graceful, no crash [9] | graceful, no crash [9] | graceful, no crash [9] | graceful, no crash [9] |
+| Massive app (500 models/tables) | no crash at scale [10] | no crash at scale [10] | no crash at scale [10] | n/a | n/a |
+
+Proof sources:
+
+1. `spec/e2e/in_gemfile_install_spec.rb`, `standalone_install_spec.rb`,
+   `zero_config_install_spec.rb` (schema, routes, model_details, and controllers
+   exercised across the install-path suite - in-Gemfile, standalone, zero-config);
+   real Rails 8.0 apps in the v5.14.0 release QA (`blog`, `sandbox`).
+2. Non-crash coverage for every built-in tool including `get_view` in
+   `spec/e2e/in_gemfile_install_spec.rb`'s full-tool sweep; output correctness
+   (ivar cross-check, render-form detection, partial interfaces) verified
+   against the real `blog` app in the v5.14.0 release QA.
+3. Unit specs for the "not applicable" API-only messaging: `get_view_spec.rb`,
+   `get_component_catalog_spec.rb`, `get_turbo_map_spec.rb`,
+   `get_partial_interface_spec.rb`, `get_stimulus_spec.rb`, `get_api_spec.rb`;
+   real Rails 8 `--api` app (`api_app`) in the v5.14.0 release QA.
+4. `spec/lib/rails_ai_context/introspectors/schema_introspector_spec.rb`
+   ("with a valid structure.sql fixture", "with a MySQL (mysqldump)
+   structure.sql", "with a SQLite structure.sql"). Unit-proven only - no
+   committed e2e fixture writes a `structure.sql` file. The MySQL/Trilogy
+   adapter itself (live queries, not the dump format) was also run for real
+   against MySQL 9.6 in the v5.14.0 release QA (`store` app,
+   `schema_format = :sql`).
+5. `spec/e2e/shapes_spec.rb`: "packs and engines code discovery (static
+   tier)" and "multi-database schema dumps".
+6. `spec/e2e/shapes_spec.rb`: "Mongoid app (bare directory, --app-path, no
+   boot possible)".
+7. `spec/e2e/boot_resilience_spec.rb` (four boot-failure modes: raises,
+   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
+   `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
+   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`
+    (plus `context`, `onboard`, `analyze_feature`, `get_turbo_map`, `get_env`)
+    sampled against 500 generated models/tables under a 180-second cap.
+
+Postgres itself - live query safety (read-only transactions, the
+`BLOCKED_FUNCTIONS` guard against `pg_read_file`/`dblink`/`COPY ... PROGRAM`,
+DDL rejection) alongside schema/routes - is proven end-to-end against a real
+Postgres instance in `spec/e2e/postgres_install_spec.rb`, opt-in via
+`TEST_POSTGRES=1` and skipped otherwise.
+
+## Known limits
+
+- **Concern-style Mongoid documents in runtime results.** Mongoid documents
+  are invisible to ActiveRecord reflection, so `ModelIntrospector#call` falls
+  back to the same source-parsing pass used in the static tier even when the
+  app is booted (`lib/rails_ai_context/introspectors/model_introspector.rb`).
+  Fields or associations defined in an included concern module rather than
+  directly in the document class body are not resolved, in either tier.
+- **Static-tier API-only detection.** `Tools::BaseTool#api_only_app?` reads
+  `app.config.api_only`. `RailsAiContext::StaticApp` exposes no `config`
+  method, so this check is always false in the static tier - the "not
+  applicable" messaging for view/frontend tools on API-only apps only fires
+  once the app has actually booted.
+- **Live multi-DB connections are not iterated, only dumps.**
+  `MultiDatabaseIntrospector` (replicas, sharding, per-model connection
+  assignment) has no static path and reports `[UNAVAILABLE]` in the static
+  tier. Only the schema introspector's own secondary-database dump parsing
+  (`db/*_schema.rb`, `db/*_structure.sql`) works without a boot.
+- **Constraints and lambda routes surface as a dynamic tally, not resolved
+  entries.** `RouteIntrospector#static_call` counts routes behind
+  `constraints do...end` blocks, lambdas, `devise_for`, and `concern`-based
+  route declarations into a `dynamic_routes` count rather than fabricating
+  per-route controller/action pairs it can't actually determine from source.
+
+<br>
+
+---
+
+<div align="center">
+
+[Back to README](../README.md)
+
+</div>

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