rails-ai-context 5.21.3 → 5.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8afb263c0004a822a803eee097300e87dcb5a3a2de27d996a3cc5f11ea801051
-  data.tar.gz: 462a8ca8d7f4a66cd617af71322356908f513aa88ac7aec2046f32cf4279805f
+  metadata.gz: 45c3818bdd2790c10c54e008bbbd22cf48b621195b89e869a1cd22e6f7e01e44
+  data.tar.gz: 6374c7cf2bad6c28a58216e96b94a36dfc71e2af6aff5095a0b98a4d843d4ec3
 SHA512:
-  metadata.gz: 2f48e61abb15f942c9a3b41eced790ce41618f091e337d84c1d598486e74e3a58e3331c9acf971ad2fea0d0a0bb8a909caef4c6b9fd3196fba51dbe318532e97
-  data.tar.gz: 07e4b2759758da12d51805c0861e8a101fcdefdff55cba0db7714c6464473e486842fbd93c55b6480c8ce7b87325138fa18eb0920c38e219f0df3556a1ec0b19
+  metadata.gz: 29b3386f4b8638e8059c42a39558547f08e7a1d5ac21197d8c09ba62a319852af5e6c7f206a63eafe378e03eac233e24f3784eb7bdf14f4ca40ff86afd12c2d3
+  data.tar.gz: 94e6915c0fd3e9472bb5792d1cd866f9c41711143ce877e39bdd461e8dfcd40280cffabeca4b4974efbd2d3f52514d438530b73cd16df033e43215a6bb519eb3

data/CHANGELOG.md

@@ -5,6 +5,348 @@ 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.24.0] - 2026-08-17
+
+### Fixed
+
+Defects found by a QA round against GitLab, OpenProject, Canvas LMS,
+Discourse and Mastodon. Every one of them exits 0.
+
+- **The commands that read the app degrade the way `tool` does.** `context`,
+  `inspect`, `facts`, `preset`, `watch` and `init` called a bare boot guard,
+  so on a repo you have just cloned - the case an agent most needs a
+  `CLAUDE.md` for, and the case least likely to boot - every tool answered
+  and the command that writes the files exited 1 having written nothing.
+  `init` was worse: it writes its config files first, so a boot failure left
+  the app half set up and called that a failure. They allow the static tier
+  now and each takes `--no-boot`; `doctor` still fails, because diagnosing
+  the boot is its job. Writing under `--no-boot` then exposed its own bug -
+  the context writer asked `Rails.application` for the output directory,
+  which raises `NameError` on the path where Rails is never loaded at all.
+- **`tool --list` reads the app's config when the app cannot boot.** Boot is
+  what normally loads `.rails-ai-context.yml`, so the listing fell back to
+  the gem's defaults: on Mastodon it advertised 45 tools while the MCP server
+  offered 43 and the CLI itself answered `Unknown tool 'query'` for one it
+  had just listed.
+- **`search_extensions` is documented as the fallback's list, which is what
+  it is.** Making ripgrep honour it did make the two backends agree, and it
+  cost the reach that makes the tool useful: on Mastodon `gem 'devise'` went
+  from 5 results to none, because a Gemfile carries no listed extension - and
+  the same for a Rakefile, a `.md`, a `.sql`. The docs, the attr comment and
+  the line the install generator writes now say plainly that the list is the
+  Ruby fallback's and that ripgrep searches every file.
+- **A table the replay cannot name is not reported.** Canvas has a migration
+  that calls `create_table table_name do |t|` with a local computed at run
+  time; the replay kept the entry under a nil key, and the first serializer
+  to sort the table names took the whole context run down. Reachable only
+  once `context` could enter the static tier at all.
+- **Coverage says nothing when there is nothing to measure against.** With a
+  `default_locale` the app configures but ships no file for, every locale
+  scored zero and all of them were named as untranslated.
+- **A mixin in a nested concerns directory is not a model.** The skip only saw
+  the top-level `concerns/` that Rails autoloads, so OpenProject's
+  `app/models/queries/operators/concerns` contributed four mixins to a model
+  count of 978 where the app has 974. A nested `concerns/` is an ordinary
+  namespace, though, so the directory name alone does not decide it: a file
+  there that declares a class is a model like any other.
+- **`docs/COMPATIBILITY.md` describes the static tier the gem actually has.**
+  It said 6 introspectors answer without a booted app and "the other 34 have
+  no static path", naming eight examples - all of which answer. The real
+  split is 23 files-only, 9 alternate-source and 8 runtime-only: 32 of 40.
+  A guard spec derives all three lists from `INTROSPECTOR_MAP`.
+
+- **A controller is named by the constant its source declares.** Zeitwerk
+  resolves a path through the app's own inflector, which the static tier
+  never loads, so camelizing the path invented `Activitypub::` for the 12
+  controllers Mastodon declares as `ActivityPub::` and `Oauth::` for the 4
+  it declares as `OAuth::` - names that appear nowhere in an app that
+  registers those acronyms, and a `NameError` for anyone who uses one. The
+  path stays the answer where the source does not carry the whole name
+  (`application_cable/channel.rb`) and where the declared name does not name
+  that file, since Prism recovers a syntax error into a partial tree.
+- **An interceptor is told from a mailer by its framework hook.**
+  `app/mailers` is also where ActionMailer interceptors live, and every `.rb`
+  under it counted: OpenProject's `Interceptors::DefaultHeaders` arrived as a
+  mailer with `delivering_email` - a hook the framework calls - listed as an
+  email an agent could send, 2 of its 11 entries. What an interceptor has and
+  a mailer does not is one of `delivering_email`, `previewing_email` or
+  `delivered_email`; requiring a class instead would have dropped GitLab's 20
+  `Emails::*` modules, which hold every notification it sends.
+- **Migration replay reads what a migration does, not what it undoes.** A
+  `def down` says how to reverse the change, so replaying it alongside `up`
+  cancelled the migration out. On a migrations-only app the ordinary
+  up-creates/down-drops pair erased two tables OpenProject really has (35
+  to 37), and the reverse pair would have invented one it dropped. The same
+  now holds for the block spellings, `reversible { |dir| dir.down { ... } }`
+  and `revert`, and for the `t.timestamps` inside them - those were found by
+  a separate walk over the whole file, so a down body's timestamps landed on
+  the last table created on the way up.
+- **i18n coverage groups the locales below its own rounding floor instead of
+  listing them.** A language-name lookup table under `config/locales`
+  contributes a top-level key per language, and Rails does load each as an
+  available locale. Scoring them produced a row each saying every key was
+  missing: on Discourse, 138 of 186 coverage rows described a translation
+  effort nobody had started. Those 138 are now summarised in one line, with a
+  shared key count stated once. The rows still exist - asking for one by name
+  answers with its numbers, so a translation genuinely started below the floor
+  is not written off as untranslated. The available list still matches a
+  booted Rails, and a locale's keys are read from its own file and any shared
+  file together, so one that lives outside the naming convention is scored.
+- **A recorded tool selection no longer switches off `.ai-context.json`.**
+  The install generator always records one, and every later `rails
+  ai:context` passed that list to the serializer. The machine artifact is
+  not an AI tool and no install menu offers it, so it silently stopped being
+  written on the one install path the docs describe - while the generator
+  went on adding it to `.gitignore`.
+- **`skip_tools` accepts the symbol spelling its neighbours use.** Every
+  other key in the generated initializer takes symbols, and `%i[]` here
+  skipped nothing at all: both readers compare against a tool name, which is
+  a String.
+
+- **A controller carries the file it was read from.** Reading the name from
+  the source fixed the name and broke every path derived from it:
+  `ActivityPub::CollectionsController`.underscore is `activity_pub/...` and
+  the file is under `activitypub/`, so `rails_get_context` answered "Could
+  not extract source code" for a file that exists and asked the routes for a
+  controller key Rails does not use. Both tiers emit `file:` - the booted one
+  asks Ruby where the class was defined - and the consumers read it through
+  `Payload`.
+- **The locale files are indexed once, not once per locale.** Asking every
+  file about every locale is O(locales x files): on Discourse, 187 over 108,
+  it took the i18n answer from 4.6 seconds to four and a half minutes. Each
+  entry also records the locales it serves, so asking for one by name finds
+  its files even when the filename spells the gem rather than the locale.
+
+- **Every consumer that turns a controller name back into a path reads the
+  file it was read from.** Carrying `file:` fixed six of them and left five
+  answering a confident negative, which is the answer an agent acts on
+  without checking. On Mastodon's 18 inflected controllers: `rails_test_info`
+  reported 16 specs that exist as missing, `rails_get_routes` reported 4
+  routes that exist as absent, `rails_get_view` 2 views, and
+  `rails_generate_test` wrote a spec whose body was `skip "no routes found"`
+  for a controller with a route. `rails_analyze_feature` listed them as
+  untested. `Payload.controller_route_key` is the one derivation now, and a
+  spec drives all five tools with an inflected name.
+- **The install path's files require their own stdlib.** `init` loads six
+  files before Rails and before the entry file, on purpose - so the entry
+  file's `require "set"` never runs for them. `legacy_cleanup`'s `[...].to_set`
+  raised `NoMethodError` on Ruby 3.1, where `Set` is not autoloaded, and 3.2+
+  hid it: only the CI matrix ever saw it.
+- **`rails_runtime_info` reports cache numbers, not the cache object.** The
+  MemoryStore branch passed `cache.inspect` straight through, so the answer
+  carried `#<ActiveSupport::Cache::MemoryStore entries=0, size=0, options={...}>`
+  - the shape this gem has shipped as a defect before. Entries and size are
+  now facts, and a store that answers `#stats` gets its hash rendered as pairs
+  rather than a Ruby literal.
+- **A model's table comes from its file, not from its name.** Naming a model by
+  the constant its source declares made `underscore` stop being the way back:
+  `OAuthClientConfig` underscores to `o_auth_client_config`, and the file is
+  `oauth_client_config.rb`. `rails_model_details` reported the table as
+  `o_auth_client_configs`, which no app has, so the columns section vanished
+  and the schema hint pointed at nothing - on Canvas that hit
+  `OAuthClientConfig`, `OAuthRequest`, `AuthenticationProvider::OAuth` and
+  `OAuth2`, on OpenProject `OAuthClient` and `OAuthClientToken`. The file's own
+  name already carries the inflection, because Zeitwerk resolved the constant
+  from it. `rails_generate_test`, `rails_get_callbacks`, `rails_test_info` and
+  the five `rails_validate` checks that key models by path read it too.
+- **An abstract base class is not a model in the static tier either.** A
+  booted Rails rejects `abstract_class?`, and a namespaced base class is one:
+  GitLab's `Ci::ApplicationRecord`, `PackageMetadata::ApplicationRecord` and
+  `SecApplicationRecord` were counted, so the same app answered 895 models
+  without a boot and 888 with one. OpenProject: 974 against 971.
+- **A model carries its file too, and is named by the constant its source
+  declares.** `rails_model_details` rebuilt `app/models/<underscored>.rb` from
+  the name in four places, so for a model in a pack or an engine the custom
+  validations, the source-defined methods, the method signatures and the class
+  structure all went quietly missing from an answer that otherwise looked
+  complete. The static tier also camelized the path into the name, so an app
+  registering an inflection got a constant it does not have - and one the
+  booted tier, which reads the real class, would never agree with.
+- **`rails_validate_semantics` checks the views under an inflected directory.**
+  A view directory names the route key, so camelizing `app/views/oauth/` back
+  gave a constant the app never declares and the undefined-ivar check stopped
+  running for that whole tree without saying so.
+- **A test-gap claim is not made from a scan that stopped early.**
+  `rails_analyze_feature` scans the first 500 files per glob; Discourse has
+  1,672 specs, so the scan never reached the ones covering the feature and
+  every controller in it was reported as having no test. The Tests section
+  disclosed the cap, the gaps section asserted through it.
+- **"Global before_actions" in the generated files means global.** The scan
+  matched `skip_before_action` too, and ignored `only:` / `except:` / `if:`.
+  Mastodon's `CLAUDE.md` listed five, of which three were false - including
+  `verify_authenticity_token`, which that controller skips.
+
+### Added
+
+- **`--no-boot` on `context`, `inspect`, `facts`, `preset`, `watch` and
+  `init`.** The static tier was reachable from `tool` and `serve` only.
+- **`--no-boot` reads a repo that has source but no `config/`.** An engine
+  keeps its dummy app under `spec/dummy`, so the guard against describing an
+  empty directory has to measure source, not boot files.
+
+### Changed
+
+- **The generated initializer has one indent from top to bottom.** The AI
+  Tools section was written at the configure body's indent and every section
+  after it flush, so the file an app commits changed indent two lines in and
+  stayed there.
+
+## [5.23.0] - 2026-08-16
+
+### Fixed
+
+- **`AstCache.parse_string` caches, as its name always said.** Keyed by
+  content digest, sharing the store and its eviction; oversize sources
+  bypass instead of raising. A controller was parsed up to ten times per
+  static run because every extractor received the text and re-parsed it.
+- **`rails_validate` says which checks it skipped.** When the AST parse
+  fails, the three rules with no regex twin used to vanish silently and a
+  partially-checked file read as clean; the response now names them. The
+  tool also gains its first spec file.
+- **A downstream app exception is the app's again.** The middleware's
+  rescue used to convert any error from the app behind it - non-MCP
+  requests included - into an MCP error frame. `McpEdge.rack_call` now owns
+  the whole Rack-shaped request (path match, session scope, dispatch,
+  containment) for the middleware and the standalone server, and the
+  pass-through branch runs outside the rescue.
+
+### Changed
+
+- **The cache fingerprint watches what the resolvers read.** Packs,
+  engines, `extra_app_paths`, every concern home, the `Gemfile`,
+  `config/locales` and `config/environments` now feed the fingerprint, so
+  an edit there cannot serve a stale answer that looks fresh.
+- **One change-detection loop.** `ChangeWatch` owns the watch list, the
+  Listen wiring, the fingerprint gate and the code reload; `Watcher` and
+  `LiveReload` keep only their reactions (regenerate files; refresh caches
+  and notify clients) and their own missing-`listen` policy.
+- **The initializer guard and the `tool_mode` line each have one home.**
+  `Install::InitializerFile` holds the guard patterns the generator writes
+  and the doctor diagnoses; `SelectionRecord.write_tool_mode` replaces the
+  rake task's hand-rolled three-branch rewriter, and only rewrites an
+  uncommented line, so the generated commented-out default stays a comment.
+- **Split-rule targets derive from the `Install::AiTool` table.** The
+  rules serializers read `rules_dir` (and the AGENTS.md pair) from the
+  table doctor and cleanup already read, so a moved path changes every
+  surface at once.
+- **The stack helper writes through `SafeFile.atomic_write`** instead of a
+  private copy of it, and its app-tree scans take a root, so they are
+  covered by specs for the first time.
+- **Every serializer is proven against a context real introspectors
+  produced** (`IntrospectedFixture`), so no serializer can read a shape
+  production does not make - the class of defect that kept the engines and
+  turbo sections dead while hand-built fixtures stayed green.
+
+## [5.22.0] - 2026-08-16
+
+### Fixed
+
+- **A class nested inside a controller, mailer, model or helper file no
+  longer contributes its methods to the host's interface.** "Which public
+  methods are this class's own" had five transcriptions with five filter
+  sets; they now share `ActionResolver`, which filters listener output by the
+  owner field the listener always emitted, walks app-owned ancestors, and
+  falls back to reflection with the #136 base subtraction. Mailers had kept
+  the pre-#136 reflection answer, so a public helper on a non-abstract
+  `ApplicationMailer` arrived as a deliverable action; they subtract now, and
+  static mailer actions apply the same underscore rule as controllers. (#149)
+
+- **Every generated context file states each fact through one renderer.**
+  `SectionFacts` owns the models line, the database line, the associations
+  list (eight copies, three of them in tools) and the warnings section -
+  which now renders in AGENTS.md and .github/copilot-instructions.md too, so
+  a half-failed run cannot look clean in two of four files. AGENTS.md stops
+  shadowing the shared architecture and footer renderers with poorer copies,
+  and its controller list goes through the shared renderer with named
+  actions as a depth choice rather than a fork. `Payload` is the reading
+  side of the introspection hash: list readers whose key pairs a spec pins
+  against the producing introspector's real output, so the next renamed key
+  fails a test instead of silently emptying a section. (#151)
+- **API-only apps are told "does not apply", not "not found".**
+  `rails_get_helper_methods` and `rails_get_frontend_stack` now consult the
+  api-only note like the other eleven call sites. The two hand-rolled
+  paginations (`rails_get_schema`, `rails_get_stimulus`) go through the
+  shared `paginate`, one offset/limit behavior across all fourteen paginated
+  surfaces. (#152)
+- **The interactive install is one program with three voices.** The
+  generator, the standalone binary and the rake task each held a full copy
+  of the prompts, the removed-tool cleanup, the gitignore append and the
+  MCP-config write - about 470 lines that had already drifted: two labels
+  for one mode, a menu with file lists in two entries and bare names in the
+  third, a byte-identical gitignore block three times. `Install::Program`
+  now owns the steps and the wording; each entry supplies its say/ask
+  surface and keeps only its closing instructions. The rake menu shows each
+  tool's files, and every entry uses one mode label.
+- **Configuration loads the same way on every entry point.** The engine now
+  runs `auto_load!` at boot, so `.rails-ai-context.yml` works on the rake
+  tasks, the middleware and the engine controller the way the docs always
+  said - initializer first, the loader steps aside when a configure block
+  ran. `Configuration#ai_tools` answers from `SelectionRecord` when nothing
+  set it, so `rails ai:context` stops re-asking a question the record
+  already answers, and the recorded `tool_mode` reaches in-app surfaces
+  through the record's new reader. A bad YAML value now warns and keeps the
+  default the way bad syntax always did, instead of dying raw out of the
+  CLI. (#147, #148)
+- **The three static schema sources follow one set of conventions, and every
+  schema question can be asked of any of them.** `SchemaReader.for(root)`
+  chooses schema.rb, structure.sql or migration replay behind one
+  question-level seam, so introspectors asking "does this table carry this
+  column" now get answers on structure.sql and migrations-only apps instead
+  of nothing. The migration replay is repaired: a replayed `create_table`
+  seeds its implicit `id`, `change_column_null` applies in both directions
+  (the listener now captures the positional boolean), and `t.references` is
+  typed per adapter instead of hardcoded bigint. The conventions live in
+  `SchemaConventions`, shared by all three sources the way #140's
+  foreign-key fix pioneered; the SQL parser and the replay engine moved to
+  `StructureSqlReader` and `MigrationReplay`, and the schema introspector
+  halves in size, keeping only presentation. (#150)
+- **Every surface answers "which concerns count" and "how many routes" the
+  same way.** Five renderers carried five concern filter sets:
+  `rails_get_callbacks` hid every namespaced concern unless it started with
+  "App", `rails_analyze_feature` hid all of them, and two ignored the
+  `excluded_concerns` config. `ConcernMembership` now decides the payload
+  sense once, at the introspector seam, for both tiers - the static
+  controller answer goes through `MixinsListener`, so `prepend` counts and a
+  singleton-class `include` does not, exactly as booted. Route populations
+  (app vs framework split, PUT/PATCH dedup) moved beside the coverage suffix
+  into `RouteCoverage`, replacing four hand-kept computations, one of them a
+  wholesale copy. CLAUDE.md's per-model concern list now names the concerns
+  the app defines, namespaced ones included.
+- **Mounted engines render again in `rails_onboard` and the context files.**
+  `EngineIntrospector` emits `:mounted_engines`; the tool read `:engines` then
+  `:mounted`, and the stack line read `:mounted`, so both fell back to "none"
+  forever. Both now read the introspector's keys and the element's real
+  `engine:`/`path:` shape, and the spec fixtures use that shape instead of one
+  production never produced. (#144)
+- **The Hotwire stack line and `rails_onboard`'s Real-Time and Frontend
+  sections read turbo keys that exist.** `turbo[:frames]`, `[:streams]` and
+  `[:broadcasts]` were never emitted (`:turbo_frames`, `:turbo_streams` and
+  `:model_broadcasts` are), so the line was dead everywhere and Real-Time
+  always fell through to its view-scan fallback. (#145)
+- **`rails_get_context` no longer offers a Related Services section it could
+  never fill.** The `:services` key it read has no introspector behind it; the
+  dead branch is gone. (#146)
+- **`rails ai:context` stops re-prompting a YAML-configured app on every
+  run.** The rake path now loads `.rails-ai-context.yml` the way the
+  standalone binary always did; the initializer still wins when its configure
+  block ran. (#147)
+- **The standalone binary's `--format` help names opencode and codex.** A
+  guard spec pins the help text to `Install::AiTool`, which the Thor class
+  body cannot ask at definition time. (#153)
+- **`rails ai:serve` and `rails ai:serve_http` boot under the same timeout
+  and rescue as the binary.** A hanging initializer used to hang the task
+  forever where `rails-ai-context serve` gives up at 60s; both tasks now boot
+  through `BootManager.guard`, and `RAILS_AI_CONTEXT_BOOT_TIMEOUT` is parsed
+  in one place. (#154)
+- **doctor's tool list and `rails_search_code`'s exclusion list derive from
+  `Install::AiTool`.** Both were hand-typed restatements sitting below the
+  ownership spec's detection floor; the search exclusions now also cover the
+  generated `app/models/AGENTS.md` pair they previously missed. (#155)
+- **An e2e example asserts `call` and `static_call` answer the same keys.**
+  The declaration contract was already enforced (ADR-0002); the shape contract
+  was not, so a key added to the booted tier could silently vanish from the
+  static one. (#156)
+
 ## [5.21.3] - 2026-08-12
 
 ### Fixed

data/CONTEXT.md

@@ -28,14 +28,48 @@ Two senses, one per module, and neither is bare "path" in a name.
 
 **How a path is written down** - `PortablePath` rewrites one so it means the same thing on another machine, because what it touches ends up in `.ai-context.json` and the app commits that file. App paths go app-relative, gem paths keep the gem and version and drop the install prefix. "Relativize" always means this.
 
+## Declared constant
+
+What a source file calls its own class, as opposed to the **path name** - the constant its path camelizes to. The two differ wherever the app registers an inflection, because Zeitwerk resolves a path through the app's own inflector and the static tier has never loaded it: `app/controllers/activitypub/` is `ActivityPub` in Mastodon, and `Oauth` is a constant nothing defines. `DeclaredConstant` reads the class the source declares, and since an inflection only ever changes case, the declaration that names a file is the one equal to the path name ignoring case. Anything else - a second class in the file, a nested error class, a tree Prism recovered from a syntax error - is not this file's class, and there the path name stays the answer: it is the only thing carrying the namespace when the source does not.
+
+Distinct from the **Static tier** sense of "declared": that one is about declaring a tier's capability up front rather than detecting it at runtime. This one is about a constant's spelling.
+
+The other half of the same problem is the reverse trip. Once a name is the declared one, no consumer can rebuild the path from it - and a pack or an in-repo engine breaks that derivation too, inflection or not. So controllers and models carry `file:` from whichever tier found them, and consumers read it through `Payload` (`controller_file`, `controller_route_key`, `controller_for_route_key`, `model_file`). The rule: a tool that needs a path for a name reads it, never underscores it.
+
 ## Static tier
 
 The mode where the app did not boot, or `--no-boot` was passed. What an introspector answers here is what it declared, never what a runtime check happened to detect. Every introspector in `INTROSPECTOR_MAP` extends `StaticTier` and names one of three kinds:
 
-**files-only** - `call` runs unchanged against the static app handle, because it only ever read files. Most of the map.
+**files-only** - `call` runs unchanged against the static app handle (`StaticApp`), because it only ever read files. Most of the map.
 
 **alternate-source** - `static_call` answers from a different source than `call` does: `db/schema.rb` instead of the connection, `config/routes.rb` instead of the route set.
 
 **runtime-only** - needs `app.config`, `app.routes` or a live database, and refuses honestly.
 
 An undeclared introspector fails the suite, and every files-only declaration is proven against `spec/fixtures/static_app` with nothing booted. Declaring files-only while defining `static_call` (or the reverse) is also a spec failure.
+
+## Concern
+
+Three senses inside the gem, and the payload one is wider than either everyday Rails reading.
+
+**Concern (as payload)** - a module in a class's ancestor chain, minus framework noise. Not only `ActiveSupport::Concern`, and not only files under a concerns directory: anything reached by `include` or `prepend` counts, which is why `extend` and a singleton-class `include` do not. This is what `:concerns` holds in model and controller data and what a "Concerns" section renders. The booted tier reads `ancestors`, so it also sees what the superclass and other concerns pulled in; the static tier sees the class's own file alone. `ConcernMembership` decides membership for both tiers; renderers trust the payload rather than re-filtering.
+
+**Concerns directory** - `app/*/concerns` as a place, glob-derived the way Rails autoloads it, never a hardcoded list. `ConcernPaths` is the one answer to "where does this app keep its concerns" for every surface that lists or counts them.
+
+**Mixin** - the static detection feeding the payload: any `include`, `prepend` or `extend` with a constant argument, as `MixinsListener` reports it. Named mixin because it captures more than concerns; its `ancestor` flag marks the subset that becomes one.
+
+## Action
+
+The callable interface of a class as this gem reports it: the class's own public instance methods - a class nested in the same file is a separate owner, not part of the interface - minus framework-shaped `_` names, read source-first, with reflection minus the app-owned base as the honest fallback. `ActionResolver` is the one answer; controller and mailer are configurations of it, and a channel's "stream methods" are a narrower selection of the same reading.
+
+## Payload
+
+The introspection context hash, in the sense consumers read it. `Payload` is the reading side: a section guard and pinned list readers whose key pairs a spec checks against the producing introspector's own output, so a renamed key fails a test instead of silently emptying a section everywhere. Facts rendered from it live once (`SectionFacts`); membership judgments are applied at the introspector seam, and readers trust the payload rather than re-filtering it.
+
+## Standalone
+
+Two senses on different axes. Qualify it; the bare word does not say which.
+
+**Standalone install** - how the gem got installed: `gem install rails-ai-context`, driven through its own binary, never in the host app's Gemfile, so the `rails ai:*` rake tasks do not exist. `InstallMode.standalone?` is the decider, and the `standalone:` flag on `McpConfigGenerator` means this - it picks whether the written MCP command is the bare binary or a bundled invocation. `docs/STANDALONE.md` documents this sense only.
+
+**Standalone server** - how MCP is served: the entry point that is its own process, `rails ai:serve_http` starting `Server` with `transport: :http`, serving MCP and nothing else. The middleware and the engine controller answer the same requests from inside the app's web server; the standalone server does not need one running. It says nothing about the install - an in-Gemfile app starts it from a rake task. ADR-0003 and `McpEdge` use this sense.

data/docs/CLI.md

@@ -37,6 +37,7 @@ rails-ai-context serve --transport http --port 6029   # HTTP transport
 |:-------|:--------|:------------|
 | `--transport` | `stdio` | `stdio` or `http` |
 | `--port` | `6029` | HTTP listen port |
+| `--no-boot` | off | Skip booting the app; answer from source alone |
 
 ### `tool`
 
@@ -58,6 +59,28 @@ rails-ai-context tool model_details --model User
 |:-------|:------------|
 | `--list` | List all available tools |
 | `--json` | Output as JSON |
+| `--no-boot` | Skip booting the app; answer from source alone |
+
+### The static tier and `--no-boot`
+
+Every command that reads the app takes `--no-boot`: `tool`, `serve`, `context`,
+`inspect`, `facts`, `preset`, `watch` and `init`. It skips the boot and answers
+from source alone, which is what you want on a repo you have just cloned, on an
+app whose boot is broken, and in CI where booting costs more than the answer.
+
+The same tier is entered automatically when a boot fails, so you get an answer
+either way. Answers that need a running app are marked `[UNAVAILABLE: ...]`
+rather than guessed, and everything else is tagged `[STATIC]` instead of
+`[VERIFIED]`. `docs/COMPATIBILITY.md` lists which of the 40 introspectors answer
+in which tier.
+
+`doctor` is the exception: diagnosing the boot is its job, so it refuses
+`--no-boot` and still exits 1 when the app cannot start.
+
+```bash
+rails-ai-context tool models --no-boot        # no boot, no database, no Gemfile
+rails-ai-context context --no-boot            # writes CLAUDE.md from source
+```
 
 ### Tool name resolution
 

data/docs/COMPATIBILITY.md

@@ -70,23 +70,37 @@ Two tiers, both reachable over the CLI and MCP (stdio and HTTP):
 (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:
+**STATIC** - the app didn't boot, or `--no-boot` was passed. 32 of the 40
+introspectors answer here; each declares which of three kinds it is
+(ADR-0002), so what a tier can say is a declaration rather than a guess.
+
+**files-only** (23) run unchanged against the static app handle, because they
+only ever read files: `gems`, `views`, `view_templates`, `turbo`, `stimulus`,
+`active_storage`, `action_text`, `auth`, `tests`, `rake_tasks`, `assets`,
+`devops`, `action_mailbox`, `migrations`, `seeds`, `middleware`, `env_config`,
+`multi_database`, `components`, `performance`, `frontend_frameworks`,
+`credentials` and `env`.
+
+**alternate-source** (9) have a `static_call` that reads a different source
+from the booted path:
 
 | 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 |
+| `schema` | `db/schema.rb` / `db/structure.sql` / migration replay |
 | `models` | `app/models/**/*.rb` (plus packs/engines/extra paths) parsed, not constantized |
+| `routes` | `config/routes.rb` parsed with a dedicated Prism listener |
 | `controllers` | `app/controllers/**/*.rb` (plus packs/engines/extra paths) parsed, not constantized |
-| `env_config` | `config/environments/*.rb` read from disk - file-based, so the static tier serves the same data as a booted app |
-
-The other 34 introspectors (views, jobs, gems, turbo, i18n, active_storage,
-auth, api, and the rest) have no static path and report `{ unavailable: reason
-}` 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.
+| `jobs` | `app/jobs`, `app/mailers` and `app/channels` parsed for classes and their public methods |
+| `i18n` | every top-level key across `config/locales`, and the default locale read from `config/` |
+| `api` | serializers, API controllers and route constraints read from source |
+| `engines` | `config/routes.rb` mounts, plus the Gemfile |
+| `active_support` | concern and core-extension use read from source |
+
+**runtime-only** (8) report `{ unavailable: reason }` here, and only these:
+`conventions`, `database_stats`, `config`, `initializers`, `autoload`,
+`connection_pool`, `security` and `observability`. The fallback message comes
+from `Introspector#run_introspector` (`lib/rails_ai_context/introspector.rb`)
+and is the same whatever put the gem in the static tier.
 
 `doctor` never enters the static tier - its job is diagnosing why boot failed,
 so it always requires a bootable app.

data/docs/CONFIGURATION.md

@@ -113,7 +113,7 @@ preset: full
 |:-------|:-----|:--------|:------------|
 | `max_search_results` | Integer | `200` | Maximum search results |
 | `max_validate_files` | Integer | `50` | Maximum files for validation |
-| `search_extensions` | Array | `["rb", "js", "erb", "yml", "yaml", "json", "ts", "tsx", "vue", "svelte", "haml", "slim"]` | File extensions to search |
+| `search_extensions` | Array | `["rb", "js", "erb", "yml", "yaml", "json", "ts", "tsx", "vue", "svelte", "haml", "slim"]` | File extensions the Ruby fallback searches (ripgrep, when installed, searches every file) |
 | `concern_paths` | Array | `nil` (discovers `app/*/concerns`) | Paths to scan for concerns. Setting it replaces discovery, so it can narrow as well as widen |
 | `frontend_paths` | Array | `nil` (auto-detect) | Override frontend file paths |
 | `extra_app_paths` | Array | `[]` | Extra directories under the app root to treat as application code |

data/docs/GUIDE.md

@@ -1353,7 +1353,7 @@ end
 | `excluded_concerns` | Array | framework regex patterns | Regex patterns for concerns to hide from model output |
 | `excluded_filters` | Array | `verify_authenticity_token`, etc. | Framework filter names hidden from controller output |
 | `excluded_middleware` | Array | standard Rails middleware | Default middleware hidden from config output |
-| `search_extensions` | Array | `rb js erb yml yaml json ts tsx vue svelte haml slim` | File extensions for Ruby fallback search |
+| `search_extensions` | Array | `rb js erb yml yaml json ts tsx vue svelte haml slim` | File extensions the Ruby fallback searches (ripgrep, when installed, searches every file) |
 | `concern_paths` | Array | `nil` (discovers `app/*/concerns`) | Where to look for concern source files. Setting it replaces discovery |
 
 ### Root file generation