rails-ai-context 5.32.2 → 5.34.0

data/docs/GUIDE.md

@@ -102,8 +102,8 @@ No Gemfile entry, no initializer, no files in your project besides config and co
    a. All of the above
    ```
 
-   There is no "none" choice. An empty answer, or one with no valid number in it, prints `No tools selected - defaulting to all.` and selects all five.
-2. **Offers to clean up tools you dropped.** Only on a re-run, and only when the last recorded selection (the `config.ai_tools` line in the initializer, else `.rails-ai-context.yml`) has a tool you did not pick this time. It lists them and asks `Remove their generated files?` with `y` (all), `n` (keep, the default) or numbers like `1,2`. A yes removes only what the gem generated: the rule files it names inside the tool's rules directory (the directory goes too when nothing else is left in it), and the block between the `rails-ai-context` markers in a root file such as `CLAUDE.md`. A rule file you wrote by hand, your own lines around the markers, a root file with no markers and a symlink are left alone. It also keeps any file a remaining tool shares (`AGENTS.md`), and takes only the `rails-ai-context` entry out of the tool's MCP config.
+   On a re-run the menu is followed by the selection recorded last time, as `Currently selected: 1,2 (Claude Code, Cursor)`. There is no "none" choice. An empty answer selects all five, and so does one with no valid number in it, which says so (`"9" names no tool - selecting all.`).
+2. **Offers to clean up tools you dropped.** Only on a re-run, and only when the last recorded selection (the `config.ai_tools` line in the initializer, else `.rails-ai-context.yml`) has a tool you did not pick this time. It lists them and asks `Remove their generated files?` with `y` (all), `n` (keep, the default) or numbers like `1,2`. A yes removes only what the gem generated: the rule files it names inside the tool's rules directory (the directory goes too when nothing else is left in it), and the block between the `rails-ai-context` markers in a root file such as `CLAUDE.md`. A rule file you wrote by hand, your own lines around the markers, a root file with no markers and a symlink are left alone. It keeps any file shared with a tool whose files stay (`AGENTS.md`) - one still selected, or one dropped whose files you kept by leaving its number out - and says so, and takes only the `rails-ai-context` entry out of the tool's MCP config - a config left with no other entry is deleted, and named as removed. A tool's dot-directory the cleanup emptied (`.cursor/`, `.github/`, `.codex/`, `.vscode/`) goes too; one that still holds a file of yours stays.
 3. **Asks what to write**, then `Enter number (default: 1):`
 
    ```
@@ -113,11 +113,11 @@ No Gemfile entry, no initializer, no files in your project besides config and co
    ```
 
    Choices 1 and 3 set `tool_mode` to `:mcp`, choice 2 sets it to `:cli`. Choice 3 also sets `context_files` to `false`. Any other answer counts as 1.
-4. **Writes the MCP config for each selected tool** (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`). Skipped for choice 2. An existing file is merged: only the `rails-ai-context` entry is added or replaced.
-5. **Creates or updates `config/initializers/rails_ai_context.rb`.** A new file gets your three answers as live lines (`config.ai_tools`, `config.tool_mode`, `config.context_files`) and every other option commented out at its default, wrapped in `if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)`. In an existing file it rewrites those three lines, appends any config section the file lacks, adds the guard if it is missing, and leaves the rest alone.
-6. **Writes `.rails-ai-context.yml`** with `ai_tools`, `tool_mode` and `context_files`. Other keys already in the file are kept.
+4. **Writes the MCP config for each selected tool** (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`). Skipped for choice 2, which instead lists any config that still starts `rails-ai-context` and asks `Remove rails-ai-context from them? (y/N)`: CLI mode starts no MCP server. A yes takes out only the gem's entries, as step 2 does. An existing file is merged: only the `rails-ai-context` entry is added or replaced. One that does not parse as JSON, or holds comments a rewrite would drop, is left as it is, with a warning that names the entry to add by hand. Each file is read as its client reads it. VS Code's and OpenCode's take JSONC, comments and trailing commas (read under json 2.9 or later); Claude Code reads `.mcp.json` as plain JSON, and Cursor's `.cursor/mcp.json` is held to plain JSON too, so a comment or a trailing comma in either is reported as one the client cannot read, and the file left as it is. In `.codex/config.toml` the server's table is found however its name is quoted, and replaced 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, since a table added beside it would declare the server twice, which Codex refuses.
+5. **Creates or updates `config/initializers/rails_ai_context.rb`.** A new file gets your three answers as live lines (`config.ai_tools`, `config.tool_mode`, `config.context_files`) and every other option commented out at its default, wrapped in `if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)`; it passes the omakase Rubocop a new Rails app runs. In an existing file it rewrites those three lines where the value changed - keeping the line's indentation and any note of your own after it - appends any config section the file lacks, adds the guard if it is missing, and leaves the rest alone.
+6. **Writes `.rails-ai-context.yml`** with `ai_tools`, `tool_mode` and `context_files`. Only a key whose value changed is rewritten, where it stands; your comments and other keys are kept, and a run that changes no value leaves the file as it was.
 7. **Adds lines to `.gitignore`**, if the file exists: `.ai-context.json` (not for choice 3) and `.codex/config.toml` (always, because it holds this machine's Ruby paths). A line that is already there is not added again.
-8. **Asks about a pre-commit hook:** `Install a pre-commit hook that validates Rails references? (y/N)`. Only `y` installs it. The hook runs `rails 'ai:tool[validate]'` on the staged `.rb` and `.erb` files. No question is asked when the app has no `.git` directory or when the hook is already installed. When another `.git/hooks/pre-commit` exists it prints `Skipped pre-commit hook (existing hook found - add manually)` and moves on.
+8. **Asks about a pre-commit hook:** `Install a pre-commit hook that checks staged Ruby, ERB and JavaScript files for syntax errors? (y/N)`. Only `y` installs it. The hook runs `bundle exec rails-ai-context tool validate` (`rails-ai-context tool validate` in a standalone install) on the staged `.rb`, `.erb`, `.js`, `.mjs` and `.cjs` files and stops a commit whose files do not parse (JavaScript is parsed by `node`, as [`rails_validate`](TOOLS.md#rails_validate) describes); the Rails-reference checks (`level=rails`) are left to the tool, as Brakeman would slow every commit. An app that cannot boot (an initializer that needs a variable the shell lacks, say) is still checked, from its source, and the hook shows why it did not boot; it shows whatever else the check prints to stderr too, so a check that cannot run says why. Every staged name is read whole, one with characters outside ASCII included; a name holding a comma, which the files list cannot carry, is named and left unchecked. It goes where git runs hooks (`git rev-parse --git-path hooks`), so an app checked out as a submodule, an app inside a monorepo and a repo with `core.hooksPath` set all get it where git will run it. The hook names the apps it covers and validates each one's staged files (deleted ones aside) from inside that app; installing in a second app of the same monorepo adds it to the hook, unless the hook was changed by hand, which it says, and for an app below the top of the repository the question names the repository. A hook an earlier version wrote, and nobody changed since, is brought up to date without asking again: the oldest handed validate the files a commit deletes too, and the commit failed on them, and later ones ran `rails 'ai:tool[validate]'`, which has to boot the app, with its errors thrown away, so an app that could not boot failed every commit with no reason given. Any other hook that runs `rails-ai-context` - one changed by hand, or a team's own that calls it among other checks - is left as it is, with a message. No hook is offered for an app the repository does not track yet (an app under a dotfiles repository at `$HOME`, say), nor into a `core.hooksPath` outside the repository, which every repository using it shares; both say why. No question is asked outside a git repository or when the hook already covers the app. When another `pre-commit` hook exists there it prints `Skipped pre-commit hook (existing hook found - add manually)` and moves on.
 9. **Generates the context files** for the selected tools. Skipped for choice 3. If files that v5.0.0 stopped generating are still there (`.claude/rules/rails-ui-patterns.md`, `.claude/rules/rails-accessibility.md`, `.cursor/rules/rails-ui-patterns.mdc`, `.github/instructions/rails-ui-patterns.instructions.md`), it lists them first and asks `Delete them? [y/N]:`. Without a terminal, or under `--defaults`, it prints the `rm` command and does not ask.
 10. **Prints a summary:** the files each selected tool got and the commands to run next.
 
@@ -126,12 +126,14 @@ Two flags change the prompts:
 - `--defaults` answers every prompt with its default: all five tools, keep dropped tools' files, choice 1, no hook, keep legacy files. Piping an empty stdin does the same.
 - `--mcp-only` skips the step 3 question and acts as choice 3. Steps 1, 2 and 8 still ask.
 
+Run from a mountable engine's root, where `bin/rails` boots `test/dummy`, the install goes into the engine's root - the folder an editor is opened at, and the one every `rails-ai-context` command run there reads: the MCP configs, `.rails-ai-context.yml`, the `.gitignore` lines and the context files, which are generated from the engine's source the way its MCP server reads it there. No initializer is written, since Rails runs an engine's `config/initializers` in every app that mounts it and the gemspec ships them; one an earlier install left there is named, with a note to delete it. Step 8 offers no hook at the engine's root (its rake tasks run in the dummy app, as `app:ai:*`), and the summary lists the commands that work at the engine's root, `bundle exec rails-ai-context ...`. The context files written there name the same commands for their CLI fallback and the server, as do the tools' own hints. `bundle exec rails-ai-context doctor` at the engine's root diagnoses the dummy app and reads this install, as `bin/rails app:ai:doctor` does.
+
 A team that wants no AI tool files in the repo can skip the generator. The gem needs none of its output: `rails 'ai:tool[NAME]'`, `rails ai:serve`, `rails ai:doctor` and the `rails-ai-context` binary all work on the defaults with no initializer, no `.rails-ai-context.yml` and no MCP config. `rails ai:context` is the one to leave alone in that setup, since it writes context files. To make that safe too, set `config.ai_tools = []` in an initializer: an empty list means no tool, so nothing is written and nothing is asked.
 
 Two other entry points ask the same step 1 and step 3 questions:
 
-- `rails-ai-context init` (standalone) asks both, then offers the step 2 and step 9 cleanups, writes `.rails-ai-context.yml`, the MCP configs and the `.gitignore` lines, and generates the context files. On an MCP-only run it skips the step 9 question, as the generator does. It never creates the initializer (in one that exists it updates `config.ai_tools`, `config.tool_mode` and `config.context_files`), never offers the pre-commit hook, and has `--mcp-only` but no `--defaults`.
-- `rails ai:context` asks step 1 only when no tool selection is recorded, and step 3 only when no `tool_mode` is recorded. It then writes `.rails-ai-context.yml`, the MCP configs and the `.gitignore` lines before generating. It does not create the initializer or offer the hook.
+- `rails-ai-context init` (standalone) asks both, then the step 2 cleanup question, step 4's question about MCP configs when the answer was CLI mode, and the step 9 question. Only then does it boot the app, so that every gem the app locks loads at the app's pin, and write: the cleanup, `.rails-ai-context.yml`, the MCP configs, the `.gitignore` lines and the context files. An MCP-only run skips the step 9 question, as the generator does, and boots nothing. It never creates the initializer (in one that exists it updates `config.ai_tools`, `config.tool_mode` and `config.context_files`), never offers the pre-commit hook, and has `--mcp-only` but no `--defaults`. Typed outside the app (`init --app-path ../shop`), it names the files it wrote from there, as `../shop/.mcp.json`. Run in a folder that holds several apps, it asks once and sets them all up: each app's own `.rails-ai-context.yml` and context files, and one MCP server per app in the folder's configs ([`init`](CLI.md#init-standalone-only)).
+- `rails ai:context` asks step 1 only when no tool selection is recorded, and step 3 only when no `tool_mode` is recorded. It then writes `.rails-ai-context.yml`, the MCP configs and the `.gitignore` lines before generating. It does not create the initializer or offer the hook. `rails-ai-context context` brings the MCP configs of a recorded selection up to date the same way, and `rails ai:context:<tool>` writes that tool's MCP config along with its files.
 
 ---
 
@@ -146,8 +148,9 @@ rails ai:context
 ```
 
 - CLAUDE.md, AGENTS.md, .cursorrules and copilot-instructions.md ≤150 non-blank
-  lines (`claude_max_lines`). Over budget, data lines are cut and the Commands,
-  Warnings, Rules and MCP-tools sections kept whole
+  lines (`claude_max_lines`). Over budget, the data sections are cut first; the
+  title and the Commands, Warnings, Rules and Tools sections are never cut, so a
+  budget smaller than they are (about 110 lines) leaves just them
 - Files contain a project overview + MCP tool reference
 - AI uses MCP tools for detailed data on-demand
 - **Best for:** all apps, especially large ones (30+ models)
@@ -160,7 +163,9 @@ rails ai:context:full
 CONTEXT_MODE=full rails ai:context
 ```
 
-- Dumps everything into the root files CLAUDE.md, AGENTS.md and copilot-instructions.md (schema, all models, all routes, etc.). The split rule files and Cursor's files are the same in both modes
+- Dumps everything into the root files CLAUDE.md, AGENTS.md and copilot-instructions.md: every table with its column types, defaults, indexes and foreign keys; every model with its associations, validations, scopes, callbacks, enum values and constants; the app's own routes (the framework's are counted, not listed); Stimulus controllers; and the rest of the introspection. The split rule files and Cursor's files are the same in both modes
+- Each root file ends with the same tools guide and anti-hallucination protocol the compact files carry, so OpenCode and Codex, which read AGENTS.md alone, get them too
+- A plain `rails ai:context` writes compact files again unless `config.context_mode` is `:full`, so each file's last line names the command that keeps full mode: `CONTEXT_MODE=full rails ai:context`, or for a standalone install `rails-ai-context context`, which reads `context_mode` from `.rails-ai-context.yml`
 - Can produce thousands of lines for large apps
 - **Best for:** small apps (<30 models) where the full dump fits in context
 
@@ -198,10 +203,10 @@ A file whose section has nothing in it is not written. An app with no models get
 | File | Purpose | Notes |
 |------|---------|-------|
 | `CLAUDE.md` | Main context file | ≤150 lines in compact mode. Claude Code reads this automatically. |
-| `.claude/rules/rails-schema.md` | Database table listing | Auto-loaded by Claude Code alongside CLAUDE.md. |
+| `.claude/rules/rails-schema.md` | Database table listing | Every database's tables, each database under its own heading when the app has more than one. A database of Solid Queue, Solid Cache or Solid Cable tables only, as Rails 8's queue, cache and cable are, is named in CLAUDE.md instead (`queue: Solid Queue (13 tables)`). Loaded when Claude Code opens a schema dump or a migration. |
 | `.claude/rules/rails-models.md` | Model listing with associations | Auto-loaded by Claude Code alongside CLAUDE.md. |
 | `.claude/rules/rails-context.md` | Project context and conventions | Auto-loaded by Claude Code alongside CLAUDE.md. |
-| `.claude/rules/rails-mcp-tools.md` | Full MCP tool reference | Parameters, detail levels, pagination, workflow guide. |
+| `.claude/rules/rails-mcp-tools.md` | Tool reference | Detail levels and the table of every tool. Loaded beside CLAUDE.md, which carries the protocol, the workflows and the rules, so they are not read twice; with `generate_root_files` off it carries them itself. |
 | `.claude/rules/rails-components.md` | View component listing | Written only when the app has view components. |
 
 ### OpenCode (3 files)
@@ -209,8 +214,8 @@ A file whose section has nothing in it is not written. An app with no models get
 | File | Purpose | Notes |
 |------|---------|-------|
 | `AGENTS.md` | Main context file | Native OpenCode format. ≤150 lines in compact mode. OpenCode also reads CLAUDE.md as fallback. |
-| `app/models/AGENTS.md` | Model reference | Auto-loaded by OpenCode when reading files in `app/models/`. |
-| `app/controllers/AGENTS.md` | Controller reference | Auto-loaded by OpenCode when reading files in `app/controllers/`. |
+| `app/models/AGENTS.md` | Model reference | Auto-loaded by OpenCode when reading files in `app/models/`. One you wrote yourself keeps its text, with the listing added between markers. |
+| `app/controllers/AGENTS.md` | Controller reference | Auto-loaded by OpenCode when reading files in `app/controllers/`. One you wrote yourself keeps its text, with the listing added between markers. |
 
 ### Cursor (5 files)
 
@@ -230,7 +235,7 @@ A file whose section has nothing in it is not written. An app with no models get
 | `.github/instructions/rails-models.instructions.md` | Model context | `applyTo: app/models/**/*.rb` - loaded when editing models. |
 | `.github/instructions/rails-controllers.instructions.md` | Controller context | `applyTo: app/controllers/**/*.rb` - loaded when editing controllers. |
 | `.github/instructions/rails-context.instructions.md` | Project context and conventions | `applyTo: **/*` - loaded everywhere. |
-| `.github/instructions/rails-mcp-tools.instructions.md` | MCP tool reference | `applyTo: **/*` - loaded everywhere. |
+| `.github/instructions/rails-mcp-tools.instructions.md` | Tool reference | `applyTo: **/*` - loaded everywhere. Detail levels and the table; the protocol and workflows are in copilot-instructions.md, or here too with `generate_root_files` off. |
 
 ### Generic (1 file)
 
@@ -263,14 +268,18 @@ unmarked file was generated with the app running.
 | `rails ai:context:full` | full | all | Generate all files in full mode |
 | `rails ai:context:claude` | compact | Claude | CLAUDE.md + .claude/rules/ |
 | `rails ai:context:opencode` | compact | OpenCode | AGENTS.md + per-directory AGENTS.md |
-| `rails ai:context:codex` | compact | Codex | AGENTS.md + per-directory AGENTS.md (same files as OpenCode; `.codex/config.toml` comes from the installer or `rails ai:context`) |
+| `rails ai:context:codex` | compact | Codex | AGENTS.md + per-directory AGENTS.md (same files as OpenCode), and `.codex/config.toml` in MCP mode |
 | `rails ai:context:cursor` | compact | Cursor | .cursor/rules/ |
 | `rails ai:context:copilot` | compact | Copilot | copilot-instructions.md + .github/instructions/ |
 | `rails ai:context:json` | - | JSON | .ai-context.json |
 | `CONTEXT_MODE=full rails ai:context:claude` | full | Claude | Full dump for Claude only |
-| `CONTEXT_MODE=full rails ai:context:cursor` | full | Cursor | Full dump for Cursor only |
+| `CONTEXT_MODE=full rails ai:context:opencode` | full | OpenCode | Full dump in AGENTS.md, which Codex reads too |
 | `CONTEXT_MODE=full rails ai:context:copilot` | full | Copilot | Full dump for Copilot only |
 
+Cursor's files are the same in both modes, so `CONTEXT_MODE=full` changes nothing for `rails ai:context:cursor`.
+
+Each `rails ai:context:<tool>` adds its tool to the recorded selection and, in MCP mode, writes that tool's MCP config too (`.cursor/mcp.json` for Cursor), since its files tell the AI to call the MCP tools.
+
 ### CLI tools
 
 | Command | Description |
@@ -290,7 +299,7 @@ unmarked file was generated with the app running.
 
 | Command | Description |
 |---------|-------------|
-| `rails ai:doctor` | Run up to 25 diagnostic checks. Reports pass/warn/fail with fix suggestions. AI readiness score (0-100). `STRICT=1` exits 1 when a check fails. |
+| `rails ai:doctor` | Run the diagnostic checks that apply to the app. Reports pass/warn/fail with fix suggestions. AI readiness score (0-100). `STRICT=1` exits 1 when a check fails. |
 | `rails ai:watch` | Watch for file changes and auto-regenerate context files. Requires `listen` gem. |
 | `rails ai:inspect` | Print introspection summary to stdout. Useful for debugging. |
 | `rails ai:facts` | Print a short schema facts summary (tables, columns, indexes, associations, dependencies). |
@@ -320,7 +329,7 @@ rails-ai-context version                   # Print version
 rails-ai-context help                      # Show all commands
 ```
 
-Run it from your Rails app root, or pass `--app-path PATH`. Booting needs `config/environment.rb`. When the app cannot boot, or with `--no-boot`, every command except `doctor` reads the source files instead.
+Run it anywhere inside your Rails app, from a folder holding one app, or pass `--app-path PATH` ([how the app is found](CLI.md#tool)). Booting needs `config/environment.rb`. When the app cannot boot, or with `--no-boot`, every command except `doctor` reads the source files instead.
 
 **Config:** Standalone mode reads from `.rails-ai-context.yml` (created by `init`), and that is its only config source - the gem is not loaded while `config/initializers` runs. If no config file exists, defaults are used. With the gem in the Gemfile the two merge key by key ([Precedence](CONFIGURATION.md#precedence)).
 
@@ -393,7 +402,11 @@ end
 ```
 
 - **`:mcp`** - context files show MCP tool syntax (e.g. `rails_get_schema(table: "users")`). CLI tools still available as fallback.
-- **`:cli`** - context files show CLI syntax (e.g. `rails 'ai:tool[schema]' table=users`). No MCP server required.
+- **`:cli`** - context files show CLI syntax (e.g. `rails 'ai:tool[schema]' table=users`). No MCP server required. Every file follows it: the root files, the split rule files and OpenCode's per-directory `AGENTS.md`, whose tools rule files then describe the CLI tools.
+
+Every tool count and list in the generated files is the set the server serves: the built-in tools `skip_tools` leaves, plus `custom_tools`. A custom tool gets a row in the tools table with the first sentence of its description. A workflow step, rule or pointer whose tool is skipped is left out, or said without the tool (with `rails_get_context` skipped, the model workflow starts from `rails_get_model_details`), so no file sends the AI to a tool the server does not serve.
+
+The workflow examples name the app's own most connected model, one of its controllers, a template and a partial it renders. An app with none of one gets an obvious placeholder (`YourModel`, `shared/your_partial`) rather than a name that reads like the app's.
 
 The `tool_mode` is selected during `rails generate rails_ai_context:install`.
 
@@ -482,7 +495,7 @@ Returns all routes: HTTP verbs, paths, controller actions, route names.
 | `detail` | string | `summary` / `standard` (default) / `full` |
 | `limit` | integer | Max routes to return. Default: 150 (standard), 200 (full). |
 | `offset` | integer | Skip routes for pagination. Default: 0. |
-| `app_only` | boolean | Filter out internal Rails routes (Active Storage, Action Mailbox, Conductor, etc.). Default: true. |
+| `app_only` | boolean | Leave out the routes Rails' engines and gems draw on their own (Active Storage, Action Mailbox and its conductor, Turbo Native navigation, `rails/info`, `rails/mailers`, `rails/welcome`). The app's own declarations stay, `devise_for` and the health check included. A `controller` filter searches every route. Default: true. |
 
 **Examples:**
 
@@ -681,7 +694,7 @@ rails_get_edit_context(file: "app/controllers/posts_controller.rb", near: "def i
 
 ### rails_validate
 
-Validates syntax of multiple files at once (Ruby, ERB, JavaScript). Optionally runs Rails-aware semantic checks.
+Validates syntax of multiple files at once (Ruby, ERB, JavaScript). Optionally runs Rails-aware semantic checks. JavaScript needs `node` on the PATH; without it a file whose brackets balance is listed as skipped, not as OK.
 
 **Parameters:**
 
@@ -714,10 +727,10 @@ Ripgrep-powered regex search across the codebase.
 
 | Param | Type | Description |
 |-------|------|-------------|
-| `pattern` | string | **Required.** Regex pattern or method name to search for. |
+| `pattern` | string | **Required.** Regex pattern or method name 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 to search in (e.g. `app/models`, `config`). Default: entire app. |
 | `file_type` | string | Filter by file extension (e.g. `rb`, `erb`, `js`). Alphanumeric only. |
-| `match_type` | string | `any` (default), `definition` (def lines), `class` (class/module lines), `call` (call sites only), `trace` (**full picture** - definition with class context + source code + internal calls + sibling methods + callers with route chain + test coverage separated). |
+| `match_type` | string | `any` (default), `definition` (def lines whose method name contains the pattern), `class` (class/module lines whose name contains it), `call` (call sites only), `trace` (**full picture** - definition with class context + source code + internal calls + sibling methods + callers with route chain + test coverage separated). |
 | `exact_match` | boolean | Match the pattern literally, whole-word where its edges are word characters. `def reblog?` does not match `def reblog`. Default: false. |
 | `exclude_tests` | boolean | Exclude test/spec/features directories. Default: false. |
 | `group_by_file` | boolean | Group results by file with match counts. Default: false. |
@@ -725,7 +738,7 @@ Ripgrep-powered regex search across the codebase.
 | `limit` | integer | Max lines to return; the default is sized in matches. |
 | `context_lines` | integer | Lines of context before and after each match (like grep -C). Default: 2, max: 5. |
 
-Smart result limiting, sized in matches: under 10 shows all, 10-100 shows half, over 100 caps at 100. `offset` and `limit` count emitted lines, so a search with context returns more lines than matches. The header says how many matches were found, how many the page shows, and whether the line cap was reached. Once it names the cap, the count covers only the lines it scanned, so it is written `N+`.
+Smart result limiting, sized in matches: under 10 shows all, 10-100 shows half, over 100 caps at 100. `offset` and `limit` count emitted lines, so a search with context returns more lines than matches. The header says how many matches were found, how many the page shows, and whether the line cap was reached. 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. Once it names the cap, the count covers only the lines it scanned, so it is written `N+`.
 
 **Examples:**
 
@@ -735,7 +748,8 @@ rails_search_code(pattern: "publishable?", match_type: "trace")
     + sibling methods + app callers with route chain + test coverage (separated)
 
 rails_search_code(pattern: "create", match_type: "definition")
-  → Only `def create` / `def self.create` lines
+  → Only def lines whose name contains `create`: `def create`, `def self.create`,
+    `def recreate`; add exact_match: true for `def create` alone
 
 rails_search_code(pattern: "publishable", match_type: "call")
   → Only call sites (excludes the definition)
@@ -749,14 +763,14 @@ rails_search_code(pattern: "has_many", group_by_file: true)
 rails_search_code(pattern: "post", exclude_tests: true)
   → Skip test/spec directories
 
-rails_search_code(pattern: "activate", match_type: "definition")
-  → Only `def activate` / `def self.activate` lines (skips method calls)
+rails_search_code(pattern: "generate_.*", match_type: "definition")
+  → Only def lines whose name matches the regex (skips method calls)
 
-rails_search_code(pattern: "User", match_type: "class")
-  → Only `class User` / `module User` definitions
+rails_search_code(pattern: "\\w+Job", match_type: "class")
+  → Only class/module definitions whose name matches the regex
 ```
 
-**Security:** Uses `Open3.capture3` with array arguments (no shell injection). Validates file_type. Blocks path traversal. Respects `excluded_paths` and `sensitive_patterns` config on both backends, and the Ruby fallback reads the ignore files ripgrep reads and ranks them the way ripgrep does: `.rgignore` over `.ignore` over `.gitignore` (each scoped to its own directory) over `.git/info/exclude` over the global excludes file, the file type deciding before depth, which breaks ties only within one type; `.ignore` and `.rgignore` apply outside a git repository too, and a directory the rules ignore is never entered. As ripgrep does, the fallback also reads the ignore files of every directory above the app, the git ones only as far up as the nearest `.git` (a file for a worktree or submodule), so an app nested in a larger repository gets that repository's rules and a repository nested in the app stops the app's `.gitignore`. Patterns match case-sensitively, symlinks are not followed, and a file with a NUL byte in its first 64 KiB is skipped unread, all as in ripgrep, so the two return the same set.
+**Security:** Uses `Open3.capture3` with array arguments (no shell injection). Validates file_type. Blocks path traversal. Respects `excluded_paths` and `sensitive_patterns` config on both backends, and the Ruby fallback reads the ignore files ripgrep reads and ranks them the way ripgrep does: `.rgignore` over `.ignore` over `.gitignore` (each scoped to its own directory) over `.git/info/exclude` over the global excludes file, the file type deciding before depth, which breaks ties only within one type; `.ignore` and `.rgignore` apply outside a git repository too, and a directory the rules ignore is never entered. As ripgrep does, the fallback also reads the ignore files of every directory above the app, the git ones only as far up as the nearest `.git` (a file for a worktree or submodule), so an app nested in a larger repository gets that repository's rules and a repository nested in the app stops the app's `.gitignore`. Patterns match case-sensitively, symlinks are not followed but for a directory linked in from the app's git repository, which both search under the app's name for it, and a file with a NUL byte in its first 64 KiB is skipped unread, all as in ripgrep, so the two return the same set.
 
 ### rails_analyze_feature
 
@@ -786,7 +800,7 @@ rails_analyze_feature(feature: "orders")
   → Everything related to orders across all layers
 ```
 
-**Returns:** Markdown with sections for Models (with columns, associations, validations, scopes, enums), Controllers (with actions and filters), Routes, Services (with methods), Jobs (with queue/retry), Views (with partials and Stimulus refs), Stimulus controllers (with targets/values/actions), Tests (with counts), Related models, Concerns, Callbacks, Channels, Mailers, and Environment dependencies. Each section shows match counts.
+**Returns:** Markdown with sections for Models (with columns, associations, validations, scopes, enums), Controllers (with actions and filters), Routes, Services (with their public methods and the files that call them), Jobs and Sidekiq workers (with queue/retry), Views (with partials and Stimulus refs), Stimulus controllers (with targets/values/actions), Tests (with counts), Related models, Concerns, Callbacks, Channels, Mailers, and Environment dependencies. Each section shows match counts.
 
 ### rails_security_scan
 
@@ -841,7 +855,7 @@ rails_get_concern(type: "model")
   → Lists only model concerns from app/models/concerns/
 ```
 
-**Returns:** Concern listing or full detail including file path, line count, included/extended modules, macros and DSL usage, public methods, class methods, callbacks, and a list of models or controllers that include the concern. Cross-references to related model/controller tools.
+**Returns:** Concern listing or full detail including file path, line count, included/extended modules (a conditional include with its condition), macros and DSL usage (`helper_method` included), public methods, class methods, private methods, callbacks, and a list of models or controllers that include the concern. The listing counts private methods apart from public ones. Cross-references to related model/controller tools.
 
 ### rails_get_callbacks
 
@@ -873,7 +887,9 @@ Within one type the order is the order Rails runs them, base classes first, a
 `before_` or `around_` callback with `prepend: true` first, and
 `after_commit`/`after_rollback` last declared first unless the app runs them in
 order (`load_defaults 7.1`). A method declared again shows once with the later
-declaration's conditions.
+declaration's conditions. A block or lambda callback shows its declaration at
+`detail: "full"`, and turbo-rails' broadcast macros (`broadcasts_refreshes`,
+`broadcasts_to` and the rest) are listed as the commit callbacks they declare.
 
 ### rails_get_helper_methods
 
@@ -1104,7 +1120,7 @@ The legacy `rails://models/{name}` form is still accepted.
 
 ### Dynamic Resource Templates (VFS)
 
-Live resources introspected fresh on every request - zero stale data:
+Live resources introspected afresh on every request, after the app's code is reloaded for any edit:
 
 | Resource Template | Description |
 |-------------------|-------------|
@@ -1138,7 +1154,11 @@ The install generator (or `rails-ai-context init`) creates per-tool MCP config f
 | OpenCode | `opencode.json` | `mcp` | JSON |
 | Codex CLI | `.codex/config.toml` | `[mcp_servers]` | TOML |
 
-Each file is merge-safe - only the `rails-ai-context` entry is managed, other servers are preserved. When the gem is not in the app's `Gemfile.lock` (standalone install) the entry runs `rails-ai-context serve` with no `bundle exec`.
+Each file is merge-safe - only the `rails-ai-context` entries are managed, other servers are preserved. When the gem is not in the app's `Gemfile.lock` (standalone install) the entry runs `rails-ai-context serve` with no `bundle exec`.
+
+On Windows every entry starts the server through `cmd /c`: `"command": "cmd", "args": ["/c", "bundle", "exec", "rails-ai-context", "serve"]` (OpenCode: `"command": ["cmd", "/c", ...]`; Codex: `command = "cmd"`). A gem's executables there are batch files (`bundle.bat`, `rails-ai-context.bat`), which Claude Code, Codex and the other clients that start a server without a shell do not run. An entry written on Windows does not start on macOS or Linux, and one written there may not start on Windows: `doctor` names either, and running the install again rewrites it for the machine it runs on. A team on both keeps the MCP configs out of git, or runs the install on each machine.
+
+A folder of apps gets one entry per app instead, `rails-ai-context-<app folder>`, each pointed at its app with `--app-path` and announcing its app first through `RAILS_AI_CONTEXT_SERVER_NAME`; see [`init`](CLI.md#init-standalone-only) for the shape each AI tool gets.
 
 **Example: `.mcp.json` (Claude Code)**
 ```json
@@ -1177,6 +1197,9 @@ claude mcp add rails-ai-context -- bundle exec rails ai:serve
 
 # Standalone
 claude mcp add rails-ai-context -- rails-ai-context serve
+
+# On Windows, through cmd /c
+claude mcp add rails-ai-context -- cmd /c bundle exec rails-ai-context serve
 ```
 
 ### Claude Desktop
@@ -1195,7 +1218,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 }
 ```
 
-Or for standalone: replace `"command": "bundle"` / `"args": ["exec", "rails-ai-context", "serve"]` with `"command": "rails-ai-context"` / `"args": ["serve"]`.
+Or for standalone: replace `"command": "bundle"` / `"args": ["exec", "rails-ai-context", "serve"]` with `"command": "rails-ai-context"` / `"args": ["serve"]`. On Windows, start either through `cmd /c`: `"command": "cmd"`, with `"/c"` ahead of the rest of the args.
 
 ### Cursor
 
@@ -1232,12 +1255,12 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
   RailsAiContext.configure do |config|
     config.auto_mount = true
     config.http_path  = "/mcp"       # default
-    config.http_port  = 6029          # default
-    config.http_bind  = "127.0.0.1"  # default (localhost only)
   end
 end
 ```
 
+The endpoint is then served by your app's own server, on its address and port; `http_bind` and `http_port` configure only the standalone process.
+
 Both transports are **read-only** - they expose the same 45 tools and never modify your app.
 
 ### Controller Transport (Alternative)
@@ -1246,10 +1269,14 @@ For tighter Rails integration (authentication, routing, middleware stack), mount
 
 ```ruby
 # config/routes.rb
-mount RailsAiContext::Engine, at: "/mcp"
+mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
 ```
 
-This provides a native Rails controller (`RailsAiContext::McpController`) that delegates to the Streamable HTTP transport.
+The `if` keeps the routes file loading wherever the gem is not: in production, where Bundler skips the `:development` group, and after the gem is removed. An unguarded mount raises `uninitialized constant RailsAiContext::Engine` there, and the app does not boot.
+
+This provides a native Rails controller (`RailsAiContext::McpController`) that delegates to the Streamable HTTP transport. Outside development and test (production, staging) it refuses every request with a 403, as `auto_mount` does, unless you set `config.allow_http_in_production = true`; see [Security](SECURITY.md#mcp-http-transport).
+
+The controller runs each call on the request's own thread and sends the answer whole, which keeps calls answering while the app reloads code in development. A custom tool's progress or log notifications therefore arrive together with its answer, and a request a tool makes of the client mid-call (sampling, elicitation, roots) fails at once; stdio and the standalone HTTP server deliver both as they are sent ([Setup](SETUP.md#http-transport-alternative)).
 
 ---
 
@@ -1370,6 +1397,8 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
 
     # Auto-mount Rack middleware for HTTP MCP
     config.auto_mount = false
+    # Let the mounted engine and auto_mount answer in production
+    config.allow_http_in_production = false
     config.http_path  = "/mcp"
     config.http_bind  = "127.0.0.1"
     config.http_port  = 6029
@@ -1384,7 +1413,7 @@ end
 | `preset` | Symbol | `:full` | Introspector preset (`:full` or `:standard`) |
 | `introspectors` | Array | 40 (full preset) | Which introspectors to run |
 | `context_mode` | Symbol | `:compact` | `:compact` or `:full` |
-| `claude_max_lines` | Integer | `150` | Max non-blank lines in a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, data lines are cut and the Commands, Warnings, Rules and MCP-tools sections kept whole |
+| `claude_max_lines` | Integer | `150` | Budget for the non-blank lines of a compact context file's gem-managed block, the `<!-- BEGIN/END rails-ai-context -->` markers included. Over budget, the data sections (Stack, Key models, Gems, Architecture) are cut first, down to none; the title and the Commands, Warnings, Rules and Tools sections are never cut, so they set the smallest file a budget can give (about 110 lines with the anti-hallucination protocol) |
 | `max_tool_response_chars` | Integer | `200_000` | Safety cap for MCP tool responses and resource payloads |
 | `cache_ttl` | Integer | `60` | Cache TTL in seconds for introspection results |
 | `custom_tools` | Array | `[]` | Additional MCP tool classes to register alongside built-in tools |
@@ -1394,14 +1423,15 @@ end
 | `excluded_models` | Array | internal Rails models | Models to skip |
 | `excluded_paths` | Array | `node_modules tmp log vendor .git doc docs` | Paths excluded from code search |
 | `sensitive_patterns` | Array | `.env`, `.key`, `.pem`, credentials | File patterns blocked from search and read tools |
-| `output_dir` | String | `nil` (Rails.root) | Where to write context files |
+| `output_dir` | String | `nil` (Rails.root) | Where to write context files. OpenCode's `app/models/AGENTS.md` and `app/controllers/AGENTS.md` are written only where that directory exists under it |
 | `auto_mount` | Boolean | `false` | Auto-mount HTTP MCP endpoint |
-| `http_path` | String | `"/mcp"` | HTTP endpoint path |
-| `http_bind` | String | `"127.0.0.1"` | HTTP bind address |
-| `http_port` | Integer | `6029` | HTTP server port |
+| `allow_http_in_production` | Boolean | `false` | Let the mounted engine and `auto_mount` answer in production and every other environment but development and test. Off, they refuse there with a 403. See [Security](SECURITY.md#mcp-http-transport) |
+| `http_path` | String | `"/mcp"` | HTTP endpoint path (`auto_mount` and the standalone server) |
+| `http_bind` | String | `"127.0.0.1"` | Address the standalone HTTP server binds. Another address still answers only a loopback `Host` header; see [CONFIGURATION](CONFIGURATION.md#mcp-server) |
+| `http_port` | Integer | `6029` | Port of the standalone HTTP server |
 | `live_reload` | Symbol/Boolean | `:auto` | `:auto`, `true`, or `false` - enable MCP live reload |
 | `live_reload_debounce` | Float | `1.5` | Debounce interval in seconds for live reload |
-| `server_name` | String | `"rails-ai-context"` | MCP server name |
+| `server_name` | String | `"rails-ai-context"` | The MCP server name the server announces. When it is left at the default, the `RAILS_AI_CONTEXT_SERVER_NAME` environment variable takes its place for one process, which is how a workspace's entries announce their app |
 | `server_version` | String | gem version | MCP server version. Read-only, there is no setter |
 | `generate_root_files` | Boolean | `true` | Set `false` to generate split rules only: no CLAUDE.md, AGENTS.md, .cursorrules or copilot-instructions.md (`.ai-context.json` is still written) |
 | `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule Anti-Hallucination Protocol in generated context files - set `false` to skip |
@@ -1415,7 +1445,7 @@ end
 | `max_search_results` | Integer | `200` | Max lines a search may emit per call, matches and context together |
 | `max_validate_files` | Integer | `50` | Max files per validate call |
 | `excluded_controllers` | Array | `DeviseController`, etc. | Controller classes hidden from listings |
-| `excluded_route_prefixes` | Array | `action_mailbox/`, `active_storage/`, etc. | Route controller prefixes hidden with `app_only` |
+| `excluded_route_prefixes` | Array | `action_mailbox/`, `active_storage/`, `rails/conductor/`, `rails/info`, `rails/mailers`, `rails/welcome`, `turbo/` | Route controller prefixes hidden with `app_only`: the routes Rails' engines and gems draw on their own |
 | `excluded_association_names` | Array | 7 framework associations | Framework association names hidden from model output |
 | `excluded_concerns` | Array of Regex or String | framework regex patterns | Patterns for concerns to hide. A YAML list replaces the framework defaults; the initializer's `+=` adds to them |
 | `excluded_filters` | Array | `verify_authenticity_token`, etc. | Framework filter names hidden from controller output |
@@ -1427,7 +1457,7 @@ end
 | `extra_app_paths` | Array | `[]` | More app-root-relative directories that hold Rails app code. Each one's `app/models`, `app/controllers` and `app/views` are scanned |
 | `query_timeout` | Integer | `5` | `rails_query` statement timeout in seconds |
 | `query_row_limit` | Integer | `100` | Max rows `rails_query` returns (1 to 1000) |
-| `query_redacted_columns` | Array | `password_digest`, `encrypted_password`, tokens, etc. | Column names whose values `rails_query` redacts |
+| `query_redacted_columns` | Array | `password_digest`, `encrypted_password`, tokens, etc. | Column names `rails_query` refuses: a query naming one is rejected before it runs, and a returned column of that name comes back `[FILTERED]` |
 | `query_allowed_columns` | Array | `[]` | Column names to exempt from the built-in sensitive list |
 | `allow_query_in_production` | Boolean | `false` | Allow `rails_query` in production |
 | `log_lines` | Integer | `50` | Default number of lines `rails_read_logs` tails |
@@ -1462,7 +1492,7 @@ Core Rails structure only. Use `config.preset = :standard` for a lighter footpri
 | Introspector | What it discovers |
 |-------------|-------------------|
 | `schema` | Tables, columns, types, indexes, foreign keys, primary keys. Falls back to `db/schema.rb` parsing when no DB connected. |
-| `models` | Associations, validations, scopes, enums, callbacks, concerns, instance methods, class methods. Source-level macros via Prism AST (single-pass, 8 listeners): `has_secure_password`, `encrypts`, `normalizes`, `delegate`, `serialize`, `store`, `generates_token_for`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `broadcasts_to`. Every result tagged `[VERIFIED]` or `[INFERRED]`. |
+| `models` | Associations, validations, scopes, enums, callbacks, concerns, instance methods, class methods. Source-level macros via Prism AST (single-pass, 8 listeners): `has_secure_password`, `encrypts`, `normalizes`, `delegate`, `serialize`, `store`, `generates_token_for`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `broadcasts`, `broadcasts_to`, `broadcasts_refreshes`, `broadcasts_refreshes_to`. Every result tagged `[VERIFIED]` or `[INFERRED]`. |
 | `routes` | All routes with HTTP verbs, paths, controller actions, route names, API namespaces, mounted engines. |
 | `jobs` | ActiveJob classes with queue names. Mailers with action methods. Action Cable channels. |
 | `gems` | 127 notable gems categorized: auth, jobs, frontend, api, database, files, testing, deploy, monitoring, admin, pagination, search, forms, server, notifications, validation, utilities, services, payments. |
@@ -1650,33 +1680,34 @@ config.introspectors += %i[api]
 rails ai:doctor
 ```
 
-Runs up to 25 checks and reports an AI readiness score (0-100). A check that does not apply to the app prints no row:
+Runs the checks below and reports an AI readiness score (0-100). A check that does not apply to the app prints no row:
 
 | Check | What it verifies |
 |-------|------------------|
 | Schema | A schema dump file exists |
-| Pending migrations | No migration is pending (fails when one is) |
-| Models | Model files detected |
+| Pending migrations | No migration is pending in any database the app migrates, each read through its own connection as `db:migrate:status` reads it, and nothing written to it: a database never migrated gets no `schema_migrations` table from doctor (fails when one is pending) |
+| Database | Shown in place of Pending migrations when a database the app migrates does not exist (fix: `bin/rails db:prepare`) or its server does not answer (fails). A SQLite database whose file is not there is named without connecting to it, since connecting would create an empty one |
+| Models | Model files detected where the tools read them: `app/models`, packs and in-repo engines, and in an engine's `test/dummy` the engine's own |
 | Routes | `config/routes.rb` exists |
-| Gems | The lockfile exists |
-| Controllers | Controller files detected |
-| Views | Files exist under `app/views` |
-| Tests | A test suite is found |
-| Migrations | Migration files exist |
-| Context files | Generated context files exist and are newer than the code they describe. No row on an MCP-only install |
+| Gems | The app's lockfile exists, or the one its `config/boot.rb` names (a monorepo's shared bundle, an engine's for its `test/dummy`) |
+| Controllers | Controller files detected, read as Models are |
+| Views | Files exist where the tools read views: `app/views`, packs, and in an engine's `test/dummy` the engine's |
+| Tests | A test suite is found: the app's, or in an engine's `test/dummy` the engine's |
+| Migrations | Migration files exist, counted over every database the app migrates, and in an engine's `test/dummy` the engine's own |
+| Context files | Generated context files exist where `config.output_dir` puts them, and a context run would leave them as they are. A file a run would rewrite, because an older version of the gem wrote it or the app changed under it, is named; a file that is only older than the code is not. In an engine's dummy app the install at the engine's root is read, and its own context command runs there, into a copy. No row on an MCP-only install |
 | Initializer guard | Shown only when `config/initializers/rails_ai_context.rb` has no guard, or guards on `defined?(RailsAiContext)` alone |
-| MCP configs | Each selected tool's MCP config file exists and parses. Skipped in CLI-only mode |
-| Codex env snapshot | The `GEM_HOME` saved in `.codex/config.toml` still exists. Only when Codex is selected |
-| MCP server | MCP server can be built |
+| MCP configs | Each selected tool's MCP config file exists, parses, and holds a rails-ai-context server whose command can start: `bundle exec` only where the app's lockfile carries the gem and the bundle's copy has its executable, the `rails-ai-context` binary only where it is on PATH, and a warning when a config runs that binary in an app whose bundle carries the gem. The command is looked up, never run. Skipped in CLI-only mode |
+| Codex env snapshot | The `PATH` saved in `.codex/config.toml` (the app's, or a folder of apps' above it) still reaches each server's command, and a saved `GEM_HOME`, and every directory on a saved `GEM_PATH`, still exists - one missing from `GEM_PATH` passes when the shell's own `GEM_PATH` names it too, since RubyGems passes over it and the install would save it again. Only when Codex is selected |
+| MCP server | MCP server can be built, with an `mcp` gem this gem supports (warns, as the boot does, when the app's bundle pins one outside that range) |
 | Introspector health | Every configured introspector returns data |
 | Preset coverage | The preset covers the features the app has |
 | ripgrep | `rg` binary installed (optional, falls back to Ruby) |
-| Prism parser | Prism is available for AST-based validation |
-| Brakeman | Brakeman is available for `rails_security_scan` (optional) |
+| Prism parser | Prism is available for AST-based validation, at a version this gem supports (warns, as the boot does, when the app's bundle pins one below it) |
+| Brakeman | Brakeman is available for `rails_security_scan` (optional): in the app's bundle, or installed on the machine, where the scan runs the gem's own script as a process of its own. Doctor runs that script's `--version` the way the scan runs it, and warns, with what it printed, when it does not answer |
 | Live reload | `listen` gem installed (optional, enables MCP live reload) |
-| MCP stdio hygiene | On a standalone install, gem activation prints nothing on stdout |
-| Secrets in .gitignore | Sensitive files that exist are gitignored |
-| MCP auto_mount | `auto_mount` is not on in production |
+| MCP stdio hygiene | On a standalone install, or where a config starts the `rails-ai-context` binary itself, gem activation prints nothing on stdout |
+| Secrets in .gitignore | Secret files that exist are gitignored and not committed: `config/master.key`, `config/credentials/*.key`, every `.env` file, `config/application.yml`, the Codex config and SSH and cloud credentials (fails when one is not ignored, or is committed: the fix is `git rm --cached` and rotating it). `config/database.yml`, `cable.yml`, `storage.yml` and the like warn only when they hold a password, token or key as a literal value. The encrypted `credentials.yml.enc` is committed by design and never reported. Inside a git repository git answers, so a rule in a `.gitignore` above the app (a monorepo's), in `.git/info/exclude` or in the global excludes counts; outside one the app's `.gitignore` is read |
+| MCP HTTP endpoint | `allow_http_in_production` is off, so the mounted engine and `auto_mount` refuse outside development and test; on, it warns, and with `auto_mount` it fails |
 | Schema file size | The schema file is under 80% of `max_schema_file_size` |
 | View aggregation size | `app/views` templates total under 80% of `max_view_total_size` |
 
@@ -1699,23 +1730,32 @@ Requires the `listen` gem:
 gem "listen", group: :development
 ```
 
+The standalone binary's `rails-ai-context watch` also finds a `listen` installed with `gem install listen`, the way it finds its own dependencies outside the app's bundle; a `listen` the app's bundle locks still wins.
+
 Watches for changes in: `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`, plus the app directories of packs, in-repo engines and `extra_app_paths`, and regenerates only the files that changed (diff-aware, skips unchanged files).
 
 ---
 
 ## Live Reload (MCP)
 
-When running the MCP server via `rails ai:serve`, **live reload** automatically invalidates tool caches and notifies connected AI clients when files change - so the AI always has fresh context without manual re-querying.
+When running the MCP server via `rails ai:serve`, **live reload** notifies connected AI clients when files change, so they know to re-query.
+
+Answers never wait on it. Every tool call and resource read first checks the watched files, with `listen` or without it (a new Rails 8 app does not bundle it), and when one changed it reloads the app's code and drops the caches - so an answer sees every edit made before the call began, one made a moment earlier included, which `listen` would deliver only after its debounce. The check stats each watched directory and file and reads a directory again only when it changed: about a millisecond on a small app, about 30 ms at 10,000 files. Calls made at the same time, over HTTP, wait for one check together; calls one after another each check.
+
+A server whose app cannot reload code - `RAILS_ENV=test`, or production with eager loading, where `config.enable_reloading` is off - keeps the code it booted with. What reflection reads, such as associations and enums, then stays as of boot (validations and callbacks are read off the source, so they still follow the edit), and once a file under the app's autoload paths changes, every answer ends with a note naming it: restart the server to see the edit.
+
+One save a reload can miss: Bootsnap's compile cache knows a Ruby file by its size and the second of its mtime, so a file saved twice within one second at the same size can reload as the first save. Every answer then names the file until it is saved again a second later ([Known limits](COMPATIBILITY.md#known-limits)).
 
 ### How it works
 
 1. A background thread watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/` and `spec/` (plus the app directories of packs, in-repo engines and `extra_app_paths`) for changes
 2. On change (debounced 1.5s), it checks the file fingerprint to avoid false positives
 3. If files truly changed, it:
-   - Clears all MCP tool caches
    - Sends `notifications/resources/list_changed` to the AI client
    - Logs a summary of what changed (e.g., "Files changed: 2 models, 1 controller.")
 
+The code reload and the cache drop are the calls' own: the first call after an edit makes them, on its own thread, when it checks the files. The watching thread loads none of the app's code.
+
 ### Setup
 
 Add the `listen` gem (you may already have it from Watch Mode):
@@ -1725,6 +1765,8 @@ Add the `listen` gem (you may already have it from Watch Mode):
 gem "listen", group: :development
 ```
 
+The standalone binary's `rails-ai-context serve` also finds a `listen` installed with `gem install listen`, as `watch` does; a `listen` the app's bundle locks still wins.
+
 Live reload is **enabled by default** when the `listen` gem is available. No configuration needed.
 
 ### Configuration
@@ -1784,7 +1826,7 @@ Works in:
 ### MCP server not detected by your AI tool
 
 1. Run `rails ai:doctor` - it checks per-tool MCP config files
-2. Verify the correct config file exists for your tool (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`)
+2. Verify the correct config file exists for your tool (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`) in the folder the tool opened: the app, or the folder of apps `init` set up
 3. Re-run install (`rails generate rails_ai_context:install` or `rails-ai-context init`) to regenerate configs
 4. Restart your AI tool
 
@@ -1833,6 +1875,10 @@ bundle add listen --group development
 
 # Then run
 rails ai:watch
+
+# Standalone install: no Gemfile change
+gem install listen
+rails-ai-context watch
 ```
 
 ### Tool responses show "not available"