rails-ai-context 5.14.0 → 5.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab9892f397e65d076b20e20f7a01da83cd70b1bfb2a2d71fe9949e09616d7bdb
-  data.tar.gz: 3f5021a82283731cc7ea915bfbab0b11f06950d5bbc9fd9b656ca70fe43d6cc9
+  metadata.gz: 0250405dffbfbb2100bf513cc75840ae980f68970e1a76911c4b2cc5ba3fac77
+  data.tar.gz: 25606a4264641a0a1be621bb30f3476c9ce1ecc1fd8dc37f7719ab15acee5e14
 SHA512:
-  metadata.gz: e5f33eee0cbaedf8d21d6983e8672b72de97f58baab5a4c12ced685389d8e78b103f3f55974ba30a9d786e200ee5609ef3930a156614e502caafe80a56222e77
-  data.tar.gz: bcb99dcf463633f7762636ee7a75b247fde3e2438e2eddfb76e977014d84bb2ab65bc6f88d0df6932f5e16adfa3d533712bab8f36fa96f45bd442b990cd7f448
+  metadata.gz: 88b6c43ddb2d47e8c7d428e0188fc9060584252d7457bcd5d5b580cba6029a73f383684582d04228c79aee1a5c014f5d65494439697e718d38844900a3b5890a
+  data.tar.gz: 00e2c762d693c804f0260b5e0d054ffb0443afd8271299a8711638f23b7a6aeaeaee68ea833ed788225086fc38ddb289b5de562fb3e5379d78e8a84cd6c75f3b

data/CHANGELOG.md

@@ -5,6 +5,57 @@ 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

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>
 

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/exe/rails-ai-context

@@ -39,18 +39,23 @@ class RailsAiContextCLI < Thor
     # and `-v` fall through to "Could not find command" instead of the `version` task.
     map %w[--version -v] => :version
 
+    class_option :app_path, type: :string,
+      desc: "Path to the Rails app root (default: current directory)"
+    class_option :environment, type: :string,
+      desc: "RAILS_ENV to run under (default: the ambient RAILS_ENV or development)"
+
     desc "tool [NAME]", "Run an MCP tool. Use --list to see all."
     option :json, type: :boolean, default: false, desc: "Output as JSON envelope"
     option :list, type: :boolean, default: false, desc: "List available tools"
+    option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
     def tool(name = nil, *args)
       if options[:list] || name.nil?
         print_tool_list
         return
       end
 
-      boot_rails!
-
       if args.include?("--help") || args.include?("-h")
+        require "rails_ai_context"
         tool_class = ::RailsAiContext::CLI::ToolRunner.new(name, []).tool_class
         puts ::RailsAiContext::CLI::ToolRunner.tool_help(tool_class)
         return
@@ -64,6 +69,13 @@ class RailsAiContextCLI < Thor
       json_mode = true if args.delete("--json")
       json_mode = true if args.delete("-j")
 
+      # stop_on_unknown_option! passes post-name flags through into args;
+      # honor --no-boot in either position, mirroring the --json handling.
+      no_boot = options[:no_boot]
+      no_boot = true if args.delete("--no-boot")
+
+      boot_rails!(allow_static: true, no_boot: no_boot)
+
       runner = ::RailsAiContext::CLI::ToolRunner.new(name, args, json_mode: json_mode)
       puts runner.run
       exit 1 if runner.error
@@ -77,8 +89,9 @@ class RailsAiContextCLI < Thor
     desc "serve", "Start MCP server (stdio transport)"
     option :transport, type: :string, default: "stdio", desc: "Transport: stdio or http"
     option :port, type: :numeric, default: 6029, desc: "HTTP port (only for http transport)"
+    option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
     def serve
-      boot_rails!
+      boot_rails!(allow_static: true)
 
       transport = options[:transport].to_sym
       if transport == :http
@@ -550,7 +563,7 @@ class RailsAiContextCLI < Thor
         require "rails_ai_context"
         puts ::RailsAiContext::CLI::ToolRunner.tool_list
         puts ""
-        puts "Run inside a Rails app to execute tools."
+        puts "Run inside a Rails app to execute tools - static source analysis works even when the app can't boot (see --no-boot)."
       rescue LoadError, StandardError => e
         $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
         $stderr.puts "Run this command from your Rails app root directory."
@@ -577,11 +590,22 @@ class RailsAiContextCLI < Thor
     # capture references BEFORE Rails boot runs and re-register them afterwards.
     STANDALONE_REQUIRED_GEMS = %w[mcp json-schema addressable public_suffix].freeze
 
-    def boot_rails!(context: nil)
+    def boot_rails!(context: nil, allow_static: false, no_boot: false)
+      app_root = File.expand_path(options[:app_path] || Dir.pwd)
+      # Relative paths inside the app (log/, tmp/, sqlite files) assume the
+      # process cwd is the app root, so honor --app-path by moving there.
+      Dir.chdir(app_root) if options[:app_path]
+      ENV["RAILS_ENV"] = options[:environment] if options[:environment]
+
+      if allow_static && (no_boot || options[:no_boot])
+        enter_static_tier!("static mode requested with --no-boot")
+        return
+      end
+
       config_path = File.join(Dir.pwd, "config", "environment.rb")
       unless File.exist?(config_path)
         $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
-        $stderr.puts "Run this command from your Rails app root directory."
+        $stderr.puts "Run this command from your Rails app root directory (or pass --app-path)."
         exit 1
       end
 
@@ -621,6 +645,18 @@ class RailsAiContextCLI < Thor
       result = ::RailsAiContext::BootManager.boot!(app_root: Dir.pwd, timeout: timeout)
 
       unless result.booted?
+        if allow_static
+          $stderr.puts "[rails-ai-context] App boot failed: #{result.failure_summary}"
+          if result.error.is_a?(::RailsAiContext::BootManager::BootTimeoutError)
+            $stderr.puts "[rails-ai-context]   If the app is healthy but slow, raise RAILS_AI_CONTEXT_BOOT_TIMEOUT (seconds, current: #{timeout})."
+          end
+          $stderr.puts "[rails-ai-context] Serving static analysis; runtime-only data is marked [UNAVAILABLE]."
+          $stderr.puts "[rails-ai-context] Run `rails-ai-context doctor` for boot diagnostics."
+          restore_standalone_environment!(pre_boot_paths, pre_boot_specs)
+          enter_static_tier!(result.failure_summary)
+          return
+        end
+
         $stderr.puts "Error: Rails app failed to boot in #{Dir.pwd}"
         $stderr.puts "  #{result.failure_summary}"
         if ENV["DEBUG"]
@@ -643,24 +679,44 @@ class RailsAiContextCLI < Thor
         exit 1
       end
 
-      # Restore paths and specs that Bundler.setup stripped (standalone mode).
-      # For Gemfile users, both restorations are no-ops.
+      restore_standalone_environment!(pre_boot_paths, pre_boot_specs)
+
+      require "rails_ai_context"
+
+      if defined?(Rails::VERSION::MAJOR) && Rails::VERSION::MAJOR >= 9
+        $stderr.puts "[rails-ai-context] WARNING: Rails #{Rails.version} is newer than this gem supports (< 9.0)."
+        $stderr.puts "[rails-ai-context]   Introspection is untested on this version and may be wrong or incomplete."
+        $stderr.puts "[rails-ai-context]   Check for a newer rails-ai-context release."
+      end
+
+      RailsAiContext::Configuration.auto_load!
+    end
+
+    # Bundler.setup during app boot strips $LOAD_PATH and the spec registry
+    # to Gemfile-resolved gems; in standalone mode our own transitive deps
+    # (mcp, json-schema) vanish. Splice back what was captured pre-boot.
+    def restore_standalone_environment!(pre_boot_paths, pre_boot_specs)
       (pre_boot_paths - $LOAD_PATH).each { |p| $LOAD_PATH << p }
       pre_boot_specs.each { |name, spec| Gem.loaded_specs[name] ||= spec }
 
-      # Loud warning if any required spec couldn't be restored — silent failure
-      # here means tools will crash later with `undefined method 'full_gem_path'
-      # for nil` from inside the MCP SDK.
       missing = STANDALONE_REQUIRED_GEMS.reject { |g| Gem.loaded_specs.key?(g) }
-      if missing.any? && !ENV["BUNDLE_BIN_PATH"]
-        $stderr.puts "[rails-ai-context] WARNING: standalone CLI could not restore gemspec(s): #{missing.join(', ')}."
-        $stderr.puts "[rails-ai-context]   Tool calls may crash with `undefined method 'full_gem_path' for nil`."
-        $stderr.puts "[rails-ai-context]   Try `gem install rails-ai-context` to ensure all transitive deps are installed."
-      end
+      return if missing.none? || ENV["BUNDLE_BIN_PATH"]
 
-      require "rails_ai_context"
+      $stderr.puts "[rails-ai-context] WARNING: standalone CLI could not restore gemspec(s): #{missing.join(', ')}."
+      $stderr.puts "[rails-ai-context]   Tool calls may crash with `undefined method 'full_gem_path' for nil`."
+      $stderr.puts "[rails-ai-context]   Try `gem install rails-ai-context` to ensure all transitive deps are installed."
+    end
 
-      RailsAiContext::Configuration.auto_load!
+    # Static tier: the gem loads standalone (no app constants), introspection
+    # runs against the filesystem, and every tool response carries the tier
+    # banner so consumers know runtime data is absent.
+    def enter_static_tier!(reason)
+      require "rails_ai_context"
+      ::RailsAiContext.tier = :static
+      ::RailsAiContext.static_reason = reason
+      ::RailsAiContext.configuration.app_root = Dir.pwd
+      ::RailsAiContext::Configuration.auto_load!
+      $stderr.puts "[rails-ai-context] static tier active: #{reason}"
     end
 
     # Look up each required gem via Gem::Specification.find_by_name BEFORE

data/lib/rails_ai_context/app_kind.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # Detects app-level facts that change which introspection applies, from
+  # artifacts that exist without booting (config files, Gemfile.lock).
+  module AppKind
+    module_function
+
+    # The four-space indent plus "(" matches Bundler's resolved-spec line
+    # exactly, so gems that merely contain the name do not false-positive.
+    def mongoid?(root)
+      root = root.to_s
+      return true if File.exist?(File.join(root, "config", "mongoid.yml"))
+
+      lock = File.join(root, "Gemfile.lock")
+      return false unless File.exist?(lock)
+
+      content = RailsAiContext::SafeFile.read(lock)
+      !!content&.include?("    mongoid (")
+    end
+  end
+end

data/lib/rails_ai_context/confidence.rb

@@ -5,13 +5,25 @@ module RailsAiContext
   # Shared across tools and introspectors without creating
   # cross-layer dependencies.
   #
-  # VERIFIED: value extracted from a static, deterministic AST node
-  #           (symbol literals, string literals, integers, booleans).
-  # INFERRED: value involves dynamic expressions, metaprogramming,
-  #           or runtime-only constructs that AST cannot fully resolve.
+  # VERIFIED: value the gem can assert with certainty - runtime-confirmed data,
+  #           or a static literal the AST resolves deterministically (see for_node).
+  # STATIC: derived from source files without a booted app - trustworthy structure,
+  #         not runtime-confirmed.
+  # INFERRED: heuristic - dynamic expressions, metaprogramming, or runtime-only
+  #           constructs the AST cannot fully resolve.
+  # UNAVAILABLE: the data source is absent entirely; the reasoned form says why.
   module Confidence
     VERIFIED = "[VERIFIED]"
     INFERRED = "[INFERRED]"
+    STATIC = "[STATIC]"
+    UNAVAILABLE = "[UNAVAILABLE]"
+
+    # Reasoned unavailability tag: "[UNAVAILABLE: requires a booted Rails app]".
+    # Reasons are collapsed to their first line so a raised exception message
+    # can be passed through without flooding the tag.
+    def self.unavailable(reason)
+      "[UNAVAILABLE: #{reason.to_s.lines.first.to_s.strip}]"
+    end
 
     # Determine confidence level for a Prism call node's arguments.
     # Returns VERIFIED if all arguments are static literals,

data/lib/rails_ai_context/configuration.rb

@@ -18,7 +18,7 @@ module RailsAiContext
       live_reload live_reload_debounce auto_mount http_path http_bind http_port
       output_dir skip_tools excluded_models excluded_controllers
       excluded_route_prefixes excluded_filters excluded_middleware excluded_association_names excluded_paths
-      sensitive_patterns search_extensions concern_paths frontend_paths
+      sensitive_patterns search_extensions concern_paths frontend_paths extra_app_paths
       max_file_size max_test_file_size max_schema_file_size max_view_total_size
       max_view_file_size max_search_results max_validate_files
       query_timeout query_row_limit query_redacted_columns allow_query_in_production
@@ -107,6 +107,12 @@ module RailsAiContext
     # Output directory for generated context files
     attr_accessor :output_dir
 
+    # Filesystem root of the app under analysis. Set by the CLI (--app-path
+    # or the working directory) for the static tier; nil means "ask Rails".
+    # Deliberately not a YAML key: the config file lives inside the app it
+    # would point at.
+    attr_accessor :app_root
+
     # Models/tables to exclude from introspection
     attr_accessor :excluded_models
 
@@ -229,6 +235,11 @@ module RailsAiContext
     # Frontend framework detection (optional overrides - auto-detected if nil)
     attr_accessor :frontend_paths         # User-declared frontend dirs (e.g. ["app/frontend", "../web-client"])
 
+    # Additional app-root-relative directories that also contain Rails app
+    # code (e.g. ["src", "vendor/internal"]). Code discovery scans each
+    # entry's app/models, app/controllers, and app/views subdirectories.
+    attr_accessor :extra_app_paths
+
     # Database query tool settings (rails_query)
     attr_accessor :query_timeout              # Statement timeout in seconds (default: 5)
     attr_accessor :query_row_limit            # Max rows returned (default: 100, hard cap: 1000)
@@ -297,6 +308,7 @@ module RailsAiContext
       @search_extensions        = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
       @concern_paths            = %w[app/models/concerns app/controllers/concerns]
       @frontend_paths           = nil
+      @extra_app_paths          = []
       @query_timeout            = 5
       @query_row_limit          = 100
       @query_redacted_columns   = %w[

data/lib/rails_ai_context/engine.rb

@@ -9,7 +9,11 @@ module RailsAiContext
     end
 
     # Auto-mount MCP HTTP middleware when configured
-    initializer "rails_ai_context.middleware" do |app|
+    # Must run after config/initializers so a user's
+    # `config.auto_mount = true` is visible when the mount decision is made;
+    # the middleware stack is built later in the boot finisher, so adding to
+    # it here still takes effect.
+    initializer "rails_ai_context.middleware", after: :load_config_initializers do |app|
       if RailsAiContext.configuration.auto_mount
         require_relative "middleware"
         app.middleware.use RailsAiContext::Middleware