rails-ai-context 5.32.2 → 5.34.0

data/docs/CLI.md

@@ -40,6 +40,10 @@ rails-ai-context serve --transport http --port 6029   # HTTP transport
 | `--port` | `http_port` from config, else `6029` | HTTP listen port |
 | `--no-boot` | off | Skip booting the app; answer from source alone |
 
+Ctrl-C or SIGTERM stops the HTTP server and exits 0. Requests still running get 3 seconds, then Puma's own grace period of 5, before they are cut off, and the process exits within 15 seconds of the signal whatever else is still running.
+
+The server announces itself to the client as `server_name` from config, else `rails-ai-context`. The `RAILS_AI_CONTEXT_SERVER_NAME` environment variable takes the place of that default for one process; a `server_name` the app sets itself still wins. A [workspace](#init-standalone-only) entry sets the variable to put its app first, since VS Code names every tool after the announced name and keeps 13 characters of it.
+
 ### `tool`
 
 Run any of the 45 MCP tools from the terminal.
@@ -67,7 +71,18 @@ Global options may be typed before or after the command name:
 `rails-ai-context --app-path /srv/app doctor` and
 `rails-ai-context doctor --app-path /srv/app` run the same check.
 
-`--app-path` names the Rails root, and defaults to the working directory.
+`--app-path` names the Rails root, taken as given. Left out, every command
+that reads an app finds it the way `bin/rails` and Bundler do: the working
+directory if it is an app, else the nearest app root above it (a directory with
+`config/application.rb`, `config/environment.rb`, or a `bin/rails` that boots an
+app or an engine; never `$HOME`, `node_modules` or a gem install), else the one
+app a level or two below it - looked for everywhere but `/`, `$HOME` and the
+directories above it, which hold too much to search. A walk names the app it chose on stderr, as
+`[rails-ai-context] using app at a/`, so `serve` keeps stdout clean. A folder
+holding several apps is refused with one `--app-path` command per app, and
+`tool --list` there lists the tools without an app. The chosen root is the
+process's working directory for the rest of the run, so `init`, the config and
+every file written land in it.
 `--environment` names the `RAILS_ENV` to boot under. Left out, it resolves the
 way Rails resolves its own environment: the ambient `RAILS_ENV`, then
 `RACK_ENV`, then `development`, reading an empty value as unset. So an app
@@ -114,7 +129,13 @@ from source alone, which is what you want on a repo you have just cloned, on an
 app whose boot is broken, and in CI where booting costs more than the answer.
 
 The same tier is entered automatically when a boot fails, so you get an answer
-either way. Answers that need a running app are marked `[UNAVAILABLE: ...]`
+either way. A boot that hangs (an initializer waiting on a service that is
+down) counts as failed after `RAILS_AI_CONTEXT_BOOT_TIMEOUT` seconds: 20 for
+`serve` over stdio, whose client waits about 30 seconds for its first answer
+and then gives up, and 60 for every other command. Raise it for an app that
+is healthy but slow to boot, and for stdio also raise the client's own limit
+(Claude Code reads `MCP_TIMEOUT`, in milliseconds), or the client stops
+waiting first. Answers that need a running app are marked `[UNAVAILABLE: ...]`
 rather than guessed, and everything else is tagged `[STATIC]` instead of
 `[VERIFIED]`. `docs/COMPATIBILITY.md` lists which of the 40 introspectors answer
 in which tier.
@@ -161,6 +182,8 @@ rails-ai-context context --format claude # Specific format
 |:-------|:--------|:------------|
 | `--format` | all configured | `claude`, `cursor`, `copilot`, `opencode`, `codex`, `json`, `all` |
 
+Without `--format`, `rails ai:context` and `rails-ai-context context` also bring the selected tools' MCP configs up to date, in the command form the install takes now - after `bundle remove rails-ai-context` that is the bare binary. A tool whose config a [workspace](#init-standalone-only) above already serves is left to it. `rails ai:context:<tool>` writes that tool's config along with its files.
+
 The rake tasks `ai:context`, `ai:context:<format>` and `ai:context_for` also read
 `CONTEXT_MODE`: `CONTEXT_MODE=full rails ai:context` overrides `config.context_mode`
 for that run. The standalone binary does not read it.
@@ -176,7 +199,11 @@ rails-ai-context doctor --strict   # exit 1 when any check fails (CI gate)
 rails ai:doctor STRICT=1           # rake equivalent
 ```
 
-Checks include: schema existence, pending migrations, model files, routes, MCP config validity, introspector health, ripgrep availability, Prism gem, Brakeman gem, listen gem, gitignore security, auto_mount security, schema size, view count, and more.
+Checks include: schema existence, pending migrations in every database (and a database that does not exist or does not answer), model files, routes, whether the command each MCP config holds can start, the Codex env snapshot, whether a context run would rewrite the context files, introspector health, ripgrep availability, the Prism and mcp gems, Brakeman gem, listen gem, secret files and .gitignore, auto_mount security, schema size, view count, and more. The [Guide](GUIDE.md#diagnostics) lists every check.
+
+At a mountable engine's root, which boots no app of its own, `bundle exec rails-ai-context doctor` (or `rails-ai-context doctor` for a standalone install) diagnoses the dummy app the engine's `bin/rails` boots - `test/dummy` or `spec/dummy` - and reads the install at the engine's root: its `.rails-ai-context.yml`, MCP configs and context files, the ones an editor opened there uses. `bin/rails app:ai:doctor` reads them there too. Its fixes name the commands that run at the engine's root, such as `bundle exec rails-ai-context context`, and its context check runs that command into a copy of the files to see which it would rewrite.
+
+Every path the report names is named from where the command was typed, and every command a fix gives runs there. Typed in an app's parent folder (`rails-ai-context --app-path shop doctor`), the app's files are named `shop/...`, and a command of the app's goes there first: `rails-ai-context --app-path shop context`, `cd shop && bin/rails db:migrate`, `git -C shop rm --cached config/master.key`. A line for `.gitignore` names the app's own and is written the way that file reads it, from the app's root: Add to shop/.gitignore: `.env.local`. Typed in a folder inside the app (`app/models`), the report names the app's files from its root, as the app names them, while a fix still works where it was typed: `cd ../.. && bin/rails db:migrate`, `git -C ../.. rm --cached .env`, `rails-ai-context --app-path ../.. context`, and Add to ../../.gitignore: `.env`. `rails ai:doctor` reads that folder from the shell's `PWD`, since Rails' `rails` command and rake move up to the app's root before the task runs. Typed at an engine's root, the dummy app's files read `test/dummy/db/schema.rb` and the engine's own `Gemfile.lock` and `app/views`, a command of the engine's runs "at the engine's root" (`bundle install` there needs no folder), and one of the dummy app's goes to `test/dummy` first; typed inside `test/dummy`, the engine's files read `../../Gemfile.lock` and its commands run "in the engine at ../..". A fix that starts with `cd` leaves the shell in that folder, so type the next one from where doctor ran.
 
 ### `watch`
 
@@ -187,7 +214,7 @@ rails ai:watch
 rails-ai-context watch
 ```
 
-Requires the `listen` gem. Watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`.
+Requires the `listen` gem. `rails ai:watch` needs it in the app's Gemfile; the standalone binary uses the app's when its bundle locks one, and otherwise one installed with `gem install listen`. Watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`.
 
 ### `init` (standalone only)
 
@@ -198,7 +225,48 @@ rails-ai-context init
 rails-ai-context init --mcp-only   # MCP config only, no context files
 ```
 
-Asks which AI tools to configure and what to write: MCP config and context files, context files only (CLI mode), or MCP config only. Creates `.rails-ai-context.yml`, the MCP config files (except in CLI mode) and the context files (except with MCP config only). `--mcp-only` skips the second question.
+Asks which AI tools to configure and what to write: MCP config and context files, context files only (CLI mode), or MCP config only. Creates `.rails-ai-context.yml`, the MCP config files (except in CLI mode) and the context files (except with MCP config only). `--mcp-only` skips the second question. Every question - including a re-run's cleanup of dropped tools, and in CLI mode whether to take the gem's entries out of existing MCP configs - is asked before the app boots and anything is written; with MCP config only, the app is not booted at all.
+
+Run inside an app, `init` sets up that app (found the way every command finds it: the [app root](#tool) above a subdirectory, or the one `--app-path` names).
+
+Run in a folder that is no app but holds apps one or two levels down - a **workspace**, the folder an editor or agent is often opened at - it sets the folder up as a whole:
+
+```text
+work/                      <- run `rails-ai-context init` here
+  .mcp.json                   one server per app: rails-ai-context-api, rails-ai-context-web
+  .cursor/mcp.json ...        (every selected AI tool's MCP config, in the folder it reads)
+  api/  .rails-ai-context.yml, CLAUDE.md, ...   each app keeps its own config and context files
+  web/  .rails-ai-context.yml, CLAUDE.md, ...
+```
+
+The AI tools and the setup are asked once. Each app gets its own `.rails-ai-context.yml` and context files, because its server reads them from its own root; a child process generates them with the install that app's server will run. The folder's MCP configs get one server per app, because a client reads its project config from the folder it opened. Each entry is named `rails-ai-context-<app folder>` (the whole path where two apps share a folder name; a short hash where the name would pass 30 characters, since Cursor drops a tool whose server and tool names together pass 60) and points `--app-path` at its app:
+
+```json
+{
+  "mcpServers": {
+    "rails-ai-context-api": {
+      "command": "rails-ai-context",
+      "args": ["serve", "--app-path", "api"],
+      "env": { "RAILS_AI_CONTEXT_SERVER_NAME": "api-rails-ai-context" }
+    },
+    "rails-ai-context-web": {
+      "command": "bundle",
+      "args": ["exec", "rails-ai-context", "serve", "--app-path", "web"],
+      "env": { "BUNDLE_GEMFILE": "web/Gemfile", "RAILS_AI_CONTEXT_SERVER_NAME": "web-rails-ai-context" }
+    }
+  }
+}
+```
+
+- **Paths stay relative**, so a committed file means the same thing on every machine. Claude Code, Codex and OpenCode start a server in the folder they were launched in, so their configs name the app from the workspace (`api`). Cursor and VS Code have a name for the folder their config sits in, `${workspaceFolder}`, so their configs name the app from it (`${workspaceFolder}/api`); Cursor does not promise a working directory.
+- **The command form is each app's own**: the bare binary where the gem is not in the app's Gemfile.lock, `bundle exec` where it is, with `BUNDLE_GEMFILE` naming the Gemfile the app's bundle reads - its own (a linked one by the link's name, so its lockfile stays beside it), else the one its `config/boot.rb` names, as a monorepo's apps share one, else the one `bundle exec` run inside the app would find - since `bundle exec` started in the workspace would look for one there.
+- **`RAILS_AI_CONTEXT_SERVER_NAME` puts the app first** in the name the server announces. VS Code names every tool after that name and keeps 13 characters of it, so without it every app's tools would start `rails-ai-cont`. It is a variable rather than a flag so that an app whose bundle pins an older gem ignores it and starts.
+- A bare `rails-ai-context` entry left in the folder is replaced, since it would serve the folder itself, and so is an entry under a name the gem gives an app in this folder (its folder name or path) when that app's folder is gone, or the app now goes by another name because an app with the same folder name arrived. An entry named `rails-ai-context-...` that runs `rails-ai-context serve` is the gem's: dropping an AI tool removes it from that tool's config. One that runs no command, such as an HTTP entry of your own under either name, is left alone, and so is a second entry you named yourself for an app (`rails-ai-context-api-2` included), one that names its app through a variable the tool expands (`${userHome}`), and one naming an app outside the folder.
+- A config 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. Trailing commas, which VS Code's and OpenCode's take, are read under json 2.9 or later; Claude Code's `.mcp.json` and Cursor's `.cursor/mcp.json` are held to plain JSON, so a comment or trailing comma there is reported as one the client cannot read. An empty one is filled, and a byte order mark at the head of one stays.
+- `--app-path` naming a folder of apps sets that folder up the same way; every other command lists the apps below it.
+- An app whose bundle is not installed yet (a Gemfile and no lockfile) is served by this binary unless its Gemfile names the gem, or pulls gems in from other files (`eval_gemfile`, `gemspec`) that could.
+
+Start the client in the workspace folder. A client started inside one of the apps (Claude Code, Codex and OpenCode still read a config above it) runs each workspace server from there, where the relative path misses; the server says which folder the path was written for. To open an app on its own, run `init` inside it as well. `init` warns when an app declares a Ruby other than the one the workspace runs, since every server it starts runs under that one. `doctor` inside one of the apps finds the workspace's config one or two levels up.
 
 ### `version`
 
@@ -239,7 +307,8 @@ rails 'ai:preset[architecture]'
 ### `tree`
 
 Print a tree of every command. `rails-ai-context help <command>` lists that
-command's options.
+command's options, and so do `rails-ai-context <command> --help` and `-h`
+(after a tool's name, `--help` is that tool's: `tool schema --help`).
 
 ```bash
 rails-ai-context tree
@@ -306,6 +375,10 @@ rails-ai-context tool schema --table users --json
 JSON=1 rails 'ai:tool[schema]' table=users
 ```
 
+stdout then holds the envelope (`tool`, `output`, `error`) and nothing else.
+Whatever the app prints while it boots or while the tool runs - an
+initializer's `puts`, Sidekiq's Redis connection line - goes to stderr.
+
 ---
 
 ## Common workflows

data/docs/COMPATIBILITY.md

@@ -30,7 +30,11 @@ document is aspirational.
   quirks_mode` inside Rails itself. Rails 8.1 dropped the keyword and resolves
   json 3 cleanly. The test bundle pins `json < 3` below 8.1 for that reason; an
   app on those lines has the same choice to make, and it is between its own
-  Rails and json rather than anything here.
+  Rails and json rather than anything here. In such an app the stdio server
+  still works, because the gem writes its stdio replies with `JSON.generate`.
+  Over HTTP the MCP SDK serializes each reply with `to_json`, so every request
+  answers with a JSON-RPC error naming `unknown keyword: quirks_mode` until
+  the pair is fixed.
 
 The gemspec's `railties` bound is wider than the CI matrix: point releases inside
 7.0-8.1 and any future 8.x minor satisfy Bundler's constraint without a gem
@@ -60,6 +64,31 @@ Source: `.github/workflows/unit-matrix.yml`, which both `ci.yml` and
   a second run inside the matrix (Ruby 3.3 / Rails 8.0), since `release.yml`
   has no `lint` job of its own.
 
+### Operating systems
+
+Linux, macOS and Windows. CI runs the unit suite on Linux for every cell
+above, and on macOS (Ruby 3.4 / Rails 8.1 and Ruby 3.1 / Rails 7.0) and
+Windows (Ruby 3.4 / Rails 8.1). The E2E harness, which builds real apps and
+drives the CLI, the rake tasks and both transports, runs on Linux for six
+Ruby / Rails pairs and on macOS and Windows for Ruby 3.4 / Rails 8.1. A
+release waits for all of them.
+
+On Windows:
+
+- The MCP configs start the server through `cmd /c`, since a gem's
+  executables there are batch files that a client starting its server
+  without a shell does not run. See [GUIDE.md](GUIDE.md#mcp-server-setup)
+  for teams on both Windows and macOS or Linux.
+- `rails_query` on SQLite runs without its time limit: the limit runs the
+  query in a forked child, and Windows has no `fork`. The answer says so.
+- The pre-commit hook runs under the sh that Git for Windows runs hooks with.
+- A checkout whose lines end in CRLF, Git for Windows' default, is read and
+  written in them: `rails_search_code` ends a line before its CRLF, so `$`
+  anchors as it does on LF, and the context files' managed block and the
+  initializer's `config.ai_tools` line keep the file's own line endings.
+- ripgrep installs with `winget install BurntSushi.ripgrep.MSVC`; without it
+  `rails_search_code` takes the slower Ruby path.
+
 ### Rails 9
 
 Not supported, and the two install paths fail differently:
@@ -245,6 +274,25 @@ Proof sources:
    limit; the installer's cleanup on a small Rails 8.1 app holding hand-written
    rule files; and the unit suite on Ruby 3.1 with Rails 7.0 through Ruby 4.0
    with Rails 8.1.
+   In the v5.33.0 release QA: the release gem in a fresh app on Ruby 3.1 with
+   Rails 7.0 and 7.1, Ruby 3.2 with Rails 8.0, and Rails 8.1 on Ruby 3.3, 3.4
+   and 4.0, each through the standalone and in-Gemfile installs, the rake
+   tasks and all 45 tools over MCP stdio; a Rails 8.1 app reached through a
+   symlinked path, as macOS spells its temporary folders; a Rails 8.1 and a
+   Rails 7.0 app mounting the engine, six clients calling while a model
+   changed every 0.3 seconds; the pre-commit hook installed and run by real
+   commits in an app's own repository, a monorepo's folder and a submodule;
+   and the unit suite and the E2E harness on Linux, macOS and Windows.
+   In the v5.34.0 release QA: the 21 apps of the v5.33.0 acceptance run
+   (Mastodon, OpenProject, Discourse, Canvas, Forem, Whitehall, Consul, Open
+   Food Network, Diaspora, Errbit, Huginn, Plots2, a private app and the small
+   blogs), 11 booted and 10 static, their answers compared with v5.33.0's,
+   and their strong params and model tables compared again after the last
+   fix; a fresh Rails 8.1 and a fresh Rails 7.0 app through the install,
+   `ai:context` twice, `zeitwerk:check` with the engine mounted, MCP over the
+   mounted HTTP endpoint and stdio, and the standalone CLI; an app that loads
+   a gem before `bundler/setup`; and the unit suite and the E2E harness on
+   Linux, macOS and Windows.
 2. Non-crash coverage for every built-in tool including `get_view` in
    `spec/e2e/in_gemfile_install_spec.rb`'s full-tool sweep; output correctness
    (ivar cross-check, render-form detection, partial interfaces) verified
@@ -403,6 +451,32 @@ Postgres instance in `spec/e2e/postgres_install_spec.rb`, opt-in via
   under `config/initializers` adds with `Rails.application.routes.prepend` or
   `.append` are read, before and after the draw as Rails orders them. Routes Rails' own
   engines and gems draw into the app's table are read only with the app booted.
+- **A folder of apps is served from the folder.** `init` run in a folder of
+  apps writes entries that name each app relative to that folder, because
+  Claude Code, Codex and OpenCode start a server in the folder they were
+  launched in, and Cursor and VS Code expand `${workspaceFolder}`. A tool
+  launched inside one of the apps still reads the folder's config above it,
+  and its servers then start where the relative path misses. Every server in
+  the folder also runs under the Ruby the version manager picks in the folder,
+  so an app that declares another may answer from the static tier, and its
+  `bundle exec` entry may not start; `init` warns when it sees one.
+  `spec/e2e/workspace_install_spec.rb` starts each entry the way its tool does,
+  on a standalone and an in-Gemfile app. ADR-0005 records the per-tool facts.
+- **A file saved twice within one second at the same size can reload as the
+  first save.** Bootsnap's compile cache, which `config/boot.rb` sets up in a
+  new Rails app, knows a Ruby file by its size and the second of its mtime.
+  A file written again within that second at the same size gets the code
+  compiled from the earlier write back from it: on the reload the write sets
+  off, and in every process that loads the file after, the app's own server
+  and tests included, until the file is written in another second. Bootsnap
+  has no way to drop one entry, and the server does not touch the app's files
+  to move their stat, so a server that reloads code names such a file at the
+  end of every answer (under `_stale_code` in a JSON body), from the call
+  that sees the save until the file is saved again. What reflection reads,
+  such as associations and enums, may be the earlier save's meanwhile.
+  Saving the file again a second later puts the edit through, and
+  `DISABLE_BOOTSNAP_COMPILE_CACHE=1` in the server's environment turns the
+  compile cache off for that process.
 
 <br>
 

data/docs/CONFIGURATION.md

@@ -50,7 +50,7 @@ preset: full
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
 | `ai_tools` | Array of symbols | `nil` (all five) | Which AI tools to generate context for. Options: `:claude`, `:cursor`, `:copilot`, `:opencode`, `:codex`. Unset, it reads the selection the installer recorded, and all five when there is none |
-| `tool_mode` | Symbol | `:mcp` | `:mcp` (MCP server primary, CLI fallback) or `:cli` (CLI only, no MCP server) |
+| `tool_mode` | Symbol | `:mcp` | `:mcp` (MCP server primary, CLI fallback) or `:cli` (CLI only, no MCP server). Any other value is refused. Under `:cli` the tools' own next-step hints name the command (`rails-ai-context tool schema table=posts`, or the rake task when the gem is in the Gemfile) rather than an MCP call |
 | `context_files` | Boolean | `true` | Set `false` for MCP-only: the server and the CLI still answer, and no context file is written or touched |
 
 #### MCP only
@@ -86,25 +86,26 @@ empty list wrote every tool's files.
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
 | `preset` | Symbol | `:full` | `:full` (40 introspectors) or `:standard` (17 introspectors) |
-| `context_mode` | Symbol | `:compact` | `:compact` (context files capped at ~150 lines) or `:full` (no line cap) |
+| `context_mode` | Symbol | `:compact` | `:compact` (context files capped at ~150 lines) or `:full` (no line cap). Any other value is refused, and so is any other `CONTEXT_MODE` on a rake task |
 | `introspectors` | Array of symbols | (from preset) | Override the introspector list directly |
 | `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 verification protocol in generated context files |
-| `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. Must be positive |
+| `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). Must be positive |
 
 ### MCP Server
 
 | Option | Type | Default | Validation | Description |
 |:-------|:-----|:--------|:-----------|:------------|
-| `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 |
 | `cache_ttl` | Integer | `60` | Must be positive | Cache time-to-live in seconds |
 | `max_tool_response_chars` | Integer | `200_000` | Must be positive | Safety cap for tool responses and MCP resource payloads. An over-cap resource keeps its JSON shape: whole elements are dropped and reported under a `_truncated` key |
-| `live_reload` | Symbol/Boolean | `:auto` | - | `:auto` (uses `listen` gem if available), `true`, or `false` |
+| `live_reload` | Symbol/Boolean | `:auto` | - | `:auto` (uses `listen` gem if available), `true`, or `false`. The watch tells clients when files change; every server checks the app's files at each tool call either way, so its answers follow edits with or without it |
 | `live_reload_debounce` | Float | `1.5` | - | Seconds to wait before processing file changes |
 | `auto_mount` | Boolean | `false` | - | Auto-mount Rack middleware for HTTP transport |
-| `http_path` | String | `"/mcp"` | - | HTTP endpoint path |
-| `http_bind` | String | `"127.0.0.1"` | - | HTTP bind address |
-| `http_port` | Integer | `6029` | 1 to 65535 | HTTP listen 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 and a JSON-RPC error saying how to opt in. Every tool answers whoever reaches the endpoint, so set it only with the endpoint behind your app's authentication (see [SECURITY.md](SECURITY.md#mcp-http-transport)). The endpoint answers the hosts the app's `config.hosts` allows |
+| `http_path` | String | `"/mcp"` | - | HTTP endpoint path, for `auto_mount` and the standalone HTTP server (the engine answers where you mount it) |
+| `http_bind` | String | `"127.0.0.1"` | - | Address the standalone HTTP server (`serve --transport http`, `rails ai:serve_http`) binds. Another address opens the port to the network with no authentication, but the MCP SDK answers only requests whose `Host` header is `127.0.0.1`, `::1` or `localhost`: a client that uses the machine's IP or name gets 403 "Invalid Host header", and one that sends `Host: localhost` gets every tool. It suits a container whose port is published to the host. The engine and `auto_mount` use the app's own server and ignore it |
+| `http_port` | Integer | `6029` | 1 to 65535 | Port of the standalone HTTP server. The engine and `auto_mount` use the app's own server and ignore it |
 
 ### Cross-Tool Hydration
 
@@ -119,7 +120,7 @@ empty list wrote every tool's files.
 |:-------|:-----|:--------|:------------|
 | `excluded_models` | Array | 8 framework models | Models to skip during introspection |
 | `excluded_controllers` | Array | 2 framework controllers | Controllers to skip |
-| `excluded_route_prefixes` | Array | 6 framework prefixes | Route prefixes to skip |
+| `excluded_route_prefixes` | Array | 7 framework prefixes | Route controller prefixes `rails_get_routes` hides with `app_only`: the routes Rails' engines and gems draw on their own. A route the app's route files declare (`devise_for`, the health check) is not one |
 | `excluded_filters` | Array | 5 framework filters | Controller filters to skip |
 | `excluded_middleware` | Array | 25 framework middleware | Middleware to skip in listing |
 | `excluded_paths` | Array | `["node_modules", "tmp", "log", "vendor", ".git", "doc", "docs"]` | Paths excluded from search |
@@ -223,13 +224,31 @@ its exact name blocks it; see [SECURITY.md](SECURITY.md).
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
 | `custom_tools` | Array | `[]` | Additional MCP::Tool classes to register (initializer only - a class reference cannot be written in YAML) |
-| `skip_tools` | Array | `[]` | Built-in tool names to exclude (e.g., `%w[rails_security_scan]`) |
+| `skip_tools` | Array | `[]` | Built-in tool names to exclude (e.g., `%w[rails_security_scan]`). A skipped tool is left out of every list and of the `_Next:` hints other tools end with, and a call that names it anyway - from the CLI, rake or an MCP client - says it is turned off here |
 
 ### Output
 
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
-| `output_dir` | String | Rails.root | Directory for generated context files |
+| `output_dir` | String | Rails.root | Directory for generated context files. OpenCode reads `app/models/AGENTS.md` and `app/controllers/AGENTS.md` beside the code, so those two are written only where the directory exists under it, and named `no app/models under output_dir` otherwise |
+
+---
+
+## Environment variables
+
+Read from the environment of the process, so an MCP config sets them in its
+server entry's `env`.
+
+| Variable | Read by | Effect |
+|:---------|:--------|:-------|
+| `RAILS_AI_CONTEXT_BOOT_TIMEOUT` | Every command that boots the app, and the `ai:serve`, `ai:serve_http` and `ai:tool` rake tasks | Seconds a boot may take before it counts as failed; a command that can then answers from the static tier. Default 20 for `serve` over stdio and `rails ai:serve`, whose client waits about 30 seconds for its first answer, and 60 for everything else. A value that is not a whole number warns and keeps the default |
+| `RAILS_AI_CONTEXT_SERVER_NAME` | The MCP server | The name it announces for one process, in place of the default `server_name`; a `server_name` the app sets wins. A workspace's MCP entries set it |
+| `DEBUG` | Every command and the MCP server | Any value prints the backtrace of a failed boot, a failed command and an exception that escapes a tool, and names the errors a fallback swallows |
+| `RAILS_ENV`, `RACK_ENV` | Every command | The Rails environment to boot, read the way Rails reads it; `--environment` sets it for one command. Default `development` |
+| `JSON` | `rails 'ai:tool[NAME]'` | `JSON=1` prints the JSON envelope, as `--json` does |
+| `CONTEXT_MODE` | `rails ai:context`, `ai:context:<format>` and `ai:context_for` | `compact` or `full` for one run, in place of `config.context_mode`. Any other value stops the task |
+| `FORMAT` | `rails ai:context_for` | The format when the task is given none: `FORMAT=cursor rails ai:context_for`. Default `claude` |
+| `STRICT` | `rails ai:doctor` | `STRICT=1` (or `true`, `yes`) exits 1 when a check fails, as `doctor --strict` does |
 
 ---
 

data/docs/CUSTOM_TOOLS.md

@@ -80,7 +80,7 @@ if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
 end
 ```
 
-Custom tools appear alongside built-in tools in the MCP server and CLI.
+Custom tools appear alongside built-in tools in the MCP server and CLI, and in the tool counts and lists of the generated context files. The tools table gives a custom tool its own row, described by the first sentence of its `description`.
 
 Use the class *name* as a string: classes under `app/` (including
 `app/mcp_tools/`) are not autoloadable while initializers run, so a bare
@@ -216,6 +216,7 @@ end
 - Keep tools read-only when possible. MCP tools annotated as non-destructive build more trust with AI clients.
 - Return `MCP::Tool::Response` objects with `type: "text"` content blocks.
 - A response you build with `MCP::Tool::Response.new` is sent as written. The `config.max_tool_response_chars` cap (default: 200,000) is applied by the built-in tools' `text_response`, so keep a custom tool's output short yourself.
+- Through the mounted engine a call's answer is sent whole when the call is over. Progress and log notifications a tool sends (`server_context.report_progress`, `server_context.notify_log_message`) arrive together with its answer, and a request it makes of the client (sampling, elicitation, roots) fails at once, saying why. stdio and the standalone HTTP server deliver both as they are sent.
 
 ---
 

data/docs/FAQ.md

@@ -47,7 +47,11 @@ Yes. The gem gracefully degrades - it parses `db/schema.rb` as text when no data
 
 ### Can I switch between Gemfile and standalone?
 
-Yes, freely. Both generate identical context files and provide the same 45 tools. Just re-run the install/init to update MCP config files.
+Yes, freely. Both write the same context files and serve the same 45 tools; only the commands those files name follow the install (`rails ai:context` and `rails 'ai:tool[...]'` in the Gemfile, `rails-ai-context context` and `rails-ai-context tool ...` standalone). Re-run the install or `init` after switching: it updates the MCP config files and regenerates the context files with the new commands.
+
+### My editor opens a folder that holds several apps. Does that work?
+
+Yes. Run `rails-ai-context init` in that folder. It asks once, gives each app its own `.rails-ai-context.yml` and context files, and writes one MCP server per app into the folder's configs, `rails-ai-context-<app folder>`, so your AI tool sees every app and each app's tools are named after it. Start the tool in that folder: the entries name each app relative to it. See [`init`](CLI.md#init-standalone-only).
 
 ### Do I need to commit the generated files?
 
@@ -83,7 +87,7 @@ Start with `rails_onboard` for an app overview, `rails_analyze_feature` for feat
 
 ### Can I add my own tools?
 
-Yes. See [Custom Tools](CUSTOM_TOOLS.md). Create an `MCP::Tool` subclass, register it via `config.custom_tools`, and it appears alongside the 45 built-in tools.
+Yes. See [Custom Tools](CUSTOM_TOOLS.md). Create an `MCP::Tool` subclass, register it via `config.custom_tools`, and it appears alongside the 45 built-in tools, in the generated context files' tool counts and lists too.
 
 ### Can I remove built-in tools?
 
@@ -93,6 +97,8 @@ Yes. Use `config.skip_tools`:
 config.skip_tools = %w[rails_security_scan rails_query]
 ```
 
+The server, the CLI and the generated context files then leave them out alike, so no context file tells the AI to call a tool that answers "Unknown tool".
+
 ### What's the `detail` parameter?
 
 Individual lookup tools accept `detail`: `summary` (compact), `standard` (default), `full` (everything). Start with summary and drill down as needed. This keeps AI context windows lean. Composite tools (`rails_get_context`, `rails_analyze_feature`) do not accept `detail` - they always return their full bundled output.
@@ -172,15 +178,19 @@ Yes. Add content outside the `<!-- BEGIN/END rails-ai-context -->` markers. The
 
 ### Is introspection slow?
 
-Introspection results are cached with TTL (default: 60s) and fingerprint invalidation. The first call is slower; subsequent calls use cache. Prism AST parsing uses a single-pass Dispatcher - all 8 listeners run in one tree walk.
+Introspection results are cached with TTL (default: 60s) and fingerprint invalidation. The first call is slower; subsequent calls use cache until a watched file changes. Prism AST parsing uses a single-pass Dispatcher - all 8 listeners run in one tree walk.
 
 ### Does this affect my app's performance?
 
-No, as long as the gem sits in the Gemfile's `:development` group, where `bundle add rails-ai-context --group development` puts it: Bundler then never loads it in production. The gem itself does not check the environment, apart from `rails_query` refusing to run in production by default. Tools execute on demand (not continuously). The MCP server is a separate process (stdio), or an HTTP endpoint that exists only when you mount it or set `auto_mount`.
+No, as long as the gem sits in the Gemfile's `:development` group, where `bundle add rails-ai-context --group development` puts it: Bundler then never loads it in production. Where the gem is loaded in production, it refuses two things there by default: `rails_query`, and MCP over HTTP from inside the app (the mounted engine and `auto_mount`). Tools execute on demand (not continuously). The MCP server is a separate process (stdio), or an HTTP endpoint that exists only when you mount it or set `auto_mount`.
 
 ### How does live reload work?
 
-The `listen` gem watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`. When files change, caches are invalidated and MCP clients are notified. Debounce interval: 1.5s (configurable).
+The `listen` gem watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`, and when files change, MCP clients are notified. Debounce interval: 1.5s (configurable).
+
+Answers do not depend on it. Every tool call first checks those 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 a call sees an edit made a moment before it. The check costs about a millisecond on a small app and about 30 ms at 10,000 files.
+
+Under `RAILS_ENV=test`, or in production with eager loading, the app does not reload code, so what reflection reads (associations, enums) stays as it was at boot; once app code changes, every answer ends with a note naming the files, and a restart brings it up to date.
 
 ---
 
@@ -228,7 +238,7 @@ Those are AI coding interfaces. This gem is a data layer that makes *any* of the
 
 ### My AI tool doesn't see the MCP server
 
-Run `rails ai:doctor` - it checks MCP config files for all configured tools. See [Troubleshooting](TROUBLESHOOTING.md) for detailed steps.
+Run `rails ai:doctor` - it checks each configured tool's MCP config file, and whether the command it holds can start. See [Troubleshooting](TROUBLESHOOTING.md) for detailed steps.
 
 ### Tools return empty results