rails-ai-context 5.32.2 → 5.33.0

data/docs/TOOLS.md

@@ -43,6 +43,8 @@ Tool name resolution is flexible - all of these work:
 | `get_schema` | `rails_get_schema` |
 | `rails_get_schema` | `rails_get_schema` |
 
+Over MCP the name is exact. A name the server has no tool for fails with a JSON-RPC `-32602` error, `Tool not found: <name>`, that names the nearest tools, or every tool when none is near; `data.available` lists them all.
+
 Most lookup tools accept a **`detail`** parameter: `summary` (compact), `standard` (default), or `full` (everything). Start with summary, drill down as needed. Composite tools (`rails_get_context`, `rails_analyze_feature`) do not accept `detail`.
 
 <p align="right"><a href="#table-of-contents">↑ back to top</a></p>
@@ -74,9 +76,9 @@ Search your codebase with regex, ripgrep acceleration, and sensitive file blocki
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
-| `pattern` | string | *required* | Regex pattern to search for |
+| `pattern` | string | *required* | Regex pattern to search for. With `definition` or `class`, a plain method or constant name matches literally (`valid?`), anything else as a regex (`generate_.*`) |
 | `path` | string | - | Subdirectory or file to search (relative to Rails root); a file is searched whatever its type or ignore files say, as ripgrep does, unless it is sensitive |
-| `match_type` | enum | `any` | `any`, `definition`, `class`, `call`, `trace` |
+| `match_type` | enum | `any` | `any`, `definition` (def lines whose method name contains the pattern), `class` (class/module lines whose name contains it), `call`, `trace` |
 | `file_type` | string | - | Filter by extension (`rb`, `erb`, `js`, etc.) |
 | `exact_match` | boolean | `false` | Literal, whole-word match. `def reblog?` does not match `def reblog` |
 | `exclude_tests` | boolean | `false` | Skip test/spec directories |
@@ -85,17 +87,19 @@ Search your codebase with regex, ripgrep acceleration, and sensitive file blocki
 | `offset` | integer | `0` | Skip this many emitted lines |
 | `limit` | integer | auto | Max lines to return; the default is sized in matches, and a limit too small for one match and its context still returns that match |
 
-The header counts matches, not emitted lines, so below the cap it does not move with `context_lines`. When the search hits `max_search_results` (a cap on emitted lines) the header says `first N lines scanned` and marks the count `N+`: it is then the matches among the lines that were scanned, a floor rather than the total, so it falls as `context_lines` grows. `offset` and `limit` count lines, so a search with context returns more lines than matches. A limit smaller than one match's context block would hold only context, so the page starts at the next match instead and says so.
+The header counts matches, not emitted lines, so below the cap it does not move with `context_lines`. The cap always holds the first match and the context before it, so a `max_search_results` below `context_lines + 1` is raised to that rather than answering "No results found". When the search hits the cap (a cap on emitted lines) the header says `first N lines scanned` and marks the count `N+`: it is then the matches among the lines that were scanned, a floor rather than the total, so it falls as `context_lines` grows. `offset` and `limit` count lines, so a search with context returns more lines than matches. A limit smaller than one match's context block would hold only context, so the page starts at the next match instead and says so.
+
+> **Trace mode** returns definition + source code + every caller grouped by file and labelled by type + tests - replaces 4-5 sequential file reads. A model's `scope :name` is the definition of a method of that name when no `def` defines one.
 
-> **Trace mode** returns definition + source code + every caller grouped by file and labelled by type + tests - replaces 4-5 sequential file reads.
+ripgrep follows no symlink while it walks, so a directory linked in from the app's git repository (a monorepo package linked into `packs/`) is handed to it as a path of its own, and its rows are named the way the app spells them (`packs/billing/app/models/invoice.rb`). `path` may name such a directory or a file in it. A link out of the repository, or out of the app when it is in none, is neither searched nor accepted as `path`.
 
-Without ripgrep on the PATH, the Ruby fallback returns the rows ripgrep would, context lines and the line cap included, from the files ripgrep would search: no hidden files, no symlinks followed, no binary files (a NUL byte in the first 64 KiB), and ignore files read with ripgrep's precedence, where the file type decides before depth: any `.rgignore`, then any `.ignore`, then any `.gitignore`, then `.git/info/exclude`, then the global excludes file, the deepest file first within a type. `.ignore` and `.rgignore` apply everywhere, including the directories above the app; the git files apply only inside a repository and only as far up as the nearest `.git` (a file for a worktree or submodule), whose `info/exclude` is the only one read. Patterns match case-sensitively.
+Without ripgrep on the PATH, the Ruby fallback returns the rows ripgrep would, context lines and the line cap included, from the files ripgrep would search: no hidden files, no other symlinks followed, no binary files (a NUL byte in the first 64 KiB), and ignore files read with ripgrep's precedence, where the file type decides before depth: any `.rgignore`, then any `.ignore`, then any `.gitignore`, then `.git/info/exclude`, then the global excludes file, the deepest file first within a type. `.ignore` and `.rgignore` apply everywhere, including the directories above the app; the git files apply only inside a repository and only as far up as the nearest `.git` (a file for a worktree or submodule), whose `info/exclude` is the only one read. Patterns match case-sensitively.
 
-Redaction treats a value under a secret-named key as a secret unless it is clearly something else: shorter than eight characters (four under a password-type key: `password`, `passwd`, `pass`, `pin`, `passphrase`), containing whitespace (a message; not under `passphrase`), a URL, an email address or a hostname (not under a password-type key), a URL query (`?mode=safe`) or a path (two slashes, no `+` or `=`), a placeholder (`<token>`, `${VAR}`, `%{var}`, a `{name}` slot, `xxxx`, `your-...`, `put-your-key-here`), a version (`2.4.1`, `v2`) or a date, an HTTP header name (`X-Api-Key`; not under a password-type key), an env name (capitals joined by `_`, led by `_` or `HTTP_` or naming a secret word, like `_DISCOURSE_API`), a name spelled from a secret word (`user_api_key`; not under a password-type key, where `admin_password` is the password), the key's own name (an enum's `password: 'password'`), or not ASCII. Keys ending `_url`, `_error`, `_use` and the like describe a secret rather than hold one. A call or block whose first argument names a secret holds its value too (`ENV.fetch("SECRET_KEY_BASE", "...")`, `let(:api_key) { "..." }`, `option :client_secret, default: "..."`, a `credentials.fetch` default); a ternary's `? "a" : "b"` is two values, not a key and its value. Under a name that ends in `_KEY`, `Key` or `key` without a secret word (`ALGOLIA_ADMIN_KEY`, `apiKey`), a value is filtered only when it looks like a credential: a run of 16+ characters mixing letters and digits, or a known token format; a cache or i18n key (`views/posts/1`, `users.index.title`), a storage key (`wp-content/uploads/...`), a word, a path or a header name is kept. Log lines use the same rule. An unquoted `NAME=value` with a secret-named name, in any file (shell, Dockerfile `ENV`, compose, env, code), has its value filtered unless it is `$VAR`, `${...}`, `#{...}` or ERB; the value ends at the first quote, bracket, `&`, `,`, `;` or space, so in a URL query (`?token=...&page=2`) only the value goes. A `:name=` setter symbol and a `(?<=name=` lookbehind are not assignments. In an example file (`*.example`, `*.sample`, `*.template`) a value under a secret-named key is kept only when it is plainly a placeholder: a placeholder shape above, or up to 20 characters of words with no digits (`changeme`, `your_password_here`). Locale files are filtered only for credential formats.
+Redaction treats a value under a secret-named key as a secret unless it is clearly something else: shorter than eight characters (four under a password-type key: `password`, `passwd`, `pass`, `pin`, `passphrase`, Redis's `requirepass` and `masterauth`, the `MYSQL_PWD` and `REDISCLI_AUTH` the mysql and redis-cli clients read, and a long password word that ends a name with another joined on before it, as Postgres's `PGPASSWORD` and a camel-cased `userPassword` have), containing whitespace (a message; not under `passphrase`), a URL, an email address or a hostname (not under a password-type key), a URL query (`?mode=safe`) or a path (two slashes, no `+` or `=`), a placeholder (`<token>`, `${VAR}`, `%{var}`, a `{name}` slot, `xxxx`, `your-...`, `put-your-key-here`), a version (`2.4.1`, `v2`) or a date, an HTTP header name (`X-Api-Key`; not under a password-type key), an env name (capitals joined by `_`, led by `_` or `HTTP_` or naming a secret word, like `_DISCOURSE_API`), a name spelled from a secret word (`user_api_key`; not under a password-type key, where `admin_password` is the password), the key's own name in any case (an enum's `password: 'password'`, `currentPassword: "current_password"`), a switch's value (`true`, `false`, `null`), or not ASCII. Keys ending `_url`, `_error`, `_use`, `_file`, `_dir`, `_id` and the like (in camel case too: `tokenType`) describe a secret rather than hold one, and so does a Stimulus target, action, controller, outlet or class (`password_visibility_target`). A quoted name joined by dashes, a header or an attribute, reads with its dashes as underscores, so `"X-Api-Key" => "..."` and `req["x-auth-token"] = "..."` hold an API key and a token, while `"Content-Type"` names no secret. A camel-cased name with `Secret` or `Token` among its words (`accessToken`, `clientSecret`, `jwtSecretKey`) is a secret's name, as JSON and JavaScript spell `access_token`, in source and in a log line. A call or block whose first argument names a secret holds its value too (`ENV.fetch("SECRET_KEY_BASE", "...")`, `let(:api_key) { "..." }`, `option :client_secret, default: "..."`, a `credentials.fetch` default); a ternary's `? "a" : "b"` is two values, not a key and its value. Under a name that ends in `_KEY`, `Key` or `key` without a secret word (`ALGOLIA_ADMIN_KEY`, `apiKey`), a value is filtered only when it looks like a credential: a run of 16+ characters mixing letters and digits, or a known token format; a cache or i18n key (`views/posts/1`, `users.index.title`), a storage key (`wp-content/uploads/...`), a word, a path or a header name is kept. Log lines use the same rule. An unquoted `NAME=value` with a secret-named name, in any file (shell, Dockerfile `ENV`, compose, env, code), a flag (`--password=...`, `--requirepass=...`) included, has its value filtered unless it is `$VAR`, `${...}`, `#{...}` or ERB; the value ends at the first quote, bracket, `&`, `,`, `;` or space, so in a URL query (`?token=...&page=2`) only the value goes. A secret-named flag's value given as the next word (`redis-server --requirepass ...`, `--token ...`) is filtered, bare or quoted, when it has a digit and would be filtered under that name, so a word (`the --password option`), a metavariable (`--token TOKEN`), a variable, ERB, another flag, a `--no-...` switch, a path (`~/.ssh/id_ed25519`, `./keys/deploy.pem`, `keys/deploy.pem`) or a `name=value` list (BuildKit's `--secret id=...,env=...`) stays. A `:name=` setter symbol, a `(?<=name=` lookbehind and a regex's wildcard (`/--password=.+/`) are not assignments. The credential after an auth scheme (`Bearer`, `Basic`, `Token`), under an `Authorization` key, in a curl line or a cassette, is filtered in any file when it is shaped like one: 16 or more letters and digits, both, read past a UUID's dashes and base64's `+`, `/` and `=`; the scheme stays, and `Bearer #{token}`, `Bearer YOUR_TOKEN` and `Basic realm=...` hold no credential. A log line's `Authorization` header goes whole in every spelling: `Authorization: Basic ...`, a quoted value, a hash or JSON key, `HTTP_AUTHORIZATION`. In an example file (`*.example`, `*.sample`, `*.template`) a value under a secret-named key is kept only when it is plainly a placeholder: a placeholder shape above, or up to 20 characters of words with no digits (`changeme`, `your_password_here`). Locale files are filtered only for credential formats. In a YAML or JSON file read whole, a mapping a secret's name names holds that secret in its `value`: Heroku's `app.json` (`"STRIPE_SECRET_KEY": { "value": "..." }`, on one line or several), a YAML `api_token:` over `value: ...`, and a `render.yaml` or Kubernetes entry named by a sibling (`- key: CLIENT_SECRET`, `- name: API_TOKEN`) over its `value:`; a boolean, and the next entry's value, stay. A YAML key written as a Ruby symbol (`:password:` in `config/sidekiq.yml`) reads as its name.
 
 ### `rails_get_edit_context`
 
-Method-aware code extraction with surrounding class context. Every line returned passes through redaction, so in a file no pattern names a string literal under a secret-named key (8+ characters, unless it is clearly not a credential: a message, URL, path, placeholder, version, date, header, env or parameter name, or a translation) or in a known credential format (vendor tokens, JWTs, a PEM or PGP private key) reads as `[FILTERED]`; code, ENV lookups, ERB and placeholders are never rewritten, so the text stays usable as the text to replace.
+Method-aware code extraction with surrounding class context. Every line returned passes through redaction, so in a file no pattern names a string literal under a secret-named key (8+ characters, unless it is clearly not a credential: a message, URL, path, placeholder, version, date, header, env or parameter name, or a translation) or in a known credential format (vendor tokens, JWTs, a PEM or PGP private key) reads as `[FILTERED]`; code, ENV lookups, ERB and placeholders are never rewritten, so the text stays usable as the text to replace. `near` is looked for in the lines as they are returned, so text only a filtered value holds is not found, and the context line names the enclosing class and method from those lines too.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -111,7 +115,7 @@ Method-aware code extraction with surrounding class context. Every line returned
 
 ### `rails_analyze_feature`
 
-Full-stack feature analysis: models + controllers + routes + services + admin resources + jobs + views + tests in one call.
+Full-stack feature analysis: models + controllers + routes + services (with the files that call them) + admin resources + jobs and Sidekiq workers + views + tests in one call.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -131,7 +135,10 @@ Composite context: schema + model + controller + routes + views for a resource.
 
 ### `rails_onboard`
 
-Narrative app walkthrough for getting up to speed. It ends with the app's custom
+Narrative app walkthrough for getting up to speed. The stack line counts the
+tables of every database the app's own schema dumps declare, as
+`rails_get_schema` reads them; the databases Rails 8 gives Solid Queue, Solid
+Cache and Solid Cable get one line, without their tables. It ends with the app's custom
 rake tasks (Rakefile, `lib/tasks`, `rakelib`), each with its arguments,
 description and file: the first 15 at `standard`, every one at `full`.
 Then the app's own generators under `lib/generators` (the `bin/rails generate`
@@ -197,7 +204,13 @@ a `before_` or `around_` callback with `prepend: true` first. `after_commit`
 and `after_rollback` are last declared first unless the app turns on
 `run_after_transaction_callbacks_in_order_defined` (`load_defaults 7.1`). A
 method declared again for one type shows once, with the later declaration's
-conditions, as Rails keeps it. The order is read from source in both tiers,
+conditions, as Rails keeps it. A block or a lambda is listed as
+`[inline_block]`, and `detail:"full"` prints its declaration. turbo-rails'
+`broadcasts`, `broadcasts_to`, `broadcasts_refreshes` and
+`broadcasts_refreshes_to` are listed as the commit callbacks they declare
+(`broadcasts_refreshes (turbo-rails)` under `after_create_commit`,
+`after_update_commit` and `after_destroy_commit`), and `detail:"full"` names
+the method each one runs. The order is read from source in both tiers,
 and dynamic dispatch is not evaluated: a callback registered through
 `send(:before_save, ...)`, through a method called with `send` or defined with
 `define_singleton_method`, or through a module included in `class << self` is
@@ -218,6 +231,13 @@ that nests its own validator class stays a concern. Every concern is named by
 the constant its file declares, so an app inflection (`sdg/tag_list.rb`
 declaring `SDG::TagList`) is answered under the name the app has.
 
+The private methods are listed under their own heading, since an includer
+gets them too, and the listing counts them apart from the public ones. The
+macros an `included` block declares are listed, `helper_method` among them. An
+`include` under a condition (`include Pagy::Backend if defined?(Pagy::Backend)`)
+carries the condition; on a booted app it also says when the module is not
+defined, so was never mixed in.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `name` | string | - | Concern name (e.g., `Trackable`, `Admin::ExportControllerConcern`). Omit to list all concerns |
@@ -234,10 +254,12 @@ declaring `SDG::TagList`) is answered under the name the app has.
 
 Controller actions with inherited filters, render map, strong params. Includes schema hints for referenced models.
 
+Rails counts every public method that a concern or a parent controller gives among a controller's actions. A `page_info` in a concern that `ApplicationController` includes is an action of each controller. An app keeps the helpers its controllers share in such places, so the action lists take one of these methods only where a route names it for that controller, booted or not. An `action` lookup also finds one that no route names, under the rules the lists apply: no callback, no name that starts with `_` or ends in `?` or `!`, and no required argument. The answer reads the method from the file that defines it. It names the parent controller under **Inherited** when the method comes from one, and says under **Not listed** why the lists leave the method out. A private `def` of the same name lower down hides the method, as it does from Rails.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `controller` | string | - | Controller name (e.g., `UsersController`) |
-| `action` | string | - | Specific action; requires `controller` |
+| `action` | string | - | Specific action; requires `controller`. Also finds one a concern or a parent controller gives that no route names (see above) |
 | `detail` | enum | `standard` | `summary`, `standard`, `full` |
 | `limit` | integer | `50` | Max controllers when listing |
 | `offset` | integer | `0` | Skip this many controllers |
@@ -253,13 +275,22 @@ spells one out. A mounted Grape API lists its endpoints under the mount (verb,
 full path, declared params), read from its classes in `app/api` and `lib/api`;
 the summary counts them.
 
+`app_only` leaves out the routes Rails' engines and gems draw on their own:
+Active Storage, Action Mailbox's ingresses and its conductor, Turbo Native's
+navigation routes, and Rails' development pages (`rails/info`, `rails/mailers`,
+`rails/welcome`), as `config.excluded_route_prefixes` lists them. A route the
+app's own route files declare is an app route, so `devise_for :users` and the
+`get "up" => "rails/health#show"` health check are listed. A `controller` filter
+searches every route, so `controller:"devise/sessions"` or
+`controller:"active_storage/blobs"` answers whatever `app_only` says.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
-| `controller` | string | - | Filter by controller |
+| `controller` | string | - | Filter by controller; searches every route, framework ones included |
 | `detail` | enum | `standard` | `summary`, `standard`, `full` |
 | `limit` | integer | auto | Max routes to return; the default depends on `detail` |
 | `offset` | integer | `0` | Skip this many routes |
-| `app_only` | boolean | `true` | Leave out internal Rails routes (Active Storage, Action Mailbox, Conductor) |
+| `app_only` | boolean | `true` | Leave out the routes Rails' engines and gems draw on their own (see above) |
 
 <p align="right"><a href="#table-of-contents">↑ back to top</a></p>
 
@@ -295,6 +326,15 @@ the naming rule of its directory when one is known: a loader that imports the
 directory by a derived path (`import(`./dynamic/${path}.controller.ts`)`), or
 two or more confirmed neighbours that all drop the directory's segment.
 
+The change callbacks Stimulus runs itself (`countValueChanged`,
+`itemTargetConnected`, `resultsOutletDisconnected`) are listed with the
+lifecycle hooks, not as actions. The copy-paste markup at `full` detail wires
+each action to the events the app's own templates use (`input->search#queue`),
+and to no named event, so the element's default, when no template wires it; it
+leaves out a method no template names that the controller calls itself, and
+carries a `data-*-class` and `data-*-outlet` attribute for each class and
+outlet the controller reads.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `controller` | string | - | Stimulus controller name |
@@ -304,7 +344,7 @@ two or more confirmed neighbours that all drop the directory's segment.
 
 ### `rails_get_partial_interface`
 
-What locals to pass to a partial and what methods are called on them.
+What locals to pass to a partial and what methods are called on them. Render sites are `render` calls, a `partial:` passed to a Turbo Stream action (`turbo_stream.prepend`) or a broadcast (`broadcast_prepend_to` in a model, controller, job or channel), and jbuilder's `json.partial!` and `json.array! ..., partial:`. A site counts only where Rails would render this file: `_post.html.erb` gets the html, Turbo Stream and broadcast sites and `_post.json.jbuilder` the jbuilder ones, and `render "comments/form"` names comments' form, never the one beside the view. A call that names `formats:` among the options it renders with - beside `partial:` (`render partial: "posts/post", formats: [:json]`), or among `json.partial!`'s keywords - counts for those formats. Rails reads no other key as one: a `format:` is a local, as is any key inside `locals:`, and `render "shared/date", date: d, format: :short` passes every key as a local. In a controller or helper a call inside `format.json { }` counts for json, and any other renders the request's format, so it counts for both. A jbuilder partial's locals are the bare names it reads; a helper, a route helper or a call with parentheses is not a local.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -313,12 +353,12 @@ What locals to pass to a partial and what methods are called on them.
 
 ### `rails_get_turbo_map`
 
-Turbo Stream broadcast-to-subscription wiring with mismatch warnings.
+Turbo Stream broadcast-to-subscription wiring with mismatch warnings. Streams are compared the way Turbo names them, part by part: a record by its model, a symbol or string by its text. So `broadcast_prepend_to [product, :reviews]` (or `broadcast_prepend_to product, :reviews`) in Review, whose `product` is a belongs_to, reaches `turbo_stream_from @product, :reviews`, and `broadcasts_refreshes` reaches `turbo_stream_from @product` on update and destroy and the model's plural stream on create. In a view, `current_user` and `Current.user` name a User record. A `stream` or `controller` filter narrows which streams are shown, each with every broadcaster and subscriber the app has for it, so a stream heard in another controller's views is not called unheard. A part that names nothing the map can resolve (no model by that name, a method rather than an association) is reported as "can't tell", never as a mismatch.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `detail` | enum | `standard` | `summary`, `standard`, `full` |
-| `stream` | string | - | Filter by stream or channel name (e.g., `notifications`) |
+| `stream` | string | - | Filter by stream or channel name (e.g., `notifications`); a name no broadcast or subscription carries says so and lists the app's streams |
 | `controller` | string | - | Filter by controller name (e.g., `messages`) |
 
 ### `rails_get_frontend_stack`
@@ -353,13 +393,19 @@ Test scaffolding that matches your project's patterns (fixtures vs factories, RS
 |:----------|:-----|:--------|:------------|
 | `model` | string | - | Model to generate a model test for (e.g., `User`) |
 | `controller` | string | - | Controller to generate a request test for (e.g., `PostsController`) |
-| `file` | string | - | File to generate tests for, relative to Rails root; the type is detected |
-| `type` | enum | `unit` | `unit`, `request`, `system` |
+| `file` | string | - | File to generate tests for, relative to Rails root; the type is detected (a job gets a job test under test/jobs or spec/jobs) |
+| `type` | enum | `unit` | `unit`, `request`, `system`. With `model` or `controller`, `system` writes a system test that visits the subject's index and show pages |
+
+When the subject's test file exists already, the cases come anyway, addressed to that file, to add the ones it lacks. A controller behind a login filter gets a test that signs in with the app's own sign-in helper and a users fixture or factory where that helper answers the filter: Rails 8's `sign_in_as` for its `require_authentication`, or a `sign_in` for Devise's `authenticate_<scope>!`. Any other filter (a token check, a hand-written one) and any `ActionController::API` controller gets a TODO instead, naming the filter and saying the requests are redirected or refused until the test signs in. Devise and Doorkeeper keep their own sign-in lines.
 
 ### `rails_validate`
 
 Syntax + semantic + Brakeman security validation in one call.
 
+An ERB template is parsed as the method body Rails compiles it into, with the trim tags `<%-` and `-%>` read as tags, as Rails reads them.
+
+JavaScript (`.js`, `.mjs`, `.cjs`) is parsed by `node --check` as the module system Node would load it with: the extension, else the nearest `package.json`'s `type`, else a module when CommonJS rejects only its `import`/`export` (a Stimulus controller). A failure names the line and column node reports. A file node cannot judge is listed as skipped with the reason, not as passed, so the pre-commit hook never stops a commit for syntax the app's own toolchain compiles: JSX or a decorator (`@observable`, `export @controller class`), named by the line node stopped at; a file that declares Flow (`// @flow`), or one Babel compiles - a `babel.config.*` or `.babelrc*` file, or a `"babel"` key in `package.json`, in its folder or one above it, up to the top of the app's repository - where node's error is named beside the skip, since it may be the toolchain's syntax or the file's own mistake; or no `node` on the PATH, where only an unmatched bracket still fails. Type annotations in a `.js` file nothing compiles still fail, as TypeScript and esbuild refuse them there too.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `files` | array | required | File paths to validate |
@@ -378,13 +424,35 @@ Brakeman static analysis: SQL injection, XSS, mass assignment, command injection
 
 > Requires the `brakeman` gem. When the app's bundle does not carry it but the
 > machine has it, the scan runs brakeman as its own process from outside the
-> bundle and says so. When no scan can run, the answer says which case it is:
-> brakeman is nowhere on the machine, or it is installed and produced no report.
+> bundle and says so: the installed gem's own `bin/brakeman`, run by the app's
+> Ruby, not whatever `brakeman` is on PATH. When no scan can run, the answer
+> says which case it is: brakeman is nowhere on the machine, or it is
+> installed and produced no report.
 
 ### `rails_performance_check`
 
 N+1 query risks, missing indexes, missing counter_cache, eager load candidates.
 
+An N+1 risk is an association call on a record that a loop hands out. Each
+action's body and the before filters that run for it say what its instance
+variables hold (`@reviews = @product.reviews.latest`, `@orders =
+current_user.orders`), and its templates and the partials they render say what
+walks them: `@reviews.each do |review|`, `render @reviews`, `render partial:,
+collection:`, `json.array!`, a loop record passed to a partial as a local, or a
+loop in a partial rendered with no locals (`render "dashboard/list"`).
+A `review.user` read there is a risk; the same name anywhere else is not. The
+row names the action and the view the call sits in. `high` means the query
+preloads nothing, `medium` that it preloads other associations, and `low` that
+it preloads this one; a named scope in the query counts with its body, so
+`Post.with_author` preloads what `scope :with_author, -> { includes(:user) }`
+does. `.count` on an association runs a query per record even when preloaded,
+so it stays `high`. `.size`, `.any?`, `.empty?` and `.none?` on a has_many
+whose other side keeps a `counter_cache` read the counter column, so they are
+not a risk. The inverse Rails sets on each record of
+`@product.reviews` (`review.product`) is not a risk, and a branch on a local
+the render passes as a literal (`show_seller: false`) is not read. ERB and
+jbuilder are read; Haml and Slim templates are not, and neither are serializers.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `model` | string | - | Filter results to one model |
@@ -431,7 +499,7 @@ found under a load-order prefix too (`config/initializers/3_omniauth.rb`).
 
 ### `rails_get_env`
 
-Environment variables + credentials keys (values are never exposed). Scans `.rb`, `.rake`, ERB views and config YAML under `app`, `config` and `lib`, plus `config.ru`, `db/seeds.rb`, `db/seeds/` and the Ruby scripts in `bin/`; config YAML matching `sensitive_patterns` (`config/database.yml`) is read only for the ENV names in its ERB tags, credentials and keys are never read, and the answer says so. The env Kamal's `config/deploy.yml` gives the app container is listed too: secret names only, and clear values, except one holding a URL or a key-like token, or under a secret-named variable, which shows as hidden, and one an ERB tag sets, which says so. So are the setting keys in the config gem's `config/settings.yml` and `config/settings/<env>.yml` when the bundle has the config gem, and the attributes of each `Anyway::Config` class in `config/configs` or `app/configs` with the env name it reads (`PAYMENT_API_KEY`), never their values. A variable whose call sites pass different defaults is labelled as such rather than with one site's default; `detail:"full"` names each site's. A default is redacted by the rule a source literal gets: a credential format under any name, a URL's password, and under a secret-named variable a value that is not clearly something else, so an address, URL or hostname default prints as written.
+Environment variables + credentials keys (values are never exposed). Scans `.rb`, `.rake`, ERB views and config YAML under `app`, `config` and `lib`, plus `config.ru`, `db/seeds.rb`, `db/seeds/` and the Ruby scripts in `bin/`. A tag on a YAML comment line is not read: ERB runs it, but what it writes goes with the comment. Config YAML matching `sensitive_patterns` (`config/database.yml`, `config/cable.yml`, `config/storage.yml` and the rest) is read only for the ENV names in its ERB tags, so a default there is listed as present and not read; credentials and keys are never read, and the answer says so. A default is read from a second argument or from a block whose one statement is a literal (`ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" }`). The env Kamal's `config/deploy.yml` gives the app container is listed too: secret names only, and clear values, except one holding a URL or a key-like token, or under a secret-named variable, which shows as hidden, and one an ERB tag sets, which says so. So are the setting keys in the config gem's `config/settings.yml` and `config/settings/<env>.yml` when the bundle has the config gem, and the attributes of each `Anyway::Config` class in `config/configs` or `app/configs` with the env name it reads (`PAYMENT_API_KEY`), never their values. A variable whose call sites pass different defaults is labelled as such rather than with one site's default; `detail:"full"` names each site's. A default is redacted by the rule a source literal gets: a credential format under any name, a URL's password, and under a secret-named variable a value that is not clearly something else, so an address, URL or hostname default prints as written.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -589,21 +657,40 @@ Model association graph in Mermaid or text format.
 | `model` | string | - | Center the graph on this model |
 | `depth` | integer | `2` | Hops from the centre model (1-3) |
 | `format` | enum | `mermaid` | `mermaid`, `text` |
-| `show_cycles` | boolean | `false` | Detect and list circular dependencies |
+| `show_cycles` | boolean | `false` | List circular dependencies: chains of foreign keys that lead back to the model they start from, through another |
 | `show_sti` | boolean | `false` | Show Single Table Inheritance hierarchies |
 
 The graph is capped at 50 nodes, with or without `model`, and says so when it cuts.
 
+A polymorphic `belongs_to` lists the models that implement it, the ones that declare `as:` for it. A cycle follows foreign keys, one edge per key from the table that holds it: a `belongs_to` and the `has_many` or `has_one` at its other end are one key, so two models joined both ways are not a cycle, and neither is a key to the model's own table. With `show_cycles` and no cycle, the answer says none.
+
 ### `rails_migration_advisor`
 
 Migration code generation with duplicate/nonexistent column warnings, reversibility flags, table name normalization. The generated class is stamped with the app's own Rails version (from the booted app, or from `Gemfile.lock` under `--no-boot`); when neither names one, the output says which version it fell back to.
 
+Before the code it warns about what the app's migrations already hold: a
+file already named what the generator would name this one (`rails generate
+migration` refuses that name), and a migration not yet run that already adds
+the column or creates the table when it runs (a `def down`, a `dir.down` or a
+`revert` block only undoes, so what it adds does not count). It also warns
+about a `create_table` for a
+table that exists and a `null: false` column with no default on a table with
+rows (the row count is the database's estimate), and refuses a column type no
+adapter knows. For `remove_column`, `rename_column` and `change_type` it lists
+the lines in `app/`, `lib/` and `config/` that name the column, the code the
+change breaks.
+
+It refuses a `table`, `type` or `new_name` longer than 256 characters, a
+`column` that long outside `create_table`, and `options` longer than 1,024
+characters: no migration takes one, and the code it writes would carry it
+whole.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `action` | enum | *required* | `add_column`, `remove_column`, `rename_column`, `add_index`, `add_association`, `change_type`, `create_table` |
 | `table` | string | *required* | Table name |
-| `column` | string | - | Column name |
-| `type` | string | - | Column type (e.g., `string`, `integer`, `references`) |
+| `column` | string | - | Column name; for `add_association`, the reference (`user`, `parent`) |
+| `type` | string | - | Column type (e.g., `string`, `integer`, `references`); for `add_association` with `column`, the table the reference points at. A `parent` reference with no `parents` table points at its own table |
 | `new_name` | string | - | New column name, for `rename_column` only |
 | `options` | string | - | Extra options (e.g., `null: false, default: 0`) |
 
@@ -620,7 +707,7 @@ Bundled topic index with weighted keyword search. Optional on-demand GitHub fetc
 
 ### `rails_query`
 
-Safe read-only SQL with 4-layer security: regex validation, `SET TRANSACTION READ ONLY`, timeout, column redaction. [Learn about the security model →](SECURITY.md)
+Safe read-only SQL with layered security: regex validation, a PostgreSQL plan check (whole-row leaks, expanded sensitive columns and VOLATILE admin functions refused before anything runs), `SET TRANSACTION READ ONLY`, timeout, and column redaction. [Learn about the security model →](SECURITY.md)
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -631,25 +718,33 @@ Safe read-only SQL with 4-layer security: regex validation, `SET TRANSACTION REA
 
 > Disabled in production by default.
 
+> Name the columns you need. A query that references a sensitive column (directly, or through an alias or expression), serialises a whole row, carries a column-alias list that renames a wildcard (a `VALUES`-body list such as `(VALUES (1,'a')) AS v(id, name)` is allowed - it renames no table column), uses UNION, or calls a session-effecting function is refused with a message that says why. `SELECT *` is allowed and its sensitive columns come back `[FILTERED]`. `SHOW CREATE TABLE` / `SHOW CREATE VIEW` are allowed and their definition text is secret-redacted; other `SHOW CREATE` forms are refused. In the default format a definition is shown whole, as the DDL in a fenced code block with its line breaks kept (a view's character set and collation follow as `name: value` lines); `csv` returns it as one quoted field. When the row limit holds rows back - only when the query really returned more than the cap - the answer says so in every format.
+
+> **Cell rendering by format.** A `markdown` table cell shows `NULL` as `_NULL_`, escapes a pipe (`a\|b`) so it cannot end the cell, renders a line break as the two characters `\n` so it cannot end the row, and shortens a value over 100 characters to `…` (a `SHOW CREATE` definition is not a table cell, so it is never shortened). A `csv` cell is the value itself: `NULL` is an empty field, nothing is escaped beyond RFC 4180 quoting (a field holding a comma, a quote or a line break is wrapped in quotes with its quotes doubled), and nothing is truncated - so a line break stays a real line break inside the quoted field. Binary (non-text) data shows as `[BLOB]` in both.
+
 ### `rails_read_logs`
 
 Reverse file tail with level filtering and sensitive data redaction.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
-| `file` | string | current environment's log | Log file name in `log/` (e.g., `production`, `sidekiq`); the `.log` suffix is optional |
-| `lines` | integer | `50` | Number of lines, max 500 |
+| `file` | string | current environment's log | Log file name in `log/` (e.g., `production`, `sidekiq`); the `.log` suffix is optional. A log that links out of the app is refused and not listed |
+| `lines` | integer | `50` | Number of lines, max 500. With `search`, the number of matching lines to show |
 | `level` | enum | `all` | Minimum level: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `all` |
-| `search` | string | - | Keep lines matching this term. The match runs on the redacted line, so a redacted value cannot be searched for |
+| `search` | string | - | Keep lines matching this term, searched for in the last 4 MB of the file (about 50,000 lines of a typical Rails log); the answer says how many lines that was, and whether older ones were left unsearched. The match runs on the redacted line, so a redacted value cannot be searched for |
 
 ### `rails_diagnose`
 
 One-call error diagnosis with classification, context, recent git changes, and log correlation. It does not call a method undefined when the model's method list could be missing one - a concern's, a parent's, or anything past the payload's own cap.
 
+A `NoMethodError` is a nil reference only when the receiver is nil; on any other receiver it is an undefined method, and on a booted app the answer names the receiver's closest method (`totl` → `total`). An error it has no rule for names the gem or app file that defines the exception class. The error can be pasted as Ruby prints it (`NoMethodError: ...`) or as a Rails log writes it (`NoMethodError (...)`).
+
+Log correlation reads the last megabyte of the current environment's log, the window `rails_read_logs` reads, and shows the latest entry for the error: the request that raised it (path, controller action, parameters, status, request id when the log is tagged), the error line and the first backtrace frames, redacted. It says so when the log holds no entry for the error.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `error` | string | *required* | Error message or class |
-| `file` | string | - | File where error occurred |
+| `file` | string | - | File where error occurred. A path refused on policy is named in the answer, which still diagnoses the error and comes back as an error result ([how a refusal is reported](SECURITY.md#how-a-refusal-is-reported)) |
 | `line` | integer | - | Line number |
 | `action` | string | - | `controller#action` (e.g., `posts#create`); adds that action's context |
 
@@ -657,15 +752,25 @@ One-call error diagnosis with classification, context, recent git changes, and l
 
 PR/commit review with per-file context and warnings.
 
+A removed validation is a `validates` line the diff takes out when no line it adds validates the same attribute; an edited `validates` line is not one.
+
+A changed migration lists the tables it affects: the table each schema method takes first (`add_column`, `remove_columns`, `rename_index`, `add_foreign_key`, ...), every table `drop_table` drops, a renamed table's new name, and for `create_join_table` and `drop_join_table` the join table, named as Rails names it, and the two tables it joins. The first two are shown with the columns the schema has now.
+
+An app in a subfolder of its repository (a monorepo's `backend/`) is reviewed on its own: its changed files, named from the app root as `rails_validate` takes them, and the commits that touched it.
+
+Each diff passes through the redaction every tool's source does, read as the file it comes from, so a secret a change adds or takes out reads `[FILTERED]`, in a hunk header's line too. A changed file on `sensitive_patterns` (`config/database.yml`, `.env`, a key) is listed with its line counts and none of its lines.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
-| `ref` | string | `HEAD` | Git ref to diff against. `HEAD` reviews uncommitted changes |
+| `ref` | string | `HEAD` | Git ref to diff against: a branch, a tag, `HEAD~3` or a commit SHA. `HEAD` reviews uncommitted changes. Any other ref reviews the commits since HEAD left it, as a pull request does: the file list and each file's diff run from the commit the two last shared to HEAD. A ref that names no commit is refused |
 | `files` | array | - | Review only these changed files (omit for all) |
 
 ### `rails_runtime_info`
 
 Live database pool stats, table sizes, pending migrations, cache stats, queue depth.
 
+The pool and the cache are read inside the MCP server process, and the answer says so: the pool's counts are that process's own connections, and a `MemoryStore`'s entries are its own, since each app server process holds its own. A store the processes share (Redis, Memcached, Solid Cache, a file store) is the app's. Another environment that configures a shared store is named, as where the app's cache lives there.
+
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `detail` | enum | `standard` | `summary`, `standard`, `full` |
@@ -673,12 +778,14 @@ Live database pool stats, table sizes, pending migrations, cache stats, queue de
 
 ### `rails_session_context`
 
-Session-aware context tracking across tool calls within a conversation. Pass `action` or `mark`; a call with neither is an error.
+Session-aware context tracking across tool calls within a conversation. Pass `action` or `mark`; a call with neither is an error. A conversation's record keeps its latest 200 queries, and `status` and `summary` say how many older ones it dropped; a param longer than 80 characters is kept as its first 80 and its length.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
-| `action` | enum | - | `status` (queried tools with timestamps), `summary` (short recap), `reset` (clear the session) |
-| `mark` | string | - | Record a tool and its params as already queried (e.g., `get_schema:users`) |
+| `action` | enum | - | `status` (queried tools with timestamps), `summary` (short recap), `reset` (clear this conversation's record) |
+| `mark` | string | - | Record a tool and its params as already queried (e.g., `get_schema:users`). The tool must be one the server has; a short name such as `schema` is taken |
+
+Each conversation has its own record: over HTTP, one server process serves every client, and each client's `Mcp-Session-Id` keeps its calls, and its `reset`, to itself. A tool that answers by calling others (`rails_get_context`, `rails_diagnose`, `rails_review_changes`) is recorded as the one call the client made.
 
 <p align="right"><a href="#table-of-contents">↑ back to top</a></p>
 
@@ -686,7 +793,7 @@ Session-aware context tracking across tool calls within a conversation. Pass `ac
 
 ## Live Resources (VFS)
 
-In addition to tools, AI clients can read structured data through **resource templates** - `rails-ai-context://` URIs introspected fresh on every request. Zero stale data.
+In addition to tools, AI clients can read structured data through **resource templates** - `rails-ai-context://` URIs introspected afresh on every request, after the app's code is reloaded for any edit.
 
 | URI Pattern | Returns |
 |:------------|:--------|
@@ -698,6 +805,10 @@ In addition to tools, AI clients can read structured data through **resource tem
 
 The legacy `rails://models/{name}` form is still accepted.
 
+`controllers/{name}/{action}` also reads an action that a concern or a parent controller gives and no route names, as the `rails_get_controllers` `action` lookup does. `inherited_from` names the parent controller an action comes from. `note` says why the controller's `actions` leave out one that no route names. For a controller that cannot load - its file, or one its class body needs, does not compile - both reads give its `error` and `file` and nothing read from its source.
+
+A read for a name the app does not have - a model, a controller, an action, a view - fails with a JSON-RPC `-32602` error whose message gives the reason and whose `data.available` lists the names there are: for a view, the ones in its directory, else the app's first twenty. So does a view over the size cap, and a URI the server does not serve, whose `data.available` lists the resources and templates it does. A path refused on policy fails as `Resource not found`, without saying why.
+
 Plus 9 static resources (schema, routes, conventions, gems, controllers, config, tests, migrations, engines).
 
 <p align="right"><a href="#table-of-contents">↑ back to top</a></p>

data/docs/TROUBLESHOOTING.md

@@ -11,7 +11,7 @@
 ---
 
 > [!TIP]
-> Always start with `rails ai:doctor`. It runs 25 checks and catches most issues automatically.
+> Always start with `rails ai:doctor`. It checks the app, its databases, the MCP configs and the context files, and catches most issues automatically.
 
 ## Diagnostics first
 
@@ -20,7 +20,7 @@ rails ai:doctor          # In-Gemfile
 rails-ai-context doctor  # Standalone
 ```
 
-This runs 25 checks and returns an AI readiness score (0-100). Each failed check includes a fix suggestion.
+This runs every check that applies to the app ([the list](GUIDE.md#diagnostics)) and returns an AI readiness score (0-100). Each check that fails or warns includes a fix suggestion.
 
 ---
 
@@ -70,9 +70,10 @@ ls -la .mcp.json .cursor/ .vscode/ .github/
    - OpenCode: `opencode.json`
    - Codex: `.codex/config.toml`
 
-2. Verify the command works:
+2. Verify the command the config holds works:
    ```bash
-   bundle exec rails ai:serve
+   bundle exec rails-ai-context serve   # in-Gemfile
+   rails-ai-context serve               # standalone
    # Should output nothing (waiting for stdio input)
    # Ctrl+C to stop
    ```
@@ -82,18 +83,66 @@ ls -la .mcp.json .cursor/ .vscode/ .github/
    rails generate rails_ai_context:install
    ```
 
+### "Could not write .vscode/mcp.json - that tool will not auto-discover the MCP server"
+
+The install never replaces a config it cannot write back faithfully: one that does not parse as JSON, one holding comments that writing it back would drop, or one that is not UTF-8. Trailing commas, which VS Code and OpenCode accept, are read the way they read them under json 2.9 or later; an older json refuses them, as JSON does. The line after the warning says which, and ends with the exact entry to add, as `Add {"servers":{...}} to it by hand`. Add that entry yourself, or remove the comments (and, under an older json, the trailing commas) and run the install again. `doctor` names the same entry for a file whose comments keep the install out, rather than sending you back to the install, and asks for one that is not UTF-8 to be saved as UTF-8 first.
+
+Claude Code reads `.mcp.json` with a plain JSON parser, and loads no server from a file holding a comment or a trailing comma ("MCP config is not a valid JSON"); Cursor's `.cursor/mcp.json` is held to plain JSON too. Either one is reported as `Claude Code cannot read it: it holds a trailing comma, which JSON does not allow`, by the install and by `doctor`, however current the entry in it. Make the file plain JSON and run the install again. `doctor` reports one that does not parse, or holds no object to merge into, a workspace's above the app included. Dropping an AI tool leaves such a file alone the same way and names the entries to remove.
+
+### Codex: "TOML parse error ... duplicate key"
+
+Codex refuses a `config.toml` that declares a server twice. An earlier install could write a second `[mcp_servers.rails-ai-context]` table beside the server spelled another way: a quoted name (`[mcp_servers."rails-ai-context"]`), an inline table under `[mcp_servers]`, or dotted keys. `doctor` names such a file. Two tables are merged into one when the install runs again; for an inline table or dotted keys, delete one of the two by hand.
+
+The install now finds the server however its name is quoted and replaces its table where it stands. An entry of the gem's written as an inline table or with dotted keys is left as it is, with a warning, as is a file whose `mcp_servers` is one inline table: write it as a `[mcp_servers.rails-ai-context]` table, or delete it, and the next run keeps it current. `doctor` gives that same edit for any problem in such an entry that only a rewrite fixes, a stale env snapshot included.
+
+### Codex: "stream did not contain valid UTF-8"
+
+Codex reads `config.toml` as TOML, which is UTF-8, and loads nothing from a file holding a byte that is not - one in a comment included. The install still writes its table into such a file, keeping every byte around it, and says `Codex CLI cannot read it: it is not UTF-8, which TOML is`; `doctor` fails it in the same words. Save the file as UTF-8.
+
 ### "MCP server fails to start"
 
+`rails ai:doctor` (or `rails-ai-context doctor`) checks the command each config holds and says which one cannot start and why. The usual causes:
+
+- `rails-ai-context is not currently included in the bundle`: the config runs `bundle exec rails-ai-context serve`, but the gem left the app's Gemfile. A standalone install runs `rails-ai-context serve`: run `rails-ai-context init` to rewrite the configs.
+- The config runs `rails-ai-context serve` while the app's Gemfile.lock carries the gem: it needs a copy installed outside the bundle as well, which hands the run to the bundle's. Run `rails generate rails_ai_context:install` to write `bundle exec rails-ai-context serve`.
+- `can't find executable rails-ai-context for gem rails-ai-context`: the bundle's copy of the gem lists no executable, as a `path:` copy of 5.32.2 or earlier outside a git checkout does. Point the Gemfile at a git checkout or a release.
+- On Windows, a config that runs `bundle` or `rails-ai-context` itself rather than through `cmd /c`: those are batch files there, which Claude Code, Codex and the other clients that start a server without a shell do not run (`doctor` warns about it). Run the install again; on Windows it writes `cmd /c bundle exec rails-ai-context serve`.
+- On macOS or Linux, a config that runs `cmd /c ...`: it was written on Windows, and there is no `cmd` here (`doctor` fails it). Run the install again on this machine, and keep the MCP configs out of git if the team works on both.
+
 Check for Bundler/Ruby path issues:
 
 ```bash
 which bundle
-which rails
+which rails-ai-context
 ruby -v
 ```
 
 For Codex CLI specifically, the env section in `.codex/config.toml` must match your current Ruby environment. Re-run install if you changed Ruby versions.
 
+### Answers say "Boot did not finish within 20s"
+
+The app's boot hung, usually an initializer waiting on a service that is
+down (Redis, Elasticsearch, a secrets store). A stdio server gives the boot 20
+seconds, because its client stops waiting for the first answer after about 30
+(Claude Code, the MCP Inspector), and then serves the static tier; every other
+command gives it 60. Start the service, or, for an app that is healthy but
+slow to boot, raise both limits in the server's MCP entry: the boot's with
+`RAILS_AI_CONTEXT_BOOT_TIMEOUT` (seconds) in its `env`, and the client's with
+its own setting (Claude Code reads `MCP_TIMEOUT`, in milliseconds). Raising
+only the boot's leaves a client that gives up first. `rails ai:serve` has no
+static tier, so it exits with the same message instead.
+
+### A server set up for a folder of apps fails to start
+
+`rails-ai-context init` run in a folder of apps writes entries that name each app relative to that folder (`--app-path shop`, and for an in-Gemfile app `BUNDLE_GEMFILE=shop/Gemfile`, or the monorepo's shared Gemfile its `config/boot.rb` names). Claude Code, Codex and OpenCode start a server in the folder they were launched in, so:
+
+1. Start the AI tool in the folder of apps, not inside one of them. Launched inside an app, the tool still reads the folder's config above it, and the server says `--app-path shop is read from ...; it names an app from ...`. An in-Gemfile entry fails earlier, in Bundler, with a Gemfile it cannot find. To work in one app on its own, run `rails-ai-context init` inside it too.
+2. Check the Ruby. Every server in the folder runs under the Ruby your version manager picks in the folder, and `init` warns about an app that declares another. `Your Ruby version is ..., but your Gemfile specified ...` from an in-Gemfile entry is that case: install the app's bundle for that Ruby, or give the app its own config with `init` inside it.
+
+### "No Rails app found in ..., and 2 below it"
+
+You ran a command in a folder that holds several apps. The error lists the exact command for each, with `--app-path`. To set them all up at once, run `rails-ai-context init` in that folder.
+
 ### "Tools return empty results"
 
 1. Check that your Rails app boots: `rails runner "puts 'ok'"`
@@ -110,7 +159,8 @@ dependency graph, or launching from inside another Bundler project's
 directory. Fixes:
 
 1. Launch `rails-ai-context serve` with the app root as the working directory
-   (the generated MCP configs do this by default).
+   (the generated MCP configs do this by default; a folder of apps' configs
+   start in that folder and name the app with `--app-path`).
 2. Make sure `GEM_PATH` covers the complete default gem path
    (`gem env path`), not just `gem env gemdir` - Ruby's bundled gems
    (racc, etc.) live in a separate directory.
@@ -120,10 +170,29 @@ directory. Fixes:
 ### MCP server responds slowly
 
 - Check `config.cache_ttl` - lower values mean more frequent re-introspection
+- Without the `listen` gem, each call first checks the app's files for edits, about 100 ms at 10,000 files; adding `listen` to the development group replaces that check with live reload
 - Check `config.preset` - `:standard` is faster than `:full`
 - Large schema files (>10MB) slow down schema introspection
 - Run `rails ai:doctor` - it checks schema size and view count
 
+### The stdio server stops with "MCP stdio connection closed: stdio frame exceeds 4194304 bytes"
+
+The MCP SDK reads one JSON-RPC message per line and refuses a line of 4 MiB or more. The server answers the client with a JSON-RPC `-32600` error, prints the reason on stderr and exits 1. The message is too large for any client to need; look for a tool argument the client filled with a whole file.
+
+### HTTP answers an HTML error page while a migration is pending
+
+In development Rails answers every request with its pending-migration page, and the mounted engine is a route like any other. Run the migration, or use `auto_mount`, stdio or the standalone server, which all answer ahead of that check; `rails_runtime_info` lists the pending migrations.
+
+### HTTP answers 403 "Forbidden: Invalid Host header"
+
+The standalone server (`serve --transport http`, `rails ai:serve_http`) answers only requests whose `Host` header is `127.0.0.1`, `::1` or `localhost`, as the MCP SDK does, to stop DNS rebinding. A client that reaches it by the machine's IP or hostname is refused, whatever `http_bind` says. Connect to `localhost`: through a published container port, or an SSH tunnel (`ssh -L 6029:localhost:6029 your-host`).
+
+The mounted engine and `auto_mount` answer the hosts the app's `config.hosts` allows, as the rest of the app does. Add the name the client uses to `config.hosts`, the way you would for any other route.
+
+### HTTP answers 403 "does not serve MCP over HTTP in production"
+
+The mounted engine and `auto_mount` refuse every request outside development and test (production, staging) unless the app sets `config.allow_http_in_production = true`. Set it only with the endpoint behind your app's authentication; see [Security](SECURITY.md#mcp-http-transport).
+
 ---
 
 ## Context file issues
@@ -151,7 +220,11 @@ rails ai:context
 
 ### "My custom content in CLAUDE.md was overwritten"
 
-The gem uses section markers (`<!-- BEGIN/END rails-ai-context -->`) to preserve user content. Content outside these markers is preserved. If markers were removed, the gem may overwrite.
+The gem writes its section between `<!-- BEGIN rails-ai-context -->` and `<!-- END rails-ai-context -->` and replaces only what lies between them, so text above and below the markers survives every run; text inside them does not. A file with no markers at all gets the section added at the top, and its own text kept below.
+
+The per-directory `app/models/AGENTS.md` and `app/controllers/AGENTS.md` that OpenCode and Codex read follow the same rule. One the gem generated whole carries `> Auto-generated by rails-ai-context. Do not edit manually.` and is rewritten whole; one you wrote yourself keeps its text, and the listing goes between the markers above it.
+
+If one marker goes missing, or the file holds a second pair, nothing says where the gem's section ends. The run then leaves the file as it is and reports it as `unpaired rails-ai-context marker, left as it is`. Put the lost marker back where the gem's section ends, or delete the leftover section with its markers, and the next run updates the file again.
 
 ### "Generated files are too large"
 
@@ -218,6 +291,9 @@ brew install ripgrep
 
 # Ubuntu
 apt install ripgrep
+
+# Windows
+winget install BurntSushi.ripgrep.MSVC
 ```
 
 The gem falls back to Ruby regex if ripgrep isn't available. Search still works, just slower on large codebases.
@@ -238,7 +314,7 @@ Standalone mode boots the app with a small shim, then restores the `$LOAD_PATH`
 
 The file is read from the app root, once, at boot, and an initializer does not replace it: a `configure` block wins only the keys it assigns, key by key ([Precedence](CONFIGURATION.md#precedence)). In standalone mode the initializer contributes nothing at all, since the gem is not loaded while `config/initializers` runs. Check:
 
-1. You are in the app root, or passed `--app-path`.
+1. You are inside the app, or passed `--app-path`. A command run from a subdirectory reads the config of the app root it walks up to, and names it on stderr.
 2. The key is one the gem knows. An unknown key warns on stderr and is ignored.
 3. The file is readable and parses. Corrupted YAML degrades gracefully with a warning.
 
@@ -262,10 +338,12 @@ Without it, the tool reports "not installed" but the gem works fine otherwise.
 
 The scan runs under the app's own bundle, so a brakeman installed globally is
 not on its load path. The tool falls back on its own: it runs the installed
-brakeman as a separate process outside the bundle and says so under the
-results. This message means that fallback produced no report either - the gem
-is there and the run failed. Run `brakeman` in the app directory to see what
-it hit, or add it to the Gemfile so the scan runs in-process:
+gem's `bin/brakeman` with the app's Ruby, as a separate process outside the
+bundle, and says so under the results. This message means that fallback
+produced no report either - the gem is there and the run failed. `rails
+ai:doctor` runs the same script's `--version` and names what it printed. Run
+`brakeman` in the app directory to see what it hit, or add it to the Gemfile
+so the scan runs in-process:
 
 ```bash
 bundle add brakeman --group development