rails-ai-context 5.13.0 → 5.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3747460b78ef9b52d5e2d4bbe59e348599499285fb0215a97ce029ad49b27aa0
-  data.tar.gz: 2f0fff5d8986ca5ead4d74933dac2c7933d2ca7bd7dd1cab11fc3c4c5c756106
+  metadata.gz: 0250405dffbfbb2100bf513cc75840ae980f68970e1a76911c4b2cc5ba3fac77
+  data.tar.gz: 25606a4264641a0a1be621bb30f3476c9ce1ecc1fd8dc37f7719ab15acee5e14
 SHA512:
-  metadata.gz: b343b7456a8f26c0738ebf3ca19b50758f54e859d82b3c40dba97765bde151f429f7da7b6d7a9abba2ac35438faaa858686c306e4f99482e2fc5a0b8692a7055
-  data.tar.gz: b18a15e6fcb931bc9ae34c340c8c3c2481092273e7c0d1ca3d63da3b40282f2a18988656a96588c2e80ea271ab2f4ebc224124b7872328663eb5bc63da93ea0f
+  metadata.gz: 88b6c43ddb2d47e8c7d428e0188fc9060584252d7457bcd5d5b580cba6029a73f383684582d04228c79aee1a5c014f5d65494439697e718d38844900a3b5890a
+  data.tar.gz: 00e2c762d693c804f0260b5e0d054ffb0443afd8271299a8711638f23b7a6aeaeaee68ea833ed788225086fc38ddb289b5de562fb3e5379d78e8a84cd6c75f3b

data/CHANGELOG.md

@@ -5,6 +5,119 @@ 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.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
+
+- **New `rails_get_api` tool (CLI: `api`)** exposing the API-layer introspection that was previously invisible on demand: API-only mode, serialization strategy (Jbuilder templates, serializer classes), GraphQL, versioning, rate limiting, OpenAPI specs, CORS, and pagination. On API-only apps the API layer was the least-served layer while six view tools returned nothing; this closes that gap. Tool count is now 39.
+- **`doctor --strict`** exits 1 when any check fails, giving CI a real gate. Default behavior is unchanged: doctor is a readiness report and exits 0.
+- **`rails_generate_test` scaffolds tests that pass out of the box.** Generated controller tests use the app's real routes, fixtures, and strong params; destroy tests create a fresh record instead of deleting a fixture row other fixtures hold foreign keys on; create/update params mutate values for columns backed by a unique index (a fixture's own value would collide). Verified by running the generated tests for real on scaffold HTML and API-only JSON controllers.
+
+### Added - Boot resilience
+
+- **Friendly boot-failure diagnostics.** Every CLI command (`tool`, `doctor`, `serve`, `context`, etc.) now boots the host app through `BootManager`, which catches `StandardError` and `ScriptError` alike. When the app can't boot -- a missing ENV var, an unreachable database or Redis, a syntax error in an initializer -- the CLI prints a one-line cause plus common-cause hints and exits 1, instead of a raw Thor backtrace. Boot is bounded by a 60-second timeout so a hanging initializer fails loudly rather than wedging the process; the timeout is configurable via `RAILS_AI_CONTEXT_BOOT_TIMEOUT`. A timed-out boot gets a dedicated message naming the configured limit and how to raise it, instead of the stdlib's `Timeout::Error: execution expired`. Set `DEBUG=1` for the full backtrace. `doctor` on an app that fails to boot appends one line noting it needs a bootable app to run its checks.
+- **stdout quarantine on every stdio launch path.** The stdio MCP transport carries JSON-RPC on stdout, so anything the host app prints while booting (initializer `puts`, deprecation warnings) used to corrupt the handshake and leave the client reporting a dead server. `OutputGuard` now redirects `$stdout` to `$stderr` for the duration of boot on every stdio launch path -- the `rails-ai-context serve` binary, the `rails ai:serve` rake task, and standalone mode. It also reopens file descriptor 1 onto `$stderr`'s target for that duration, so writes through the `STDOUT` constant (which bypass the `$stdout` global) and subprocess output inherited on fd 1 are caught too; only a descriptor duplicated before boot starts stays out of reach.
+- **Unexpected tool errors return in-band MCP error results instead of protocol errors.** Every registered tool's `call` is now wrapped so an unhandled exception produces an `isError: true` tool response (error class, origin line, and a recovery hint) rather than escaping to the MCP SDK, which turned it into a JSON-RPC -32603 protocol error that most AI clients silently swallow. Exceptions that still escape at the SDK level get a stderr backtrace via a new `exception_reporter`.
+- **Aggregate tools flag partial context.** `rails_get_context` and `rails_onboard` append a "Partial context" note listing which introspectors failed when any did, so an AI client can tell missing data from empty data. The note is appended after the truncation decision, so it survives response truncation instead of being cut off with the rest of the body.
+- **Generated MCP configs launch the quarantined CLI command.** All 5 generated config formats (Claude Code, Cursor, VS Code, OpenCode, and Codex CLI) now point at `bundle exec rails-ai-context serve` instead of `bundle exec rails ai:serve`, so new installs get stdout quarantine from before `Bundler.require` runs. `rails ai:serve` still works and now quarantines its own boot output too.
+
+### Fixed
+
+- Introspector fault isolation no longer crashes when `Rails.logger` is nil (early-boot rake tasks, engine dummy apps). The failure-logging call that the rescue exists to protect now falls back to `$stderr` via `RailsAiContext.log_warn` instead of raising `NoMethodError` on a nil logger.
+- `BaseTool.abstract!` now works when called on a subclass. It read `registry_mutex` and `descendants` off `self`, but those are ivars set on `BaseTool` itself -- a subclass has no ivar storage of its own to read them from, so the call raised `NoMethodError` on the nil mutex. It now reaches back to `BaseTool` explicitly.
+- Custom tools that subclass `RailsAiContext::Tools::BaseTool` must accept a `server_context:` keyword (or `**kwargs`) in `self.call` -- the MCP dispatch now always passes it.
+- **The install generator no longer crashes on non-interactive stdin.** Thor's `ask` returns `nil` on EOF (piping fewer answers than prompts, or `< /dev/null`), and the very next `.strip` call raised `NoMethodError`. Every prompt now goes through `ask_safe`, which treats EOF the same as an empty answer -- each prompt's existing default-handling logic takes it from there. A new `--defaults` flag skips every prompt outright for CI/scripted installs.
+- **`rails-ai-context --version` and `-v` work**, not just the `version` subcommand -- Thor only recognized the bare subcommand by default.
+- **Presets share one definition.** The rake task (`rails 'ai:preset[name]'`) and the CLI (`rails-ai-context preset name`) used to define their own, different tool lists under the same preset name. Both now read from `RailsAiContext::Presets::DEFINITIONS`, the single source of truth. The `migration` preset's old tool list called `migration_advisor` with an invalid `action` and `validate` with no files -- both require a caller-supplied target and only emitted errors on a healthy app; it now runs `get_schema`, `runtime_info`, and `performance_check` with zero arguments, matching what `architecture` and `debugging` already did correctly.
+- **`rails_performance_check` no longer claims "Your app looks good!" when a category or model filter is hiding issues elsewhere.** A zero count under a filter now says so explicitly and points back at the unfiltered call, instead of implying the whole app is clean.
+- **`rails_get_view`'s render map now detects the Rails 7+ bare local-variable render form** (`render article`, as the default scaffold generates), not just `render "partial"` and `render @article`. The scan excludes keyword-argument hashes (`render json:`, `render partial:`, ...) so it doesn't misread those as local-variable renders.
+- **`rails_get_view` accepts a full repo-relative path** (e.g. `app/views/layouts/mailer.html.erb`) in addition to the documented app/views-relative form -- previously a genuinely-existing file read as "not found" solely because of which convention the caller used.
+- **`rails_analyze_feature` no longer substring-matches unrelated identifiers.** `feature:"post"` used to pull in ActionMailbox's `postmark` ingress route because `"postmark".include?("post")` is true. Matching is now word-boundary aware (with basic singular/plural handling), so `post` still matches `posts`, `post_comments`, and `PostsController`, but not `postmark`.
+- Empty-result "not found" responses no longer end with a dangling `Available:` line when there's nothing to list (`rails_get_concern`, and any other tool built on the shared `not_found_response` helper).
+- `rails_get_partial_interface`'s "not found" suggestion list no longer lists the same partial twice when it exists under two extensions (e.g. `_article.html.erb` and `_article.json.jbuilder` both display as `articles/article`).
+- A non-numeric `RAILS_AI_CONTEXT_BOOT_TIMEOUT` value now falls back to the default with a stderr warning instead of raising a raw `ArgumentError` that surfaced as a Thor backtrace on `doctor`, `inspect_app`, and `watch`.
+- **`rails_get_conventions`'s create-action and read-only-page skeletons now reflect what's actually detected**, instead of a hardcoded `current_user`-based template labeled with real controller names regardless of whether any auth pattern existed. They're built from the union of flow parts actually matched, and only reference `current_user` when a permission or auth check was really found.
+- **`rails_analyze_feature`'s test counts are accurate again.** `discover_tests` counted the bare words `it`/`test`/`should` anywhere in a file's text, including comments and prose. It now counts line-anchored `test`/`it`/`specify` declarations and `def test_*` methods, matching how `rails_get_test_info` already counted correctly.
+- **CLI and rake tool failures exit non-zero.** `rails-ai-context tool NAME` and `rails 'ai:tool[NAME]'` used to exit 0 even when the tool itself reported failure (`isError: true`); both now exit 1 in that case, and `--json` output gains an `error` key so scripts can check it without parsing text. An unrecognized `rails-ai-context` subcommand also exits 1 instead of Thor's default 0. The "unknown tool" error message points at whichever `--list` invocation actually works for the caller (CLI vs rake) instead of always suggesting the CLI-only flag, and a blank tool-name query no longer produces an arbitrary "Did you mean" suggestion.
+- Routine MCP protocol errors (unknown tool, invalid params) now log as a single quiet line instead of a 10-line backtrace; only genuinely unhandled exceptions still get the full backtrace.
+- **Install generator output is honest about install mode and idempotency.** Generating context files for multiple selected AI-tool formats no longer reports the shared `AGENTS.md` trio as both written and unchanged in the same run. `.rails-ai-context.yml` writes report Created/Updated/unchanged consistently across the generator, standalone `init`, and the `ai:context` rake task. `.codex/config.toml` (which embeds a machine's Ruby PATH/GEM_HOME) is now flagged as local and added to `.gitignore` instead of told to commit it. Generated context files reference the `rails-ai-context` CLI binary instead of rake tasks on standalone installs, detected via a Gemfile.lock scan for the gem's own spec line.
+- Eight tool-output and doctor accuracy fixes from live QA: `rails_get_gems` points the Solid Queue config hint at `config/queue.yml`/`config/recurring.yml` (checked at runtime) instead of `config/solid_queue.yml`, which Rails 8's generator never writes; `doctor`'s gitignore check distinguishes a missing `.gitignore` file from a missing entry; `rails_get_model_details` no longer renders a bare "Key instance methods" heading when every candidate method was filtered out as an association accessor; `rails_onboard`'s route total shares dedup logic and prefix config with `rails_get_routes` instead of disagreeing with it; CLI `tool --list` truncates descriptions with an ellipsis instead of mid-word; `tool --list` falls back to loading the gem standalone when there's no app to boot; and `doctor`'s introspector-health message computes the tool count it compares against dynamically instead of hardcoding it.
+- **Tools stay truthful on API-only apps.** `rails_get_frontend_stack` reports "No frontend stack detected" instead of a lone "TypeScript: disabled" line implying a JS frontend exists. `rails_get_turbo_map` reports that Turbo isn't installed when `turbo-rails` isn't in `Gemfile.lock`, instead of an empty broadcast/subscription report. `rails_get_context`'s instance-variable cross-check recognizes ivars rendered via `render json: @foo`/`render xml: @foo` (which have no view template to cross-reference), and swaps "used in view" language for "used in response" on API-only apps; the generated CLAUDE.md/AGENTS.md workflow guide swaps its view-editing walkthrough for a JSON-endpoint walkthrough on the same apps. `app/models/concerns` and `app/controllers/concerns` are only reported as in-use patterns when they contain a real Ruby file, not just the `.keep` placeholder a fresh `rails new` leaves behind. `rails_get_conventions`'s create-action skeleton now emits `render json:` (and `render json: @record.errors`) instead of an HTML redirect when the app's create actions render JSON directly, not just via a scaffold's `respond_to` JSON branch.
+- **MySQL/Trilogy adapter parity.** Rails 8's default MySQL adapter reports `adapter_name` as "Trilogy", not "Mysql2", so every `/mysql/`-only regex dispatch silently fell through to unsafe or degraded fallbacks -- `rails_query`'s read-only transaction and statement timeout, `rails_runtime_info`'s table sizes, and the database-stats introspector now all match `/mysql|trilogy/i`. `rails_query`'s `SHOW`/`DESCRIBE`/`EXPLAIN` are exempted from row-limit appending (invalid syntax after those statements) and from column-name-based redaction (MySQL's `DESCRIBE` returns a literal "Key" column that isn't secret data); `EXPLAIN` on MySQL forces `FORMAT=TRADITIONAL` so parsing doesn't depend on the server's default explain format.
+- **Pending-migrations detection works again.** All three call sites (`rails_runtime_info`, `doctor`, the migration introspector) guarded on `respond_to?(:pending_migrations)`, which is never true on any currently supported Rails version, and fell back to an `ActiveRecord::Migrator.new` signature that raises on Rails 7.0+ -- it always reported zero pending migrations. A shared `MigrationStatus` helper now walks `migration_context.open.pending_migrations`, the same path Rails uses for its own "migrations are pending" error page; the file-based fallback also reads the schema version from `db/structure.sql`'s trailing `schema_migrations` insert, so `:sql`-format apps get correct results instead of always reporting zero.
+- `migration_advisor`'s locking advice is now adapter-aware instead of always suggesting Postgres-only `algorithm: :concurrently` and two-step foreign key validation on every adapter.
+- The generated tool-usage guide names `db/structure.sql` instead of `db/schema.rb` in its "don't read this file" guidance on apps configured with `schema_format = :sql`.
+- Fixed the remaining "N indexes"/"N files" pluralization misses: `rails_get_schema`'s summary view now says "1 column, 1 index" and `rails_get_conventions`'s directory structure says "1 file", matching the singular/plural handling already applied to table, issue, and test counts.
+- The CLI `preset` command's banner now uses a plain hyphen instead of an em dash, matching the rake task's output, and its per-tool "Running:" headers print to stdout (the same stream as the tool's own output) instead of stderr, so `2>&1` captures stay in order.
+- The install generator no longer emits raw terminal escape sequences (cursor hide/show, line clears) when stdin or stdout isn't a real terminal (`rails generate rails_ai_context:install < /dev/null`, captured CI logs). Thor's line editor now falls back to its plain, escape-free reader outside a genuine interactive TTY session.
+- **The generated initializer no longer crashes `bin/rails test` on path:/git: Gemfile installs scoped to `group :development`.** Bundler evaluates a path:/git: gemspec in-process during dependency resolution in every environment, so `require_relative "lib/rails_ai_context/version"` defines a VERSION-only stub `RailsAiContext` module even in environments where `Bundler.require` correctly skips the gem. The initializer's `if defined?(RailsAiContext)` guard was satisfied by that stub and called `.configure` on it anyway, raising `NoMethodError`. The guard now also checks `RailsAiContext.respond_to?(:configure)`; re-running the install generator upgrades an existing initializer's bare guard in place, and `doctor` warns when one is still on the old guard.
+- **`DEBUGGER__::TrapInterceptor` no longer shows up as a model concern.** The `debug` gem, default in Rails 7.0+ Gemfiles, prepends this module onto `Kernel`, so it appeared in every model's ancestors. It's now excluded the same way other framework-internal modules are.
+- **The `rails-ai-context://routes/{controller}` MCP resource returns real routes.** It filtered a flat `:routes` list that the route introspector never emits (routes are grouped under `:by_controller`), so every read returned an empty array. It now reads the real shape, merges the controller name back into each entry, and dedupes PUT/PATCH update pairs into one `PATCH|PUT` entry so the resource reports the same counts as the routes tool.
+- MCP resource contents use the spec field name `mimeType` instead of snake_case `mime_type`.
+- **Rails-internal routes are excluded correctly.** The route introspector guarded on `route.respond_to?(:internal?)`, but `ActionDispatch::Journey::Route` exposes the flag as a plain `internal` attribute, so the guard never matched and Rails' info/mailers/welcome routes leaked into route listings as "framework routes". The tool and the MCP resource now agree on route counts, and the routes header notes how many framework routes were excluded.
+- **`.mcp.json` content is stable across entry points.** The standalone `init` wrote `rails-ai-context serve` while the in-Gemfile generator and `ai:context` rake task wrote `bundle exec rails-ai-context serve`, so alternating commands rewrote the file on every run. All writers now derive the command from the detected install mode.
+- **`rails_validate` failures exit non-zero.** A failed validation ("0/1 files passed", real Prism diagnostics) is now an MCP error result, so the CLI exits 1 and CI can gate on it; passing validations still exit 0. `rails_query`'s genuine SQL execution errors (unknown column, syntax error) get the same treatment, while policy guardrail messages ("Blocked: contains UPDATE") remain informational at exit 0.
+- `rails-ai-context preset bogus` exits 1 with the available-presets list instead of exiting 0.
+- **`rails_get_conventions` renders the status symbol actually detected in the app's controllers** (`:unprocessable_content` on Rails 7.1+ scaffolds) instead of hardcoding `:unprocessable_entity` in a skeleton labeled "Detected in".
+- `rails_get_frontend_stack` reads the introspector's real output keys, so the Framework and Testing lines (React/Vue/Jest and friends) render again; they had been silently dropped for every app.
+- `rails_search_code` marks match lines with a `>` prefix and indents context lines, so matches are distinguishable in captured output; a legend line explains the markers.
+- `rails_diagnose` classifies an undefined method on a model by checking the model's real associations and columns, reporting "no association or column named X" instead of the generic nil-reference guidance.
+- `rails_review_changes` no longer leaks git's raw "fatal: not a git repository" stderr line above its own friendly message when run outside a repository.
+- The config tool lists every file in `config/initializers/`, not just the gem's own initializer.
+- CLI copy is install-mode aware everywhere: `tool --list`, per-tool help, unknown-tool errors, and the generated git pre-commit hook show only invocation forms that exist in the current install (standalone installs have no rake tasks). The `tree` command shows the binary name as its root and `inspect` under its public name.
+- Assorted output honesty from the final QA sweep: onboard only recommends `bin/dev` when the app has one, names the real queue adapter instead of mentioning Sidekiq on non-Sidekiq apps, labels implicit `belongs_to` validations as such, and pluralizes counts correctly; the view tool omits its "Directories with views:" enumeration when there are none; the standalone `facts` command matches the rake task's singular/plural forms and prints `_none_` instead of a bare Associations header; `rails_get_partial_interface` no longer lists ERB block parameters (`|form|`, `|error|`) as partial locals.
+
 ## [5.13.0] - 2026-07-10
 
 ### Added

data/README.md

@@ -20,8 +20,8 @@
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green)](https://registry.modelcontextprotocol.io)
 <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-CC0000)](https://github.com/crisnahine/rails-ai-context)
-[![Tests](https://img.shields.io/badge/Tests-2257%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
+[![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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 </div>
@@ -68,7 +68,7 @@ rails-ai-context serve    # start MCP server
 
 </div>
 
-Now your AI doesn't guess - it **asks your app directly.** 38 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.** 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.
 
 <br>
 
@@ -163,7 +163,7 @@ Native Rails controller transport. No separate process needed.
 
 ### CLI
 
-Same 38 tools, no server needed. Works in any terminal, any AI tool.
+Same 39 tools, no server needed. Works in any terminal, any AI tool.
 
 ```bash
 rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
@@ -351,7 +351,7 @@ Every tool is **read-only** and returns data verified against your actual app -
 
 </details>
 
-> **[All 38 tools with parameters →](docs/TOOLS.md)** &nbsp;|&nbsp; **[Real-world recipes →](docs/RECIPES.md)**
+> **[All 39 tools with parameters →](docs/TOOLS.md)** &nbsp;|&nbsp; **[Real-world recipes →](docs/RECIPES.md)**
 
 <br>
 
@@ -401,8 +401,8 @@ graph TD
 
     B["rails-ai-context\nPrism AST parsing · Cached · Confidence-tagged\nVFS: rails-ai-context:// URIs introspected fresh"]
 
-    B --> C["MCP Server\nstdio / HTTP\n38 tools · 5 templates"]
-    B --> D["CLI Tools\nRake / Thor\nSame 38 tools"]
+    B --> C["MCP Server\nstdio / HTTP\n39 tools · 5 templates"]
+    B --> D["CLI Tools\nRake / Thor\nSame 39 tools"]
     B --> E["Static Files\nCLAUDE.md · .cursor/rules/ · .cursorrules\n.github/instructions/"]
 
     style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
@@ -440,7 +440,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 38 tools |
+| `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any of the 39 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 |
@@ -448,12 +448,50 @@ 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
 
 | | |
 |:------|:------------|
 | **[Quickstart](docs/QUICKSTART.md)** | 5-minute getting started |
-| **[Tools Reference](docs/TOOLS.md)** | All 38 tools with every parameter |
+| **[Tools Reference](docs/TOOLS.md)** | All 39 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 |
@@ -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>
 
@@ -543,7 +582,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-2154 tests + 100-example e2e harness. 38 tools. 5 resource templates. 39 introspectors. Standalone or in-Gemfile.<br>
+2154 tests + 100-example e2e harness. 39 tools. 5 resource templates. 39 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

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 38 tools and functionality.
+Both provide the same 39 tools and functionality.
 
 ---
 
@@ -98,6 +98,8 @@ Run 23 diagnostic checks and report AI readiness score.
 ```bash
 rails ai:doctor
 rails-ai-context doctor
+rails-ai-context doctor --strict   # exit 1 when any check fails (CI gate)
+rails ai:doctor STRICT=1           # rake equivalent
 ```
 
 Checks include: schema existence, pending migrations, model files, routes, MCP config validity, introspector health, ripgrep availability, Prism gem, Brakeman gem, listen gem, gitignore security, auto_mount security, schema size, view count, and more.

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/TOOLS.md

@@ -2,7 +2,7 @@
 
 # MCP Tools Reference
 
-**All 38 read-only tools, with every parameter.**
+**All 39 read-only tools, with every parameter.**
 
 [Quickstart](QUICKSTART.md) · [Recipes](RECIPES.md) · [Custom Tools](CUSTOM_TOOLS.md) · [CLI Reference](CLI.md)
 
@@ -59,7 +59,7 @@ Individual lookup tools accept a **`detail`** parameter: `summary` (compact), `s
 | [Controllers & Routes](#controllers--routes) | `get_controllers`, `get_routes` |
 | [Views & Frontend](#views--frontend) | `get_view`, `get_stimulus`, `get_partial_interface`, `get_turbo_map`, `get_frontend_stack` |
 | [Testing & Quality](#testing--quality) | `get_test_info`, `generate_test`, `validate`, `security_scan`, `performance_check` |
-| [App Config & Services](#app-config--services) | `get_conventions`, `get_config`, `get_gems`, `get_env`, `get_helper_methods`, `get_service_pattern`, `get_job_pattern`, `get_component_catalog` |
+| [App Config & Services](#app-config--services) | `get_api`, `get_conventions`, `get_config`, `get_gems`, `get_env`, `get_helper_methods`, `get_service_pattern`, `get_job_pattern`, `get_component_catalog` |
 | [Data & Debugging](#data--debugging) | `dependency_graph`, `migration_advisor`, `search_docs`, `query`, `read_logs`, `diagnose`, `review_changes`, `runtime_info`, `session_context` |
 
 <p align="right"><a href="#table-of-contents">↑ back to top</a></p>
@@ -303,6 +303,14 @@ N+1 query risks, missing indexes, missing counter_cache, eager load candidates.
 
 ## App Config & Services
 
+### `rails_get_api`
+
+API layer: api_only mode, serialization strategy (Jbuilder, serializers), GraphQL, versioning, rate limiting, OpenAPI specs, CORS, pagination.
+
+| Parameter | Type | Default | Description |
+|:----------|:-----|:--------|:------------|
+| `detail` | enum | `standard` | `summary` (one-liner), `standard` (per-area breakdown), `full` (adds OpenAPI spec paths) |
+
 ### `rails_get_conventions`
 
 Auth checks, flash messages, create action template, test patterns.

data/docs/index.md

@@ -22,7 +22,7 @@ Works with Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI.
 
 | Guide | Description |
 |:------|:------------|
-| **[Tools Reference](TOOLS.md)** | All 38 tools with every parameter |
+| **[Tools Reference](TOOLS.md)** | All 39 tools with every parameter |
 | **[Configuration](CONFIGURATION.md)** | 40+ config options with defaults |
 | **[CLI Reference](CLI.md)** | Commands and argument syntax |
 | **[Introspectors](INTROSPECTORS.md)** | All 39 introspectors and AST engine |