rails-ai-context 5.32.2 → 5.33.0

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,15 @@ 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.
 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 +441,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