rails-ai-context 5.35.0 → 5.35.2

data/CONTEXT.md

@@ -6,9 +6,9 @@ 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`: `EnvIntrospector` reads the variables and the `ENV[]` call sites, and the tool reads the other places itself.
+**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_config(section:"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`.
+**Environment config** - what `config/environments/*.rb` declares per environment: the assigned `config.*` keys and the values of the notable toggles. Served by `rails_get_config(section:"env_config")`, read by `EnvConfigIntrospector`.
 
 **Environment** (unqualified, as data) - a single named Rails environment: development, production, staging. This is the only sense in which the bare word is allowed, and only as a value, never as a name. The `:environments` payload key means "the list of these", which is why it kept its name when the introspector was renamed.
 
@@ -110,10 +110,10 @@ 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
-its loaded classes. The record key is `engine:` for the same reason the section
-key is `mounted_engines:` - it predates the widening, and what it holds is the
-mounted app's constant, engine or not.
+or not anything mounts it, and which `rails_get_config(section:"engines")`
+lists separately under its loaded classes. The record key is `engine:` for the
+same reason the section key is `mounted_engines:` - it predates the widening,
+and what it holds is the mounted app's constant, engine or not.
 
 ## Interaction filter
 
@@ -167,7 +167,7 @@ A gem the context calls out because it shapes how the app is built, counted only
 
 ## Payload
 
-The introspection context hash, in the sense consumers read it. `Payload` is the reading side: a section guard and pinned list readers whose key pairs a spec checks against the producing introspector's own output, so a renamed key fails a test instead of silently emptying a section everywhere. Facts rendered from it live once (`SectionFacts`); membership judgments are applied at the introspector seam, and readers trust the payload rather than re-filtering it.
+The introspection context hash, in the sense consumers read it. `Payload` is the reading side: a section guard and pinned list readers whose key pairs a spec checks against the producing introspector's own output, so a renamed key fails a test instead of silently emptying a section everywhere. Facts rendered from it live once (`SectionFacts`); membership judgments are applied at the introspector seam, and readers trust the payload rather than re-filtering it. One reader fills a section a preset leaves out: `Payload.multi_database` reads the app databases list when the `multi_database` introspector did not run, so a database's mark and the first database's own name do not depend on the preset.
 
 ## Standalone
 
@@ -210,3 +210,33 @@ An install with every question answered on the command line, the way an AI tool
 ## Install prompt
 
 A message a user pastes into their AI tool so the AI tool installs, changes, removes or starts using the gem in their app. `docs/PROMPTS.md` holds them. Each names its commands outright and runs an **unattended install**, since an AI tool's shell has no one at the keyboard to answer a question.
+
+## Database family
+
+What a database is by its adapter's name, as far as running a statement on it goes: PostgreSQL (PostGIS too), MySQL (Trilogy and MariaDB too) or SQLite. Each family knows how its database opens a read-only transaction, bounds a statement in time, explains a plan and reports table sizes; anything else is no family, and a tool that needs one refuses or says the answer is not available, naming the adapter. `DatabaseFamily` is the one answer, from a connection, a database.yml adapter or a dump's dialect. ADR-0008 records why a family is claimed by name.
+
+Not "engine", which this glossary keeps for Rails engines and **mounted apps**, and not "adapter", which is ActiveRecord's class for one driver.
+
+## App database
+
+A database the app has in any environment: one database.yml configures for the running environment, one only another environment configures (Rails 8's queue, cache and cable outside production, and a replica or a database with `database_tasks` off too), or one only a committed dump names. `AppDatabases` lists them once per run, the primary first, and each knows the environments that configure it, its **database family**, its dump and its migrations. The primary is the database `ActiveRecord::Base` is connected to on the booted tier, and the running environment's first entry on the static tier. Every surface that asks "which databases" reads this list, so the schema section, the models and the migrations cannot disagree about one app.
+
+A tool that needs a connection reaches an app database configured here and nothing else: asked for one that only production configures, it says so. A SQLite database whose file is not there is never connected to, since connecting would create the file: the answer names it and says it does not exist yet. A SQLite database other than the primary that lives in memory is refused by name too: it exists only inside the process that created it, and a new connection would open an empty one. Not the **environment** (one named Rails environment), and not a shard, which is one database's copy under another name.
+
+## Secret column
+
+A column whose values `rails_query` never returns, and whose name a statement may not mention: one the app lists in `query_redacted_columns`, an `encrypts` column, a built-in secret name, a name the result heuristic flags, or a name `Redaction`'s secret words cover, unless the app allows it by name in `query_allowed_columns`. An `encrypts` column is secret whatever that list holds: a statement that names it is refused, and its values come back filtered. A generated column whose expression reads a secret column is a secret column. On MySQL, MariaDB and SQLite, where no result column is traced to its table column, the rule also refuses a view whose definition names a secret column, and a `*` inside a subquery of a statement that names a table holding one. On PostgreSQL a materialized view is held to that view rule, and on SQLite a virtual table that holds a secret column is refused whole. `SecretColumns` decides for every check in the tool, from a read of the schema of the database the statement runs on and of every other schema or database the statement reaches. Only the primary falls back to the cached context's schema when its tables cannot be read. A database whose columns cannot be read at all is not queried. `docs/SECURITY.md` is the full statement of the rule.
+
+Not redaction itself: `Redaction` scrubs secret values out of text (logs, config, source). The two share the vocabulary, so a word added to one is secret in both.
+
+## SQL gate
+
+What decides whether `rails_query` runs a statement: the checks on its text, and on PostgreSQL the checks on its plan. It reads the statement once, with comments taken out, and answers either the text to run or a refusal with the reason, so nothing reaches the database that the gate did not read. On PostgreSQL a statement whose plan cannot be read does not run. `SqlGate`. The read-only transaction behind it is a second guard, and the gate's checks run before it on every database family (ADR-0008). A name the gate refuses belongs to one family and is refused there alone.
+
+## Served tool
+
+A tool the server answers for under the app's configuration: the built-ins `skip_tools` leaves, then each custom tool whose name no tool before it claims. An app's own class that inherits the gem's base tool counts with the built-ins once it is loaded, whether or not `custom_tools` lists it. Every surface reads the one set: `tools/list`, the CLI's list and lookup, the tool guide, the context files, `rails_get_context`'s includes and every tool name an answer prints. A tool outside it is never offered, run or pointed at. An answer or a guide step names or runs a tool only when the app serves the gem's own tool under that name: a custom tool in a built-in's place is listed, and nothing gives it the built-in's arguments. A custom tool named `rails_get_config` takes the built-in's place when `skip_tools` lists that name, and the **config sections** go with the built-in.
+
+## Config section
+
+One part of the app's configuration that `rails_get_config` answers by `section`: `app` (the default: database, auth, assets, cache, queue, Action Cable, initializers, middleware), `gems`, `frontend`, `api`, `engines`, `conventions`, `autoload`, `active_support`, `env` (the **process environment**), `env_config` (the **environment config**) and `i18n`. Ten of them were tools of their own; their names still reach their section from the CLI and the MCP server, and `skip_tools` lists them to turn a section off. With `app` off, a call has to name its `section`. ADR-0010.

data/CONTRIBUTING.md

@@ -20,7 +20,7 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 lib/rails_ai_context/
 ├── cli/               # CLI tool runner (tool_runner.rb) - executes MCP tools from rake/Thor
 ├── introspectors/     # 40 introspectors (schema, models, routes, etc.)
-├── tools/             # 45 MCP tools with detail levels and pagination
+├── tools/             # 35 MCP tools with detail levels and pagination
 ├── serializers/       # Per-assistant formatters + shared ToolGuideHelper
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── live_reload.rb     # MCP live reload (file watcher + cache invalidation)
@@ -82,6 +82,35 @@ bundle exec rspec spec/lib/    # Just lib specs
 bundle exec rubocop --parallel # Lint check
 ```
 
+### Real database servers
+
+The suite runs on SQLite. `spec/lib/rails_ai_context/database_family/database_servers_spec.rb`
+runs the PostgreSQL, MySQL and MariaDB families against real database servers, one group
+per URL that is set. `spec/lib/rails_ai_context/tools/query_postgresql_spec.rb` and
+`query_mysql_spec.rb` beside it run `rails_query` end to end on the same URLs.
+`spec/lib/rails_ai_context/app_databases_servers_spec.rb` leases a MySQL and a MariaDB
+database by name, and runs with `RAC_TEST_MYSQL_URL` and `RAC_TEST_MARIADB_URL`:
+
+| Variable | Database server | Example |
+|---|---|---|
+| `RAC_TEST_PG_URL` | PostgreSQL | `postgresql://postgres:secret@127.0.0.1:5432/rac` |
+| `RAC_TEST_MYSQL_URL` | MySQL, through mysql2 or Trilogy | `trilogy://root:secret@127.0.0.1:3306/rac` |
+| `RAC_TEST_MARIADB_URL` | MariaDB, through mysql2 or Trilogy | `trilogy://root:secret@127.0.0.1:3307/rac` |
+
+The URL's scheme picks the adapter. The drivers come from a separate Gemfile:
+
+```bash
+docker run -d --name rac-mysql -e MYSQL_ROOT_PASSWORD=secret -e MYSQL_DATABASE=rac -p 3306:3306 mysql:8.4
+BUNDLE_GEMFILE=gemfiles/database_servers.gemfile bundle install
+RAC_TEST_MYSQL_URL=trilogy://root:secret@127.0.0.1:3306/rac \
+  BUNDLE_GEMFILE=gemfiles/database_servers.gemfile bundle exec rspec spec/lib/rails_ai_context/database_family/database_servers_spec.rb
+```
+
+The specs create and drop tables and views whose names start with `rac_`, and leave the `postgres_fdw` extension installed on PostgreSQL, so point them at a scratch database.
+CI's `database_servers` job runs them on PostgreSQL 16 in every leg. Rails 8.0 runs two legs: MySQL 8.0 with MariaDB 10.6, and MySQL 8.4 with MariaDB 11.4. Rails 7.0 runs MySQL 8.0 with MariaDB 10.6, and Rails 8.1 runs MySQL 8.4 with MariaDB 11.4.
+Rails 7.0 has no Trilogy adapter, so its leg runs PostgreSQL and mysql2 only.
+The job builds mysql2 against MariaDB's client library (`libmariadb-dev`, through `BUNDLE_BUILD__MYSQL2`), which signs in to MySQL and to MariaDB. A MySQL client from 9.0 on cannot sign in to MariaDB.
+
 ### Static fixture
 
 `spec/fixtures/static_app` is the app the static tier is exercised against, and

data/README.md

@@ -25,7 +25,7 @@
 
 </div>
 
-**rails-ai-context** makes your Rails app the source of truth for your AI coding assistant. The assistant stops guessing your schema, associations, routes and conventions from training data and asks your app instead: **45 read-only tools** over [MCP](https://modelcontextprotocol.io) or the command line, plus context files written for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI.
+**rails-ai-context** makes your Rails app the source of truth for your AI coding assistant. The assistant stops guessing your schema, associations, routes and conventions from training data and asks your app instead: **35 read-only tools** over [MCP](https://modelcontextprotocol.io) or the command line, plus context files written for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI.
 
 ## Install in one paste
 
@@ -129,7 +129,7 @@ You catch it, fix it, re-prompt, and something next to it breaks. The tokens are
 
 | | |
 |:---|:---|
-| **45 read-only tools** | Schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app. |
+| **35 read-only tools** | Schema, models, controllers, routes, views, Stimulus, Turbo, jobs, services, mailers, i18n, gems, config, tests, security, performance and more. Every answer comes from your app. |
 | **Answers it can trust** | Models are read with the Prism parser. A model and each scope carry `[VERIFIED]` or `[INFERRED]` (`[STATIC]` without a boot), so the assistant knows what still needs a runtime check. |
 | **Three ways in** | MCP over stdio, MCP mounted in your app over HTTP, or plain CLI in any terminal. |
 | **Context files per AI tool** | `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, each with the MCP config its tool picks up, and six anti-hallucination rules up top. |
@@ -154,8 +154,8 @@ Switch any time with the [change the setup](docs/PROMPTS.md#change-the-setup) pr
 graph TD
     A["Your Rails app\nmodels + schema + routes + controllers + views + jobs"] -->|"40 introspectors"| B
     B["rails-ai-context\nPrism AST · cached · confidence-tagged\nstatic tier when the app can't boot"]
-    B --> C["MCP server\nstdio / HTTP\n45 tools · 5 templates · 9 resources"]
-    B --> D["CLI\nrake / Thor\nsame 45 tools"]
+    B --> C["MCP server\nstdio / HTTP\n35 tools · 5 templates · 9 resources"]
+    B --> D["CLI\nrake / Thor\nsame 35 tools"]
     B --> E["Context files\nCLAUDE.md · .cursor/rules/ · .github/instructions/ · AGENTS.md"]
 
     style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
@@ -177,9 +177,9 @@ Every tool is read-only and answers from your app.
 | Understand | `analyze_feature`, `get_context`, `onboard` |
 | Schema and models | `get_schema`, `get_model_details`, `get_callbacks`, `get_concern` |
 | Controllers and routes | `get_controllers`, `get_routes` |
-| Views and frontend | `get_view`, `get_stimulus`, `get_partial_interface`, `get_turbo_map`, `get_frontend_stack` |
+| Views and frontend | `get_view`, `get_stimulus`, `get_partial_interface`, `get_turbo_map` |
 | Testing and quality | `get_test_info`, `generate_test`, `validate`, `security_scan`, `performance_check` |
-| App config and services | `get_api`, `get_conventions`, `get_config`, `get_gems`, `get_env`, `get_helper_methods`, `get_service_pattern`, `get_job_pattern`, `get_component_catalog`, `get_i18n`, `get_mailers`, `get_engines`, `get_autoload`, `get_active_support`, `get_env_config` |
+| App config and services | `get_config` (sections: app, gems, frontend, api, engines, conventions, autoload, active_support, env, env_config, i18n), `get_helper_methods`, `get_service_pattern`, `get_job_pattern`, `get_component_catalog`, `get_mailers` |
 | Data and debugging | `dependency_graph`, `migration_advisor`, `search_docs`, `query`, `read_logs`, `diagnose`, `review_changes`, `runtime_info`, `session_context` |
 
 Four worth knowing on day one:
@@ -189,7 +189,7 @@ Four worth knowing on day one:
 - **`get_model_details`** returns associations, validations, scopes, enums and macros from the AST, tagged `[VERIFIED]` or `[INFERRED]`.
 - **`query`** runs read-only SQL with a timeout, a row limit and column redaction.
 
-Over MCP each name gets a `rails_` prefix (`rails_get_schema`). From the CLI the short name works: `schema`, `get_schema` and `rails_get_schema` all resolve. Parameters for all 45 are in the [tools reference](docs/TOOLS.md); worked examples in [recipes](docs/RECIPES.md).
+Over MCP each name gets a `rails_` prefix (`rails_get_schema`). From the CLI the short name works: `schema`, `get_schema` and `rails_get_schema` all resolve. Parameters for all 35 are in the [tools reference](docs/TOOLS.md); worked examples in [recipes](docs/RECIPES.md).
 
 <details>
 <summary><b>Live resources</b></summary>
@@ -241,7 +241,7 @@ mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
 
 The `if` keeps the routes file loading where the gem is not installed, as in production, where Bundler skips the development group. Outside development and test the endpoint refuses every request with a 403 unless you set `config.allow_http_in_production = true`, since it has no authentication of its own ([Security](docs/SECURITY.md#mcp-http-transport)). There is also a standalone HTTP process: `rails-ai-context serve --transport http --port 6029`.
 
-**CLI** runs the same 45 tools with no server, in any terminal:
+**CLI** runs the same 35 tools with no server, in any terminal:
 
 ```bash
 bin/rails 'ai:tool[search_code]' pattern="publishable?" match_type=trace
@@ -361,7 +361,7 @@ It removes the context files, the MCP entries, its config, its `.gitignore` line
 | [Quickstart](docs/QUICKSTART.md) | Up and running in 5 minutes |
 | [AI tool setup](docs/SETUP.md) | Claude Code, Cursor, Copilot, OpenCode, Codex CLI, HTTP transport |
 | [Guide](docs/GUIDE.md) | Every command, parameter and option |
-| [Tools reference](docs/TOOLS.md) | All 45 tools with every parameter |
+| [Tools reference](docs/TOOLS.md) | All 35 tools with every parameter |
 | [Recipes](docs/RECIPES.md) | Real workflows, end to end |
 | [CLI reference](docs/CLI.md) | Commands, flags and argument syntax |
 | [Standalone](docs/STANDALONE.md) | Use without a Gemfile entry |

data/SECURITY.md

@@ -18,12 +18,12 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 
 ## Security Design
 
-- All 45 MCP tools are **read-only** and never modify your application or database.
+- All 35 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.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.
+- **Credential safety** - `rails_get_config(section:"env")` reads only `.env.example`, `.env.sample` or `.env.template` and leaves `.env` unread. It shows credential key names without their values, and redacts secrets. `rails_get_config` exposes adapter and framework names and no connection string.
 - **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** - 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.

data/docs/ARCHITECTURE.md

@@ -30,7 +30,7 @@ graph TD
             H["Hydration Layer\nSchema hints\ninjected into\ntool responses"]
         end
 
-        engine --> R["Tool Registry\n45 tools auto-discovered via inherited\n+ custom_tools - skip_tools = active tools"]
+        engine --> R["Tool Registry\n35 tools auto-discovered via inherited\n+ custom_tools - skip_tools = active tools"]
     end
 
     R --> MCP
@@ -40,7 +40,7 @@ graph TD
     subgraph outputs["Output"]
         direction LR
         MCP["MCP Server\nstdio / HTTP\nResources\nVFS URIs"]
-        CLI["CLI Runner\nRake / Thor\nSame 45 tools\nNo server needed"]
+        CLI["CLI Runner\nRake / Thor\nSame 35 tools\nNo server needed"]
         S["Serializers\n18 modules\nStatic files\nPer-AI-tool"]
     end
 
@@ -128,6 +128,13 @@ Two more answer a question a tool asks:
 - **PendingMigrations** - which migration files are not in the applied set, from one derivation both the schema and migrations sections read
 - **ActionFilters** - which filters apply to a controller or to one of its actions: own, inherited, skipped. `skipped` holds unconditional skips only; a skip carrying `if:`/`unless:` leaves the filter in `own` or `inherited` with the condition on the record. Every controller surface reads its filter line from here, so no two answers can disagree
 
+Four more answer for the app's databases and for what `rails_query` runs on them:
+
+- **DatabaseFamily** - what a database is by its adapter's name: PostgreSQL (PostGIS too), MySQL (Trilogy and MariaDB too) or SQLite, else no family. A family owns its read-only transaction, its statement timeout, EXPLAIN, table sizes, row estimates and index usage. A runtime call on no family raises before anything reaches the database
+- **AppDatabases** - every database the app has, listed once per run: the primary, the rest of the running environment's, those only another environment configures, then dumps no environment claims. Both tiers build it through one builder. It also leases a connection to a database configured here, through a connection handler of its own for the call
+- **SecretColumns** - which columns `rails_query` never returns and a statement may not name, from one read of the leased database's schema. An `encrypts` column is secret whatever `query_allowed_columns` lists
+- **SqlGate** - whether `rails_query` runs a statement: the checks on its text, and on PostgreSQL the checks on its plan. It answers the comment-free text to run or a refusal with the reason
+
 ### AST Engine
 
 **Prism AST parsing** replaced all regex-based Ruby source parsing in v5.2.0.
@@ -145,6 +152,7 @@ Auto-registration via Ruby's `inherited` hook:
 2. Subclass is appended to `@descendants` (protected by `@registry_mutex`)
 3. `BaseTool.registered_tools` eager-loads all tool files and returns non-abstract classes
 4. `BaseTool` itself is marked `abstract!` - excluded from the registry
+5. The ten classes that render a `rails_get_config` section call `section_renderer!`. `rails_get_config` calls them, so they stay out of the registry and are still callable from Ruby
 
 **Deadlock-free design**: `eager_load!` walks `Tools.constants` and `const_get`s each one without holding the mutex, because `const_get` triggers Zeitwerk autoloading which calls `inherited`, which takes the mutex itself.
 
@@ -217,7 +225,7 @@ Thor-based CLI that works standalone (no Gemfile entry):
 - `EntryBoot` - Boots the app `AppRoot` chose for the standalone binary, or says which tier it fell back to
 - `ToolRunner` - Parses CLI args, resolves tool names, executes tools, formats output
 - Supports `--json` mode for machine-readable output
-- Same 45 tools available as MCP and CLI
+- Same 35 tools available as MCP and CLI
 
 ### Path safety (`lib/rails_ai_context/safe_path.rb`, `lib/rails_ai_context/view_file.rb`)
 
@@ -247,7 +255,7 @@ SHA256-based change detection:
 ## Key design decisions
 
 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.
+2. **Read-only tools** - All 35 tools annotated as non-destructive. Defense-in-depth for query tool.
 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.

data/docs/CLI.md

@@ -17,7 +17,7 @@
 | In-Gemfile (Rake) | `rails ai:` | `rails 'ai:tool[schema]' table=users` |
 | Standalone (Thor) | `rails-ai-context` | `rails-ai-context tool schema --table users` |
 
-Both provide the same 45 tools and functionality.
+Both provide the same 35 tools and functionality.
 
 ---
 
@@ -46,7 +46,7 @@ The server announces itself to the client as `server_name` from config, else `ra
 
 ### `tool`
 
-Run any of the 45 MCP tools from the terminal.
+Run any of the 35 MCP tools from the terminal.
 
 ```bash
 # Rake syntax
@@ -92,13 +92,33 @@ than one environment, because the environment decides which database
 configuration the booted tier reads.
 
 After the name of a tool that declares an `environment` parameter of its own
-(`env_config`), `--environment` is that tool's filter and does not set
-`RAILS_ENV`: `tool env_config --environment production` lists production and
-boots the app in its usual environment. Set `RAILS_ENV` through the
-environment variable, or put `--environment` before the command name, to boot
-in another one. Every other tool reads the flag as `RAILS_ENV`. A custom tool
-that declares the parameter gets the value both ways, since its schema cannot
-be read before the app boots.
+(`env_config`, or `config --section env_config`), `--environment` is that
+tool's filter and does not set `RAILS_ENV`:
+`tool config --section env_config --environment production` lists production
+and boots the app in its usual environment. The section's name is read in any
+capitalisation. Set `RAILS_ENV` through the environment variable, or put
+`--environment` before the command name, to boot in another one. Every other
+tool reads the flag as `RAILS_ENV`, and so does `config` with any other
+section: `tool config --section gems --environment production` boots the app
+in production. A custom tool that declares the parameter gets the value both
+ways, since its schema cannot be read before the app boots.
+
+The ten tools that became `rails_get_config` sections still answer by their
+old names: `tool gems` runs `config --section gems`. `tool gems --help` prints
+"rails_get_gems - runs the `gems` section of rails_get_config (notable gems by
+category)." and that section's parameters alone. A mistyped old name is
+suggested: `tool gemz` answers "Unknown tool 'gemz'. Did you mean 'gems'?". A
+bare word after an old name gets that section's flag: `tool gems auth` answers
+"'auth' is not a flag - did you mean '--category auth'?".
+
+Inside an app, or with `--app-path`, `tool <name> --help` describes the tool
+that app serves. It reads `.rails-ai-context.yml` and boots nothing. A tool or
+section `skip_tools` turned off answers "rails_get_env is turned off in this
+app: skip_tools lists it ..." and exits 1. With the `app` section off,
+`tool config --help` marks `section` required and says "Required: the app
+section is turned off in this app." A `skip_tools` set in an initializer is
+not seen, since help boots nothing. Outside an app help describes the gem's
+own tools.
 
 #### Exit status
 
@@ -107,7 +127,8 @@ parameter you did not pass, a flag with no value after it, a bare word where a
 flag belongs, and an unknown parameter all exit 1 and say which one. So does a
 refusal on policy - a path outside the app root, a sensitive file, a SQL
 statement the read-only validator blocks - because the question went
-unanswered.
+unanswered. So does a tool that fails unexpectedly: the answer starts
+`Tool <name> failed:`.
 
 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
@@ -115,11 +136,19 @@ tool looked for and did not find, a search with no matches, a directory the
 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. A required
-parameter has no default, so a value outside its list (`--action bogus` on
-`migration_advisor`) exits 1.
+A value outside a parameter's list (`--format xml` on `schema`,
+`--action bogus` on `migration_advisor`) exits 1 and names the values the
+parameter takes. The tool is not run, since any other value would answer a
+question you did not ask. `config --section bogus` exits 1 the same way, and
+its answer names the sections that are on in this app. A value of the wrong
+type is refused too: `--limit abc` on `search_code` answers
+"**Error:** `abc` is not a valid `limit`. Valid: an integer", a boolean takes
+`true` or `false`, and an empty `--limit=` is refused. So is `--no-<param>` on
+a parameter that is no boolean: `--no-limit` answers
+"**Error:** `--no-limit` is not a valid `limit`. Valid: an integer", and a
+string or an array parameter says "a string" or "an array". One value falls
+back to the tool's own default with a warning on stderr: a `--detail` level
+the tool does not have, since every level answers the same question.
 
 ### The static tier and `--no-boot`
 

data/docs/COMPATIBILITY.md

@@ -277,12 +277,13 @@ Proof sources:
    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.
+   tasks and all 45 of that release's 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
@@ -303,6 +304,19 @@ Proof sources:
    private production app; each AI tool's MCP config started the way its
    client starts it; and the unit suite and the E2E harness on Linux, macOS
    and Windows.
+   In the v5.35.1 release QA: `rails_query` through its tool call on real
+   PostgreSQL 16, MySQL 8.0 and 8.4 and MariaDB 10.6 and 11.4 servers, through
+   mysql2 and Trilogy, on Rails 7.0, 8.0 and 8.1, now a CI job of its own;
+   files of statements sent through the tool on each server and on SQLite
+   before and after each fix, with every changed answer traced to its fix;
+   the tool's own checks timed on Ruby 3.4 for statements up to a megabyte
+   and on Ruby 3.1 for statements of 50 kilobytes; and the unit suite and the
+   E2E harness on Linux, macOS and Windows.
+   In the v5.35.2 closing review: the statement files of the v5.35.1 QA sent
+   through the tool again on PostgreSQL 16, MySQL 8.4, MariaDB 11.4 and SQLite,
+   on the v5.35.1 code and on the fixed code, with every changed answer traced
+   to its fix; and for each fix an example that fails on the v5.35.1 code, on a
+   real server where the fix is a server's.
 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
@@ -332,13 +346,25 @@ Proof sources:
    in `spec/lib/rails_ai_context/introspectors/static_tier_declarations_spec.rb`.
    `Introspector#run_introspector` reports `{ unavailable: reason }` only for
    the eight runtime-only sections, regardless of shape.
-9. `spec/e2e/empty_app_spec.rb` - all 45 built-in tools swept against an app
+9. `spec/e2e/empty_app_spec.rb` - all 35 built-in tools swept against an app
    with no scaffold, no models, no controllers beyond
    `ApplicationController`, no routes beyond root.
 10. `spec/e2e/massive_app_spec.rb` - `schema`, `model_details`, and `routes`
-    (plus `context`, `onboard`, `analyze_feature`, `get_turbo_map`, `get_env`)
+    (plus `context`, `onboard`, `analyze_feature`, `get_turbo_map` and the
+    `env` section of `get_config`)
     sampled against 500 generated models/tables under a 180-second cap.
 
+`rails_query`, `rails_runtime_info` and the row estimates run on three
+database families: PostgreSQL (with PostGIS), MySQL (mysql2 and Trilogy, with
+MariaDB) and SQLite. `rails_query` refuses any other adapter (SQL Server,
+Oracle, CockroachDB) by name before sending a statement, and the table sizes,
+row estimates and index usage say they are not available there. CI's
+`database_servers` job runs the families against PostgreSQL 16, MySQL 8.0 and
+8.4 and MariaDB 10.6 and 11.4 on Rails 8.0, through mysql2 and Trilogy. It also
+runs PostgreSQL 16 with MySQL 8.0 and MariaDB 10.6 on Rails 7.0, which has no
+Trilogy adapter, and with MySQL 8.4 and MariaDB 11.4 on Rails 8.1; see
+[CONTRIBUTING.md](../CONTRIBUTING.md#real-database-servers).
+
 Postgres itself - live query safety (read-only transactions, the
 `BLOCKED_FUNCTIONS` guard against `pg_read_file`/`dblink`/`COPY ... PROGRAM`,
 DDL rejection) alongside schema/routes - is proven end-to-end against a real

data/docs/CONFIGURATION.md

@@ -177,7 +177,7 @@ filter either runs or is struck through.
 | `max_validate_files` | Integer | `50` | Maximum files for validation |
 | `search_extensions` | Array | `nil` | Narrows the Ruby fallback to these extensions. Unset, the fallback searches every non-hidden, non-binary file, as ripgrep does, so both backends return the same lines |
 | `concern_paths` | Array | `nil` (discovers `app/concerns` and `app/*/concerns`) | Paths to scan for concerns. Setting it replaces discovery, so it can narrow as well as widen |
-| `frontend_paths` | Array | `nil` (auto-detect) | Frontend directories, e.g. `["app/frontend", "../web-client"]`. One outside the app root is read for its package.json, lockfiles and bundler config, plus its tsconfig.json and the configs it extends inside that directory, and frontend_stack names it |
+| `frontend_paths` | Array | `nil` (auto-detect) | Frontend directories, e.g. `["app/frontend", "../web-client"]`. One outside the app root is read for its package.json, lockfiles and bundler config, plus its tsconfig.json and the configs it extends inside that directory, and the `frontend` section of `rails_get_config` names it |
 | `extra_app_paths` | Array | `[]` | Extra directories under the app root to treat as application code |
 
 Directories that carry their own Rails tree - `plugins/*`, `modules/*`,
@@ -199,12 +199,24 @@ fits neither that shape nor the conventional one.
 
 | Option | Type | Default | Validation | Description |
 |:-------|:-----|:--------|:-----------|:------------|
-| `query_timeout` | Integer | `5` | - | SQL query timeout in seconds |
+| `query_timeout` | Number | `5` | positive | SQL query timeout in seconds. A fraction of a second is allowed |
 | `query_row_limit` | Integer | `100` | 1 to 1000 | Maximum rows returned |
 | `query_redacted_columns` | Array | 14 patterns | - | Column names that cause a query to be rejected, on top of a fixed built-in list (see [SECURITY.md](SECURITY.md)) |
-| `query_allowed_columns` | Array | `[]` | - | Column names exempted from the built-in sensitive list and from `query_redacted_columns` |
+| `query_allowed_columns` | Array | `[]` | - | Column names exempted from the built-in secret column names and from `query_redacted_columns`. It does not release an `encrypts` column |
 | `allow_query_in_production` | Boolean | `false` | - | Allow `rails_query` tool in production |
 
+`rails_query` treats a column as a secret column when one of these holds:
+
+- its name is in `query_redacted_columns` or in the built-in list (`password_reset_token`, `remember_token`, `secret`, `private_key`, `authentication_string`, `rolpassword`, `setconfig`);
+- an `encrypts` declaration covers it;
+- its name ends in `password`, `secret`, `token`, `key`, `digest` or `hash`;
+- its name contains `password`, `secret`, `token` or `nonce`;
+- its name is `iv` or ends in `_iv`;
+- its name is secret to the gem's log and config redaction (`passwd`, `salt`, `credentials`, `pepper`, `signing_key` and the rest of its secret words);
+- it is a generated column whose expression reads a secret column.
+
+A statement that names a secret column is refused, and a secret column's values come back as `[FILTERED]`. A name in `query_allowed_columns` is not secret. An `encrypts` column, and a generated column that reads one, is the exception: a statement that names it is still refused, and its values stay filtered. On MySQL, MariaDB and SQLite a statement is also refused when it names a view whose definition reads a secret column, or holds a `*` inside a subquery while it names a table with a secret column. On PostgreSQL the view rule holds for a materialized view. [SECURITY.md](SECURITY.md#layer-4---secret-column-rejection) is the full statement of the rule, with how each check reads it and its stated limits.
+
 ### Logs
 
 | Option | Type | Default | Description |
@@ -224,8 +236,19 @@ 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]`). 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 |
+| `custom_tools` | Array | `[]` | Additional MCP::Tool classes to register (initializer only - a class reference cannot be written in YAML). A custom tool takes a built-in's name only when `skip_tools` lists that built-in. One that reuses the old name of a `rails_get_config` section (`rails_get_gems`) is served as its own tool, and the gem's own hints still mean the built-in section: they print `rails_get_config(section:"gems")` |
+| `skip_tools` | Array | `[]` | Built-in tool names to exclude (e.g., `%w[rails_security_scan]`). The notes below this table say what a skipped tool leaves and how the `rails_get_config` sections are skipped |
+
+What `skip_tools` does:
+
+- A skipped tool is left out of `tools/list`, `tool --list`, the tool guide and the context files.
+- No other tool's answer points at it: the hint that would name it is left out.
+- A custom tool with the same name takes its place and is listed with the app's tools. The gem's own hints, guide steps and composite answers leave it out, since those carry the built-in's arguments.
+- A call that names a skipped tool anyway says it is turned off here. That holds from the CLI, rake, an MCP client and `rails_get_context(include:)`.
+- The ten tools that became `rails_get_config` sections still go here by their old names: `rails_get_env` turns the `env` section off.
+- `rails_get_config` turns off only `app`. With `app` off, `section` is required.
+- The tool leaves `tools/list` once all eleven names are listed.
+- Listing `rails_get_config` while a custom tool has that name gives the custom tool the built-in's place. The ten sections go with the built-in, and a call to an old name such as `rails_get_gems` is then an unknown tool.
 
 ### Output
 

data/docs/CUSTOM_TOOLS.md

@@ -2,7 +2,7 @@
 
 # Custom Tools
 
-**Build your own MCP tools that run alongside the 45 built-in ones.**
+**Build your own MCP tools that run alongside the 35 built-in ones.**
 
 [Tools Reference](TOOLS.md) · [Configuration](CONFIGURATION.md) · [Architecture](ARCHITECTURE.md) · [FAQ](FAQ.md)
 
@@ -11,7 +11,7 @@
 ---
 
 > [!NOTE]
-> Custom tools have full access to your Rails environment - ActiveRecord, services, mailers, everything. They appear alongside the 45 built-in tools in both MCP and CLI.
+> Custom tools have full access to your Rails environment - ActiveRecord, services, mailers, everything. They appear alongside the 35 built-in tools in both MCP and CLI.
 
 ## Creating a custom tool
 
@@ -210,6 +210,12 @@ RailsAiContext.configure do |config|
 end
 ```
 
+The replacement is listed with the app's tools. The gem's own hints, the guide's steps and `rails_get_context` leave it out, since they would call it with the built-in's arguments.
+
+A custom `rails_get_config` listed in `skip_tools` replaces the built-in with its sections: the old names such as `rails_get_gems` then reach nothing, and no answer points at a section.
+
+A custom tool may also reuse one of those old names with the built-in left on. It is served as its own tool. The gem's own hints still mean the built-in section and print it as `rails_get_config(section:"gems")`.
+
 ## Tips
 
 - Custom tools have access to the full Rails environment - ActiveRecord, services, mailers, etc.

data/docs/FAQ.md

@@ -25,7 +25,7 @@ Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI. Each gets tailored
 No. The gem works three ways:
 1. **MCP server** - AI calls tools via the protocol (best experience)
 2. **Static files** - Generated context files (CLAUDE.md, .cursor/rules/, etc.)
-3. **CLI** - Same 45 tools from the terminal, no server needed
+3. **CLI** - Same 35 tools from the terminal, no server needed
 
 ### Is this safe for production?
 
@@ -55,7 +55,7 @@ Yes. [Copy-paste prompts](PROMPTS.md) has one prompt per setup: the usual instal
 
 ### Can I switch between Gemfile and standalone?
 
-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.
+Yes, freely. Both write the same context files and serve the same 35 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?
 
@@ -96,7 +96,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, in the generated context files' tool counts and lists too.
+Yes. See [Custom Tools](CUSTOM_TOOLS.md). Create an `MCP::Tool` subclass, register it via `config.custom_tools`, and it appears alongside the 35 built-in tools, in the generated context files' tool counts and lists too.
 
 ### Can I remove built-in tools?
 
@@ -110,7 +110,7 @@ The server, the CLI and the generated context files then leave them out alike, s
 
 ### 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.
+Every tool that takes `detail` takes the same three levels: `summary` (compact), `standard` (default), `full` (everything). The generated tool guide lists which tools take it. 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.
 
 ### What are `[VERIFIED]` and `[INFERRED]` tags?
 
@@ -120,7 +120,7 @@ Confidence tags from Prism AST parsing:
 
 ### Does the query tool support all databases?
 
-PostgreSQL, MySQL, and SQLite. Each gets database-specific safety mechanisms (read-only transactions, timeouts). See [Security](SECURITY.md).
+PostgreSQL, MySQL (with MariaDB) and SQLite. Each gets database-specific safety mechanisms (read-only transactions, timeouts). On any other adapter the tool answers with the adapter's name and runs nothing. See [Security](SECURITY.md).
 
 ---