rails-ai-context 5.32.1 → 5.32.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da0f12372e58a903300979aa8be03f53f53e9d5de073709e549a47b46cb8a5eb
-  data.tar.gz: cc0b3c5e77840cef702e9e163bd3e2d73f24a56ec324fbdfe3ec5b8c6e58eaf7
+  metadata.gz: fac0badbc6cdd650df304ed443948b0d96190d77458caebca44b513642d28bd9
+  data.tar.gz: 52c14b40304a1fb7e475bfc8755e22954afd655d3e31607d08814c187bd5b05c
 SHA512:
-  metadata.gz: 5cc39f9e5208f88eea4ac18c3dac8a9abbe5da282c8a9b8f62594e5f9069483db9ced2f537768a97b864d17921b622ce7c640590e47546292fe3dafb5c7cd65e
-  data.tar.gz: 56d23208cbd739927ac9d85af26a39bfab5da0cebd75731791717bd67b83752bc28a096d1307e956ee9de593287b17efc70d91b81fa47c6deec2678beb064fd4
+  metadata.gz: 139928d253882921153d4f676aa7b7317efb5a4396dcbd4fc9d90ba8cc9abb5f513481b1534a22b18319c731f6b6a4e99fc1b21145daf03f0b980c2fc337c2cf
+  data.tar.gz: 122546a2d53a798334bb16f27886300eda3b76a958e3ded63f5f2814257bcbe69b568c585eefb0b81e4cf81d63525412fcef8acddd24ed45a4df1a588bebcbfe

data/CHANGELOG.md

@@ -5,6 +5,80 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.32.2] - 2026-10-07
+
+### Security
+
+- **`rails_query` runs the text its checks read.** The read-only validator
+  strips comments before it looks for blocked keywords, sensitive columns and
+  a second statement, but the query that ran was the raw input. The stripper
+  did not know string literals, so a `--` or `/*` inside a quoted string hid
+  the rest of the line from every check while the database still ran it: a
+  column such as `api_key` could be read through an alias, unredacted. Comments
+  are now taken out by a scanner that copies quoted strings and identifiers
+  whole, and the query that runs is the text it leaves, so the checks and the
+  database read the same thing.
+
+### Fixed
+
+- **The row limit holds whatever the query text looks like.** `LIMIT` was
+  appended after a trailing `-- note`, where the database read it as part of
+  the comment, and the first `LIMIT` anywhere in the text counted as the
+  query's own: one in a comment or a string literal left the query unlimited,
+  and one in a subquery was rewritten to the cap, which changed the answer.
+  Only a `LIMIT` or `FETCH FIRST` that ends the statement is the query's own
+  now, the appended one goes on its own line, and the answer is cut to the
+  limit after the database returns as well.
+- **A `#` no longer ends a PostgreSQL or SQLite query line.** A line starting
+  with `#>>`, `#>` or `#-` was dropped from the validated text as a MySQL
+  comment. Hash comments are read on MySQL only, where they can start anywhere
+  on a line.
+- **Dropping an AI tool on a re-run removes only what the gem generated.**
+  Answering yes to "Remove their generated files?" deleted the whole rules
+  directory and the whole root file, so a rule file written by hand in
+  `.claude/rules/`, and a `CLAUDE.md` the gem had never written to, went with
+  them. Cleanup now removes the rule files the gem names, the block between
+  its markers in a root file, and a split rules file it generated whole. It
+  leaves every other file and line, a symlink included, and says so when a
+  file kept the user's own content.
+- **`search_code` trace names the routes that reach the call.** A controller
+  caller's heading listed the controller's first two routes whatever action
+  the call was in, so a call inside `create` could read `GET /posts`. The
+  heading now lists the routes of the actions the calls sit in, and none when
+  the call is in a `before_action` line, a private or class method, or a
+  nested class.
+- **`rails-ai-context init` records the tool mode where it is read first.**
+  It wrote `tool_mode` to `.rails-ai-context.yml` only, and an initializer that
+  already set `config.tool_mode` won on read, so choosing CLI mode changed
+  nothing in such an app. It now updates the initializer line too, as it does
+  for the tool selection. An assignment written in another shape, such as one
+  read from `ENV`, is left alone and no second line is added beside it; the
+  same now holds for `config.context_files`.
+- **`--defaults` on the install generator asks nothing.** The legacy-files
+  question still waited for an answer on a terminal.
+- **`rails-ai-context init --mcp-only` no longer asks about legacy rule
+  files**, matching the generator.
+- **`rails_get_gems` filters by every category it prints.** The `category`
+  parameter accepted 8 of the 19 categories, so `monitoring`, `admin`,
+  `payments` and the rest could not be asked for.
+- **A composed answer carries the static tier banner once.** `rails_get_context`
+  repeated it for each tool the answer was built from.
+- **`rails_ai_context/test_helper` loads the MCP SDK.** A spec for a custom
+  tool raised `uninitialized constant MCP` when the helper was the first thing
+  the suite required.
+- **Descriptions say what the code does.** `rails_dependency_graph` no longer
+  claims services and controllers, `rails_get_concern` no longer promises a
+  `summary` level that differs from `standard`, `rails ai:context:codex` no
+  longer says it writes `.codex/config.toml`, and `init --help` no longer names
+  `.mcp.json` as the one MCP config.
+
+- **The docs say what the code does.** They were checked against the code,
+  line by line. The install steps
+  are listed in full in the guide, MCP config samples show the command the
+  installer writes, every tool's parameters match its schema, and counts,
+  defaults and error messages are the ones the code has. `rails ai:setup`,
+  which was documented and never existed, is gone from the CLI reference.
+
 ## [5.32.1] - 2026-10-06
 
 ### Fixed

data/CONTEXT.md

@@ -6,7 +6,7 @@ Terms this project uses in a narrower sense than everyday English. One entry per
 
 Overloaded. Always qualify it; never use "environment" bare in a tool name, an introspector name, or a config key.
 
-**Process environment** - the environment variables a running app sees, plus the places they are declared (`ENV[]` call sites, `.env.example`, Dockerfile, credentials keys). Served by `rails_get_env`, read by `EnvIntrospector`.
+**Process environment** - the environment variables a running app sees, plus the places they are declared (`ENV[]` call sites, `.env.example`, Dockerfile, credentials keys). Served by `rails_get_env`: `EnvIntrospector` reads the variables and the `ENV[]` call sites, and the tool reads the other places itself.
 
 **Environment config** - what `config/environments/*.rb` declares per environment: the assigned `config.*` keys and the values of the notable toggles. Served by `rails_get_env_config`, read by `EnvConfigIntrospector`.
 
@@ -18,7 +18,7 @@ The assistant a user points at their app: claude, cursor, copilot, opencode, cod
 
 Avoid "format" for either sense - claude is not a file format, and the word collides with real formatting elsewhere in the code. The public config key `ai_tools` already uses the canonical term.
 
-`Install::AiTool` is the one table of what each means: name, context files, MCP config shape, legacy leftovers. `Install::SelectionRecord` owns which ones the user picked - written to YAML always and to the initializer line inside a Rails app, read initializer-first because that is the file a user hand-edits.
+`Install::AiTool` is the one table of what each means: name, context files, MCP config shape, legacy leftovers. `Install::SelectionRecord` owns which ones the user picked - written to YAML always, and to the initializer line when the caller asks for it and the line is in a shape it can rewrite (an ordinary `ai:context` run refreshes the YAML only), read initializer-first because that is the file a user hand-edits.
 
 ## Path
 
@@ -30,13 +30,13 @@ Two senses, one per module, and neither is bare "path" in a name.
 
 ## Safe path
 
-A caller-supplied path resolved once, through `SafePath`, before anything reads it. Its refusal order is the contract, not an implementation detail: traversal, sensitive name, realpath, containment, sensitive realpath, file, size. A caller that reorders those checks, or repeats one of them itself, gets a different answer on a symlink or a dotfile than every other tool does, which is the divergence the module exists to end. `safe_glob` is the globbed-path form: the same guard applied to each path a pattern yields.
+A caller-supplied path resolved once, through `SafePath`, before anything reads it. Its refusal order is the contract, not an implementation detail: traversal, sensitive name, realpath, containment, sensitive realpath, file, size. A caller that reorders those checks, or repeats one of them itself, gets a different answer on a symlink or a dotfile than every other tool does, which is the divergence the module exists to end. `BaseTool.safe_glob` is the globbed-path form: realpath, containment and the sensitive-realpath check on each path a pattern yields, with the size cap left to the read that follows.
 
 Not the same as a path that merely looks harmless, and not a caller's own containment check - "the tool guards this parameter" means it hands the parameter to `SafePath` and renders whatever refusal comes back.
 
 ## Carried path
 
-A path the payload already holds because the gem's own walk found it - a controller's or a model's `file:`. It is re-read with `SafeFile.read(File.join(root, relative))`, which applies the size cap and nothing else. The reason is the walk: `SourceScan` deliberately keeps the spelling the app uses rather than the realpath, so a pack or an in-repo engine symlinked out of the root is spelled inside it, and `SafePath`'s realpath containment would refuse the very file the payload just named - the source comes back nil and a section silently empties.
+A path the payload already holds because the gem's own walk found it - a controller's or a model's `file:`. A controller's is re-read with `SafeFile.read(File.join(root, relative))`, which checks that it is a regular file under the size cap and nothing else; a model's goes through `PortablePath.resolve` first, since it can be a `gem:` path. The reason is the walk: `SourceScan` deliberately keeps the spelling the app uses when the realpath falls outside the root, so a pack or an in-repo engine symlinked out of the root is spelled inside it, and `SafePath`'s realpath containment would refuse the very file the payload just named - the source comes back nil and a section silently empties.
 
 Not an exception to the **safe path** rule, the other side of it: a caller-supplied path is untrusted and goes through `SafePath`; a carried path was produced by this gem and only needs the cap.
 
@@ -58,7 +58,7 @@ The other half of the same problem is the reverse trip. Once a name is the decla
 
 The table a model reads. Rails builds it as `table_name_prefix` + the demodulized class name, pluralized unless `pluralize_table_names` is off, + `table_name_suffix`, unless the class assigns one itself or is an STI child, which reads its parent's. The static tier answers the same order from source: an explicit `self.table_name =`, else the table of the model it inherits from, else the prefix and suffix the enclosing modules declare around the file's own basename. That basename is pluralized unless the class, then its superclass chain, then the app sets `pluralize_table_names = false`. The app-wide affixes and pluralize setting come from `ActiveRecordSettings`, which reads config/application.rb, the environment file, the initializers and `on_load(:active_record)` blocks. Never the underscored constant - that turns `Admin::ActionLog` into `admin/action_logs` and `OAuthClientConfig` into `o_auth_client_configs`, neither of which is a table.
 
-`TableName` reads the five declarations of one class body (`table_name`, `table_name_prefix`, `table_name_suffix`, `pluralize_table_names` and `primary_key`) and holds the two derivations; walking the namespace and the superclass chain belongs to the caller, because only it has the other files. A reader that starts from a model name instead of a file asks `TableName.for_model_name`, which takes the table the model tier already recorded before falling back to the convention. A prefix declared outside the model directories is still invisible, so the answer stays [STATIC].
+`TableName` reads the five declarations of one class body (`table_name`, `table_name_prefix`, `table_name_suffix`, `pluralize_table_names` and `primary_key`) and holds the two derivations; walking the namespace and the superclass chain belongs to the caller, because only it has the other files. A reader that starts from a model name instead of a file asks `TableName.for_model_name`, which takes the table the model tier already recorded before falling back to the convention. A module prefix declared outside the model directories is still invisible, an engine's in `lib/**/engine.rb` aside, so the answer stays [STATIC].
 
 ## Static tier
 
@@ -94,8 +94,10 @@ A Rack app the routing table attaches at a path, engine or not. `mount App =>
 "/path"` is `match("/path", to: App, via: :all, anchor: false)` with a name
 derived, so both spellings build the same endpoint and both are this. The
 payload key is `mounted_engines` for the sections that predate the widening;
-what it holds is every controller-less, non-dynamic endpoint the route set
-carries, which is what the count beside it has always counted.
+in the booted routes section it holds every controller-less, non-dynamic
+endpoint the route set carries, which is what the count beside it has always
+counted. The engines section, and the static routes section, hold the mounts
+parsed from the route files.
 
 Distinct from a **Rails engine**, which is a `Rails::Engine` subclass whether
 or not anything mounts it, and which `rails_get_engines` lists separately under
@@ -139,7 +141,7 @@ Which filters a controller runs, and which of them a given action runs. `ActionF
 
 **A block filter is named by its line.** `before_action { ... }` and `after_action -> { ... }` are callbacks of their own, listed as `block (line N)` and `lambda (line N)` (a lambda says so, as `Proc#lambda?` does, so it reads apart from a block on its line), N being the line the block opens on in the controller's own file; a block in any other file (a concern's class method, an ancestor's body) is `block (line N of app/controllers/concerns/cache_concern.rb)`, as two blocks on one line number in two files are two callbacks. The booted tier lists only a block the app wrote; a framework's or a gem's (`allow_browser`) is left out, as the static tier cannot see it. `skip_forgery_protection` is the `skip_before_action :verify_authenticity_token` Rails defines it as.
 
-**What it cannot see is stated rather than guessed.** The walk reads `ApplicationController`'s file by the one name Rails fixes, so its filters are in the chain; a parent the listing does not hold and the app has no file for - a gem-owned base, or one an inflection renames - still ends the walk. `docs/COMPATIBILITY.md` says both halves.
+**What it cannot see is stated rather than guessed.** The walk reads `ApplicationController`'s file by the one name Rails fixes, so its filters are in the chain; a parent the listing does not hold and the app has no file for - a gem-owned base other than Devise's or Doorkeeper's (there the walk resumes at the parent the initializer names), or one an inflection renames - still ends the walk. `docs/COMPATIBILITY.md` says both halves.
 
 ## Payload
 

data/CONTRIBUTING.md

@@ -35,7 +35,7 @@ lib/rails_ai_context/
 3. Register it in `lib/rails_ai_context/introspector.rb` (the `INTROSPECTOR_MAP`)
 4. `extend StaticTier` and declare one: `static_tier :files_only` if `#call` runs unchanged with nothing booted, `:runtime_only` if it needs live reflection, or `:alternate_source` plus a `static_call` reading elsewhere. A mapped introspector that declares nothing fails the suite
 5. Add the key to the appropriate preset(s) in `Configuration::PRESETS` (`:full` is the default, `:standard` for core-only)
-6. Write specs in `spec/lib/rails_ai_context/your_introspector_spec.rb`
+6. Write specs in `spec/lib/rails_ai_context/introspectors/your_introspector_spec.rb`
 
 ## Adding a New MCP Tool
 
@@ -86,7 +86,7 @@ bundle exec rubocop --parallel # Lint check
 
 `spec/fixtures/static_app` is the app the static tier is exercised against, and
 `spec/lib/rails_ai_context/serializers/real_shape_smoke_spec.rb` pins its model
-count in two places (`Models 7` and `Models (7)`).
+count in three assertions (a `Models 7` match and `Models (7)` twice).
 
 Adding or removing a fixture model means changing that spec in the same commit.
 

data/README.md

@@ -8,7 +8,7 @@
 [![Downloads](https://img.shields.io/gem/dt/rails-ai-context?style=flat-square&color=blue)](https://rubygems.org/gems/rails-ai-context)
 [![CI](https://img.shields.io/github/actions/workflow/status/crisnahine/rails-ai-context/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/crisnahine/rails-ai-context/actions)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green?style=flat-square)](https://registry.modelcontextprotocol.io)
-[![Ruby](https://img.shields.io/badge/Ruby-3.1_to_3.4-CC342D?style=flat-square&logo=ruby&logoColor=white)](https://github.com/crisnahine/rails-ai-context)
+[![Ruby](https://img.shields.io/badge/Ruby-3.1_to_4.0-CC342D?style=flat-square&logo=ruby&logoColor=white)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.0_to_8.1-CC0000?style=flat-square&logo=rubyonrails&logoColor=white)](https://github.com/crisnahine/rails-ai-context)
 [![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
 
@@ -30,7 +30,7 @@
 **rails-ai-context** is a Ruby gem that turns your Rails app into the source of truth for AI coding assistants. Instead of guessing your schema, associations, routes and conventions from training data, the assistant asks your app: 45 read-only tools served over [MCP](https://modelcontextprotocol.io) or run from the CLI, plus generated context files for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI.
 
 > [!TIP]
-> Nothing to add to your Gemfile if you don't want to. `gem install rails-ai-context`, then `rails-ai-context init` inside any Rails app. It also works on an app that won't boot: pass `--no-boot` and every tool answers from the source files.
+> Nothing to add to your Gemfile if you don't want to. `gem install rails-ai-context`, then `rails-ai-context init` inside any Rails app. It also works on an app that won't boot: pass `--no-boot` and the tools answer from the source files. The two that need a live app, `query` and `runtime_info`, say so.
 
 ## Why
 
@@ -63,7 +63,7 @@ You catch it, fix it, re-prompt, and something next to it breaks. The tokens are
 ## Features
 
 - **45 read-only tools** for schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app.
-- **Prism AST parsing** for model introspection. Each result carries `[VERIFIED]` or `[INFERRED]` so the assistant knows what is ground truth and what needs a runtime check.
+- **Prism AST parsing** for model introspection. A model heading and each scope carry `[VERIFIED]` or `[INFERRED]` (`[STATIC]` without a boot) so the assistant knows what is ground truth and what needs a runtime check.
 - **Three ways in**: MCP over stdio, MCP mounted inside your Rails app over HTTP, or plain CLI in any terminal.
 - **Generated context files** for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI, with the MCP config each tool auto-detects on project open.
 - **Live resources**: `rails://` and `rails-ai-context://` URIs that introspect fresh on every read.
@@ -87,7 +87,7 @@ bundle add rails-ai-context --group development
 rails generate rails_ai_context:install
 ```
 
-The generator asks which AI tools you use and what to write, then creates the context files, the MCP config for each tool, and `config/initializers/rails_ai_context.rb`. Re-running it is safe; it keeps what you have and adds what is missing.
+The generator asks which AI tools you use and what to write, then creates the context files, the MCP config for each tool, `config/initializers/rails_ai_context.rb` and `.rails-ai-context.yml`. In a git repo with no pre-commit hook it also offers to install one. An empty answer to the tools question selects all five, and `--defaults` takes the default for each question. Re-running it is safe; it keeps what you have and adds what is missing. Every step is in [What the install generator does](docs/GUIDE.md#what-the-install-generator-does).
 
 Keeping your own `CLAUDE.md` and `AGENTS.md`? `rails generate rails_ai_context:install --mcp-only` writes the MCP config and leaves every context file alone.
 
@@ -125,10 +125,12 @@ Then open the project in your AI tool. The MCP config it wrote is picked up on o
 The default. Each AI tool gets its own config file (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`) pointing at:
 
 ```bash
-rails ai:serve             # in-Gemfile
-rails-ai-context serve     # standalone
+bundle exec rails-ai-context serve   # in-Gemfile
+rails-ai-context serve               # standalone
 ```
 
+`rails ai:serve` starts the same server from rake.
+
 ### MCP over HTTP
 
 Mount the server inside your app. It inherits your routing, auth and middleware, and needs no second process.
@@ -152,7 +154,7 @@ rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
 rails-ai-context tool schema --table users --detail full
 ```
 
-Tool names resolve loosely: `schema`, `get_schema` and `rails_get_schema` all work. Most tools take `detail=summary|standard|full`.
+Tool names resolve loosely: `schema`, `get_schema` and `rails_get_schema` all work. About half the tools take `detail=summary|standard|full`.
 
 ### Commands
 
@@ -186,9 +188,9 @@ Every tool is read-only and answers from your app.
 
 A few worth knowing on day one:
 
-- `search_code` with `match_type=trace` returns definition, source, every caller grouped by type, and the tests, in one call. That replaces 4 to 5 file reads.
+- `search_code` with `match_type=trace` returns definition, source, every caller grouped by file and labelled by type, and the tests, in one call. That replaces 4 to 5 file reads.
 - `get_controllers` returns the action source with inherited filters, strong params and the render map.
-- `get_model_details` returns associations, validations, scopes, enums and macros from the AST, each tagged `[VERIFIED]` or `[INFERRED]`.
+- `get_model_details` returns associations, validations, scopes, enums and macros from the AST, with the model and each scope tagged `[VERIFIED]` or `[INFERRED]`.
 - `query` runs read-only SQL with a timeout, a row limit and column redaction. `read_logs` redacts sensitive data before it leaves the process.
 
 Parameters for all 45 are in the [tools reference](docs/TOOLS.md); worked examples in [recipes](docs/RECIPES.md).
@@ -234,7 +236,7 @@ Code is found in the conventional layout, in packwerk packs (`packs/*/app/*`), i
 
 ```ruby
 # config/initializers/rails_ai_context.rb
-if defined?(RailsAiContext)
+if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)
   RailsAiContext.configure do |config|
     config.ai_tools  = %i[claude cursor]   # which AI tools to generate for
     config.tool_mode = :mcp                # :mcp (default) or :cli
@@ -254,8 +256,9 @@ Register your own tools next to the built-in ones:
 class RailsGetBusinessMetrics < MCP::Tool
   tool_name "rails_get_business_metrics"
   description "Key business metrics for this app"
+  input_schema(properties: { period: { type: "string" } })
 
-  def call(period: "week")
+  def self.call(period: "week", server_context: nil)
     MCP::Tool::Response.new([{ type: "text", text: "Users this #{period}: #{User.recent.count}" }])
   end
 end

data/SECURITY.md

@@ -21,11 +21,11 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 - All 45 MCP tools are **read-only** and never modify your application or database.
 - **Sensitive file blocking** - configurable `sensitive_patterns` blocks access to `.env`, `*.key`, `*.pem`, `credentials.yml.enc` across all search and read tools. Patterns are checked in `rails_search_code`, `rails_get_edit_context`, and all new tools.
 - **Path traversal protection** - all file-reading tools validate paths with `File.realpath()` against `Rails.root` to prevent directory escape.
-- **Command injection prevention** - code search uses `Open3.capture2` with array arguments (never shell strings). The `--` flag separator prevents pattern injection.
-- **Regex DoS protection** - user-supplied regex patterns have 1-2 second timeouts via `Regexp.new(pattern, timeout:)`.
-- **Credential safety** - `rails_get_env` only reads `.env.example` (never `.env`), shows credential key names only (never values), and redacts secrets. `rails_get_config` exposes adapter/framework names, not connection strings.
+- **Command injection prevention** - code search uses `Open3.capture3` with array arguments (never shell strings). The `--` flag separator prevents pattern injection.
+- **Regex DoS protection** - user-supplied regex patterns have 1-2 second timeouts via `Regexp.new(pattern, timeout:)` on Ruby 3.2 and newer. Ruby 3.1 has no `Regexp.timeout`, so the timeout is skipped there.
+- **Credential safety** - `rails_get_env` only reads `.env.example`, `.env.sample` or `.env.template` (never `.env`), shows credential key names only (never values), and redacts secrets. `rails_get_config` exposes adapter/framework names, not connection strings.
 - **Brakeman integration** - optional `rails_security_scan` tool runs static security analysis. Graceful degradation if not installed. Users can exclude it via `config.skip_tools = %w[rails_security_scan]`.
-- **File size limits** - all tools enforce configurable `max_file_size` (default 5MB) to prevent memory exhaustion on large files.
+- **File size limits** - tools that read a whole file skip one over the configurable `max_file_size` (default 5MB) to prevent memory exhaustion on large files. `rails_read_logs` reads the last 1MB of a log instead, and `rails_search_code` caps its output with `max_search_results`.
 - **SQL comment stripping** - `rails_query` strips block (`/* */`), line (`--`), and MySQL-style (`#`) comments before validation to prevent keyword hiding.
 - **Regex interpolation safety** - all introspectors use `Regexp.escape` when interpolating model/association names into patterns to prevent regex injection.
 - **Log redaction** - `rails_read_logs` redacts passwords, tokens, secrets, API keys, cookies, session IDs, emails, and environment variables before output.

data/docs/ARCHITECTURE.md

@@ -93,7 +93,7 @@ flowchart LR
     F --> G[Cache Result]
     G --> D
     D --> H[Hydrate\nSchema Hints]
-    H --> I[Truncate\nmax_chars]
+    H --> I[Truncate\nmax_tool_response_chars]
     I --> J[MCP::Tool::Response]
 ```
 
@@ -132,10 +132,10 @@ Two more answer a question a tool asks:
 
 **Prism AST parsing** replaced all regex-based Ruby source parsing in v5.2.0.
 
-- **AstCache** - Thread-safe parse cache (`Concurrent::Map`), keyed by path + SHA256 + mtime; a stat match answers without a read for a file already two seconds older than the read that recorded it
+- **AstCache** - Thread-safe parse cache (`Concurrent::Map`), keyed by the SHA256 of the file's content; a stat match answers without a read for a file already two seconds older than the read that recorded it
 - **SourceIntrospector** - Single-pass Prism Dispatcher walks the AST once, feeding every registered listener simultaneously
-- **Listeners** - Associations, Validations, Scopes, Enums, Callbacks, Macros and Methods are the default map for model analysis; the rest are used through targeted walks over schema dumps, migrations, Gemfiles, rake tasks and initializers, and `MethodCallListener` reports a named call with its arguments and options wherever one is asked for
-- **Confidence** - Every result carries `[VERIFIED]` (static literals) or `[INFERRED]` (dynamic expressions), and a record in a static-tier entry is capped at `[STATIC]`, since no record can claim more than the tier that carries it
+- **Listeners** - Associations, Validations, Scopes, Enums, Callbacks, Macros, Methods and Mixins are the default map for model analysis; the rest are used through targeted walks over schema dumps, migrations, Gemfiles, rake tasks and initializers, and `MethodCallListener` reports a named call with its arguments and options wherever one is asked for
+- **Confidence** - A listener that records one tags each record `[VERIFIED]` (static literals) or `[INFERRED]` (dynamic expressions), and a record in a static-tier entry is capped at `[STATIC]`, since no record can claim more than the tier that carries it
 
 ### Tool Registry (`lib/rails_ai_context/tools/base_tool.rb`)
 
@@ -196,7 +196,7 @@ Result: controller and view tools automatically include relevant schema informat
 | `CopilotSerializer` | `.github/copilot-instructions.md` |
 | `CopilotInstructionsSerializer` | `.github/instructions/*.instructions.md` |
 | `OpencodeSerializer` | `AGENTS.md` (root) |
-| `OpencodeRulesSerializer` | `app/*/AGENTS.md` |
+| `OpencodeRulesSerializer` | `app/models/AGENTS.md`, `app/controllers/AGENTS.md` |
 | `JsonSerializer` | `.ai-context.json` |
 | `MarkdownSerializer` | Base formatting |
 | `ContextFileSerializer` | Atomic file writes with section markers |
@@ -207,6 +207,7 @@ Result: controller and view tools automatically include relevant schema informat
 | `SectionFacts` | The facts every surface states about an app - auth, assets, associations, the filter chain, an unread entry's row, the static-tier notice - each rendered in one place |
 | `SectionMarkerWriter` | Writes a managed section into a file the user also owns |
 | `ContextModeDispatch` | Picks full or compact rendering for a run |
+| `Base` | Holds the context hash a serializer renders |
 
 ### CLI (`exe/rails-ai-context`, `lib/rails_ai_context/cli/`)
 
@@ -219,7 +220,7 @@ Thor-based CLI that works standalone (no Gemfile entry):
 
 ### Path safety (`lib/rails_ai_context/safe_path.rb`, `lib/rails_ai_context/view_file.rb`)
 
-- **SafePath** - Resolves a caller-supplied path once, in a fixed refusal order: traversal, sensitive name, realpath, containment, sensitive realpath, file, size. `safe_glob` is the globbed-path form
+- **SafePath** - Resolves a caller-supplied path once, in a fixed refusal order: traversal, sensitive name, realpath, containment, sensitive realpath, file, size. `BaseTool.safe_glob` is the globbed-path form, checking realpath, containment and the sensitive realpath on each path a pattern yields
 - **ViewFile** - Which file a view name means, and whether the app owns it, so no tool builds a template path itself
 
 ### Caching
@@ -237,7 +238,7 @@ Four cache layers:
 
 SHA256-based change detection:
 
-- Watches: `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`, Gemfile.lock, `config.ru`, the Rakefile
+- Watches: `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`, the Gemfile and Gemfile.lock (or `gems.rb` and `gems.locked`), `package.json`, `tsconfig.json`, `config.ru`, the Rakefile
 - Computes a composite fingerprint from all watched files
 - Used by introspection cache and live reload to detect actual changes
 
@@ -245,9 +246,9 @@ SHA256-based change detection:
 
 1. **Official MCP SDK** - Not a custom protocol. Uses `mcp` gem's `MCP::Tool`, `MCP::Server`, transports.
 2. **Read-only tools** - All 45 tools annotated as non-destructive. Defense-in-depth for query tool.
-3. **Graceful degradation** - Works without database (parses schema.rb as text), without Brakeman, without ripgrep, without listen gem.
-4. **Zeitwerk autoloading** - Files loaded on-demand. No `require_relative` in the gem.
-5. **Diff-aware generation** - Context file regeneration skips unchanged files using fingerprinting.
+3. **Graceful degradation** - Works without database (parses `schema.rb` or `structure.sql`, or replays the migrations), without Brakeman, without ripgrep, without listen gem.
+4. **Zeitwerk autoloading** - Files loaded on-demand. `require_relative` is kept for the few files that load before or outside the loader.
+5. **Diff-aware generation** - Context file regeneration skips a file whose content is unchanged, the timestamp line aside.
 6. **Section markers** - Root file content wrapped in `<!-- BEGIN/END rails-ai-context -->` to preserve user-added content.
 
 ## Dependencies

data/docs/CLI.md

@@ -29,6 +29,7 @@ Start the MCP server.
 
 ```bash
 rails ai:serve                                        # stdio (default)
+rails ai:serve_http                                   # HTTP transport
 rails-ai-context serve                                # stdio (default)
 rails-ai-context serve --transport http --port 6029   # HTTP transport
 ```
@@ -58,7 +59,8 @@ rails-ai-context tool model_details --model User
 | Option | Description |
 |:-------|:------------|
 | `--list` | List all available tools |
-| `--json` | Output as JSON |
+| `--json` | Output as JSON (`-j` after the tool name) |
+| `--help` | After the tool name, print that tool's parameters. Rake: `help=true` |
 | `--no-boot` | Skip booting the app; answer from source alone |
 
 Global options may be typed before or after the command name:
@@ -94,11 +96,15 @@ unanswered.
 
 A thing that is simply not there is an ordinary answer and exits 0: a file the
 tool looked for and did not find, a search with no matches, a directory the
-`--path` names that does not exist.
+`--path` names that does not exist. A tool that needs a
+booted app and is run with `--no-boot` (`query`, `runtime_info`) prints
+`[UNAVAILABLE]` with the reason and also exits 0.
 
 A value the schema cannot hold - `--detail bogus` where the parameter takes
 `summary`, `standard` or `full`, or `--limit abc` where it takes an integer -
-is warned about on stderr and the tool's own default is used.
+is warned about on stderr and the tool's own default is used. A required
+parameter has no default, so a value outside its list (`--action bogus` on
+`migration_advisor`) exits 1.
 
 ### The static tier and `--no-boot`
 
@@ -131,7 +137,7 @@ rails 'ai:tool[get_schema]'
 rails 'ai:tool[rails_get_schema]'
 ```
 
-Resolution order: exact match → `rails_` prefix → `rails_get_` prefix → `get_` prefix.
+Resolution order: exact match → `rails_` prefix → `rails_get_` prefix → short name (the name with `rails_get_` or `rails_` removed).
 
 ### `context`
 
@@ -143,7 +149,9 @@ rails ai:context:claude       # Claude only
 rails ai:context:cursor       # Cursor only
 rails ai:context:copilot      # Copilot only
 rails ai:context:opencode     # OpenCode only
+rails ai:context:codex        # Codex only
 rails ai:context:json         # JSON export
+rails ai:context:full         # All formats, full mode
 
 rails-ai-context context                # All
 rails-ai-context context --format claude # Specific format
@@ -153,6 +161,10 @@ rails-ai-context context --format claude # Specific format
 |:-------|:--------|:------------|
 | `--format` | all configured | `claude`, `cursor`, `copilot`, `opencode`, `codex`, `json`, `all` |
 
+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.
+
 ### `doctor`
 
 Run the diagnostic checks and report an AI readiness score.
@@ -183,14 +195,16 @@ Interactive setup for standalone mode.
 
 ```bash
 rails-ai-context init
+rails-ai-context init --mcp-only   # MCP config only, no context files
 ```
 
-Asks which AI tools to configure and whether to use MCP or CLI mode. Creates `.rails-ai-context.yml` and MCP config 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.
 
 ### `version`
 
 ```bash
 rails-ai-context version
+rails-ai-context --version   # or -v
 ```
 
 ### `inspect`
@@ -199,6 +213,7 @@ Print introspection summary as JSON.
 
 ```bash
 rails-ai-context inspect
+rails ai:inspect             # short text summary instead of JSON
 ```
 
 ### `facts`
@@ -206,17 +221,19 @@ rails-ai-context inspect
 Print a schema facts summary: tables, associations and dependencies.
 
 ```bash
+rails ai:facts
 rails-ai-context facts
 rails-ai-context facts --no-boot
 ```
 
 ### `preset`
 
-Run a named group of tools in one pass. With no name it lists the presets.
+Run a named group of tools in one pass: `architecture`, `debugging` or `migration`. With no name it lists the presets.
 
 ```bash
 rails-ai-context preset
 rails-ai-context preset architecture
+rails 'ai:preset[architecture]'
 ```
 
 ### `tree`
@@ -239,12 +256,18 @@ rails-ai-context tree
 | `rails ai:context:cursor` | Generate Cursor context |
 | `rails ai:context:copilot` | Generate Copilot context |
 | `rails ai:context:opencode` | Generate OpenCode context |
+| `rails ai:context:codex` | Generate Codex context |
 | `rails ai:context:json` | Generate JSON export |
+| `rails ai:context:full` | Generate all formats in full mode |
+| `rails 'ai:context_for[claude]'` | Generate one format by name |
 | `rails ai:serve` | Start MCP server (stdio) |
+| `rails ai:serve_http` | Start MCP server (HTTP) |
 | `rails ai:tool` | List tools or run a tool |
 | `rails ai:doctor` | Run diagnostics |
 | `rails ai:watch` | Watch mode |
-| `rails ai:setup` | Interactive setup (alternative to generator) |
+| `rails ai:inspect` | Print introspection summary |
+| `rails ai:facts` | Print schema facts summary |
+| `rails 'ai:preset[name]'` | Run a preset; no name lists them |
 
 ---
 
@@ -259,6 +282,7 @@ rails 'ai:tool[tool_name]' key=value key2=value2
 - Strings: `table=users`
 - Booleans: `explain=true` or `explain=false`
 - Enums: `detail=full`
+- Arrays: `files=a.rb,b.rb`
 - Spaces: `pattern="has_many :posts"`
 
 ### Thor format
@@ -270,6 +294,7 @@ rails-ai-context tool tool_name --key value --key2 value2
 - Strings: `--table users` or `--table=users`
 - Booleans: `--explain` (true) or `--no-explain` (false)
 - Enums: `--detail full`
+- Arrays: `--files a.rb b.rb` or `--files a.rb,b.rb`
 - Spaces: `--pattern "has_many :posts"`
 
 ### JSON output
@@ -278,6 +303,7 @@ Add `--json` for machine-readable output:
 
 ```bash
 rails-ai-context tool schema --table users --json
+JSON=1 rails 'ai:tool[schema]' table=users
 ```
 
 ---