rails-ai-context 5.16.2 → 5.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eea6e2b178ca5641f69ba9e78d20faa743e9639c706b2a8f847e60f854618b97
-  data.tar.gz: d688b1ac2b70859c0f2cdfecfb731bf0dda802743924664967f15680b4e9042f
+  metadata.gz: d4a8615479dc45f376da0873dbd18511feda7dafddad0e4c4c14039d26f8a4bf
+  data.tar.gz: 9fa06c53d871f05d30c284964777ebd15b26d44e87284e9232591e288ab47d29
 SHA512:
-  metadata.gz: bb7f069772ba9a58014b905eb68629cf8024b767c7cd01f409fbcd4418f252e04b7d0618c39160bcc7f2364e4535240372da158d267284f721fb365409216699
-  data.tar.gz: b22aac0130e6ee73829982f5dce526036c5e944ed2104f93664ec89868df7a1db26ea12412f5d3c6d73c7daa9a4421e2e61bf7054f67814fde12b9da70c3a206
+  metadata.gz: 38cc97cb5ec47c4ecd680ebb588169372d4d5a41c53dd0c59fde9260dc2bffad4f9830ffea5bc84cbef0079b167d522bccf77903104e5f6e5a03bd93aa85445d
+  data.tar.gz: 9987140ad897944e8def9318c6eedad861228f345465937062dba5e6ea36a2c47246d5c0697acce041afe7966b866d40bd289e67eeb1d582a6b220cc5c6dc147

data/.rubocop.yml

@@ -11,13 +11,6 @@ AllCops:
 Style/Documentation:
   Enabled: false
 
-Metrics/MethodLength:
-  Max: 25
-
-Metrics/ClassLength:
-  Max: 200
-
-Metrics/BlockLength:
-  Exclude:
-    - "spec/**/*"
-    - "*.gemspec"
+# rubocop-rails-omakase disables the whole Metrics department. Setting Max on a
+# disabled cop does not re-enable it, so size limits here would enforce nothing.
+# Turning it on would need ~40 existing files brought under the limit first.

data/AGENTS.md

@@ -0,0 +1,15 @@
+# rails-ai-context
+
+## Agent skills
+
+### Issue tracker
+
+Issues live as GitHub issues on `crisnahine/rails-ai-context`, driven with the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical roles, each label string equal to its name (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

data/CHANGELOG.md

@@ -5,6 +5,109 @@ 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.18.0] - 2026-08-09
+
+### Added
+
+- **Three new Prism listeners.** `ConfigAssignmentListener` reads
+  `config.key = value` and `config.key.subkey = value` in initializers, matching
+  the root anywhere in the chain so `Rails.application.config.assets.paths`
+  resolves too. `ComponentStructureListener` reads ViewComponent and Phlex
+  structure: `renders_one`/`renders_many`, slot methods, constant tables,
+  `case @ivar` variant branching, and `CONST[@ivar]` indexing.
+  `ClassDefinitionListener` reads class definitions with their superclass.
+- **`docs/INTROSPECTORS.md` documents the listener catalogue**, how to add a
+  listener, and when regex is the right tool instead of the AST.
+
+### Changed
+
+- **Auth, component, channel, controller, inflection and initializer reading
+  moved from regex to the AST.** Devise and Doorkeeper settings, devise-jwt
+  detection, ViewComponent and Phlex structure, Action Cable `identified_by` /
+  `stream_from` / `stream_for` / `periodically`, `rate_limit` options, custom
+  inflections, CORS origins, RSpec helper `include`s, `DatabaseCleaner.strategy`
+  and model class detection are all read structurally now. Formatting that used
+  to defeat the patterns (multi-line arguments, adjacent string literals,
+  `%i[]` and `%w[]` forms) is read correctly.
+- **A filter's `if:` condition reports the action it names.** A lambda has no
+  literal value, so `if: -> { action_name == "create" }` used to surface as
+  `[INFERRED]`; it now reads `action_name == "create"`. Same key, same type.
+- **`rate_limit_parsed[:within]` no longer keeps a trailing comma.**
+  `within: 1.minute, only: :create` returned `"1.minute,"` and now returns
+  `"1.minute"`.
+- **Initializer `setup_calls` sees more.** The old pattern only matched a line
+  beginning with `config.`, so `Rails.application.config.x = y` and multi-line
+  chains were missed.
+- **Every remaining regex over Ruby source carries a note** saying why regex is
+  right there: non-Ruby files, mixed-extension globs, vocabulary matching, or
+  scope the listeners cannot see.
+
+### Fixed
+
+- **Dead namespace-tracking loop removed from `RakeTaskIntrospector`**, which
+  walked every line of every `.rake` file and discarded the result.
+
+## [5.17.0] - 2026-08-09
+
+### Added
+
+- **`config.query_allowed_columns`** exempts a column name from the built-in
+  sensitive list used by `rails_query`. The rejection message told you to
+  subtract from `query_redacted_columns`, which could never work: that list is
+  unioned with a frozen suffix list, so an app with its own
+  `oauth_applications.secret` had no way to query it.
+
+### Fixed
+
+- **Documented security behaviour now matches the code.** The ReDoS timeout on
+  user-supplied regexes needs `Regexp.timeout`, which Ruby 3.1 does not have,
+  so `SECURITY.md` no longer promises it unconditionally on a version the gem
+  still supports. Layer 4 was documented as post-execution redaction; it has
+  rejected the query outright since 5.8.1, which is what the doc now says.
+- **`config.introspectors = %i[source]` no longer appears to be supported.**
+  `SourceIntrospector` was listed in the introspector table but is
+  infrastructure, not a registered introspector, so configuring it raised
+  `ConfigurationError`.
+- **Corrected documented defaults**, which had drifted: `sensitive_patterns` is
+  27 patterns not 8, `excluded_middleware` 25 not 24, `excluded_filters` 5 not
+  3, and the listener count is 21. `extra_app_paths` and
+  `instrumentation_include_arguments` were undocumented.
+- **Secondary database dumps report their own generated columns.** Parsing
+  `db/queue_schema.rb` read generated columns from the primary `db/schema.rb`
+  instead of the dump being parsed.
+- **Polymorphic foreign keys no longer always report a missing index.** The
+  compound check compared one joined string against two column names, so it
+  could never match an existing index.
+- **A column is no longer treated as indexed because a wider column name is.**
+  Index matching compared substrings, so an index on `user_id` counted as
+  covering `id`.
+
+### Changed
+
+- **schema.rb is read through one AST-backed reader.** `SchemaIntrospector`,
+  `PerformanceIntrospector` and `ConventionIntrospector` each parsed the dump
+  line by line with their own `create_table` regex; they now share
+  `SchemaReader`, built on the existing `SchemaDslListener`, as do the static
+  tier's table parse and the check-constraint, enum and generated-column
+  reads that each walked the dump separately.
+- **The static schema tier reports four things differently.** Where no live
+  connection is available and `db/schema.rb` is parsed instead: a `t.references`
+  or `t.belongs_to` column is reported by its foreign key name (`author_id`,
+  not `author`), which is what the live tier has always reported; a column
+  default written as a proc reports its source rather than being omitted; a
+  default split across lines is picked up; and an expression index declared at
+  the top level is flagged `expression: true`, as an in-table one already was.
+- **`rails_validate`'s Rails-aware rules moved to `ValidateSemantics`.** The
+  tool entry point kept syntax validation and orchestration; the 15 lint rules
+  now live in their own class. Behaviour is unchanged.
+- **`detail` has a type.** `DetailLevel` defines the three levels, their
+  ordering and normalization. An unrecognised value now reads as `standard`
+  rather than silently selecting whichever branch happened to be last.
+- **Soft-delete detection prefers the schema.** A `deleted_at` column in the
+  dump now drives the `soft_delete` convention, instead of matching the word
+  anywhere in model source. Apps dumping `structure.sql` keep the old source
+  match, and the `acts_as_paranoid` / `discard` macro check is unchanged.
+
 ## [5.16.2] - 2026-07-17
 
 ### Fixed

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/     # 39 introspectors (schema, models, routes, etc.)
-├── tools/             # 38 MCP tools with detail levels and pagination
+├── tools/             # 39 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)
@@ -51,11 +51,13 @@ Listeners extract specific concerns (associations, validations, etc.) from the A
 1. Create `lib/rails_ai_context/introspectors/listeners/your_listener.rb` inheriting from `BaseListener`
 2. Implement `on_call_node_enter(node)` and/or `on_def_node_enter(node)` - only the events your concern needs
 3. Use `confidence_for(node)` from `BaseListener` to tag results `[VERIFIED]` or `[INFERRED]`
-4. Store results in `@results` (accessed via `#results`)
-5. Register the key/class pair in `SourceIntrospector::LISTENER_MAP`
-6. Write specs in `spec/lib/rails_ai_context/introspectors/listeners/your_listener_spec.rb`
+4. Store results in `@results` (accessed via `#results`) as plain hashes, never Prism nodes
+5. If your listener needs an event `SourceIntrospector.register_listener` doesn't already wire up, add it there
+6. Register the key/class pair in `SourceIntrospector::LISTENER_MAP` only if the listener should run on every model walk; listeners used by one introspector are passed to `SourceIntrospector.walk(path, key => Listener)` at the call site instead
+7. Write specs in `spec/lib/rails_ai_context/introspectors/listeners/your_listener_spec.rb`
+8. Add a row to the listener catalogue in `docs/INTROSPECTORS.md`
 
-See existing listeners in `lib/rails_ai_context/introspectors/listeners/` for reference patterns.
+See existing listeners in `lib/rails_ai_context/introspectors/listeners/` for reference patterns, and `docs/INTROSPECTORS.md` for the catalogue and the AST-vs-regex rule.
 
 ## Adding a CLI Tool Interface
 

data/app/controllers/rails_ai_context/mcp_controller.rb

@@ -29,7 +29,14 @@ module RailsAiContext
     def handle
       status_code, rack_headers, body = self.class.mcp_transport.handle_request(request)
       self.status = status_code
-      rack_headers.each { |k, v| response.headers[k] = v }
+      rack_headers.each do |k, v|
+        # mcp >= 1.0 returns Rack 3-style lowercase header keys. Rails 7.0's
+        # response header hash is case-sensitive (Rack 2), so a lowercase
+        # "content-type" never registers and Rails falls back to text/html on
+        # an otherwise valid JSON body. Write it with the canonical case.
+        key = k.casecmp("content-type").zero? ? "Content-Type" : k
+        response.headers[key] = v
+      end
 
       if body.respond_to?(:each)
         # Plain enumerable body (initialize, errors, JSON mode): join to a

data/docs/ARCHITECTURE.md

@@ -25,8 +25,8 @@ graph TD
 
         subgraph engine["Introspection Engine"]
             direction LR
-            I["Introspectors\n31 modules\nPresets\nCached"]
-            AST["AST Engine\nPrism\n20 listeners\nConfidence tags"]
+            I["Introspectors\n39 modules\nPresets\nCached"]
+            AST["AST Engine\nPrism\n24 listeners\nConfidence tags"]
             H["Hydration Layer\nSchema hints\ninjected into\ntool responses"]
         end
 
@@ -73,7 +73,7 @@ sequenceDiagram
     alt cache hit (TTL + fingerprint valid)
         Cache-->>TR: cached context
     else cache miss
-        Cache->>App: introspect (31 modules)
+        Cache->>App: introspect (39 modules)
         App-->>Cache: structured data
         Cache-->>TR: fresh context
     end
@@ -115,8 +115,8 @@ The `Introspector` orchestrator runs configured introspectors and merges results
 **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
-- **SourceIntrospector** - Single-pass Prism Dispatcher walks the AST once, feeds events to all 7 listeners simultaneously
-- **7 Listeners** - Associations, Validations, Scopes, Enums, Callbacks, Macros, Methods
+- **SourceIntrospector** - Single-pass Prism Dispatcher walks the AST once, feeding every registered listener simultaneously
+- **21 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
 - **Confidence** - Every result carries `[VERIFIED]` (static literals) or `[INFERRED]` (dynamic expressions)
 
 ### Tool Registry (`lib/rails_ai_context/tools/base_tool.rb`)

data/docs/CONFIGURATION.md

@@ -91,8 +91,8 @@ preset: full
 | `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_filters` | Array | 3 framework filters | Controller filters to skip |
-| `excluded_middleware` | Array | 24 framework middleware | Middleware to skip in listing |
+| `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 |
 | `excluded_association_names` | Array | 7 framework associations | Association names to hide from model output |
 | `excluded_concerns` | Array of Regex | Framework concerns | Concerns to skip (supports regex) |
@@ -116,6 +116,16 @@ preset: full
 | `search_extensions` | Array | `["rb", "js", "erb", "yml", "yaml", "json", "ts", "tsx", "vue", "svelte", "haml", "slim"]` | File extensions to search |
 | `concern_paths` | Array | `["app/models/concerns", "app/controllers/concerns"]` | Paths to scan for concerns |
 | `frontend_paths` | Array | `nil` (auto-detect) | Override frontend file paths |
+| `extra_app_paths` | Array | `[]` | Extra directories under the app root to treat as application code |
+
+### Instrumentation
+
+| Option | Type | Default | Description |
+|:-------|:-----|:--------|:------------|
+| `instrumentation_include_arguments` | Boolean | `false` | Include tool arguments in instrumentation events |
+
+> [!WARNING]
+> `instrumentation_include_arguments` forwards raw tool arguments to your subscribers, which for `rails_query` means the SQL text and for other tools can mean environment variable names. Leave it off unless your subscriber is as trusted as your logs.
 
 ### Database Query Safety
 
@@ -123,7 +133,8 @@ preset: full
 |:-------|:-----|:--------|:-----------|:------------|
 | `query_timeout` | Integer | `5` | - | SQL query timeout in seconds |
 | `query_row_limit` | Integer | `100` | 1–1000 | Maximum rows returned |
-| `query_redacted_columns` | Array | 10+ patterns | - | Column names/suffixes to redact |
+| `query_redacted_columns` | Array | 14 patterns | - | Column names that cause a query to be rejected |
+| `query_allowed_columns` | Array | `[]` | - | Column names exempted from the built-in sensitive list |
 | `allow_query_in_production` | Boolean | `false` | - | Allow `rails_query` tool in production |
 
 ### Logs
@@ -136,7 +147,7 @@ preset: full
 
 | Option | Type | Default | Description |
 |:-------|:-----|:--------|:------------|
-| `sensitive_patterns` | Array | 8 patterns | File patterns blocked from search/read (`.env*`, `*.key`, `*.pem`, `credentials.yml.enc`, etc.) |
+| `sensitive_patterns` | Array | 27 patterns | File patterns blocked from search/read (`.env*`, `*.key`, `*.pem`, `config/credentials.yml.enc`, `.ssh/*`, etc.) |
 
 ### Extensibility
 

data/docs/INTROSPECTORS.md

@@ -94,7 +94,6 @@ end
 
 | Introspector | Key | What it extracts |
 |:-------------|:----|:-----------------|
-| SourceIntrospector | `:source` | Prism AST: associations, validations, scopes, enums, callbacks, macros, methods |
 | MigrationIntrospector | `:migrations` | Migration files, versions, reversibility |
 | SeedsIntrospector | `:seeds` | Seed file analysis |
 | DatabaseStatsIntrospector | `:database_stats` | Table sizes, row counts, index stats |
@@ -170,9 +169,11 @@ These introspectors map directly onto [`RAILS_NERVOUS_SYSTEM.md`](../RAILS_NERVO
 
 ## AST-based introspection
 
-The **SourceIntrospector** uses Prism AST parsing for model analysis. It runs a single-pass Dispatcher that walks the AST once and feeds events to 7 listeners simultaneously:
+The **SourceIntrospector** uses Prism AST parsing for model analysis. It is infrastructure shared by the introspectors above rather than an introspector you can enable: there is no `:source` key for `config.introspectors`.
 
-### 7 Prism listeners
+It runs a single-pass Dispatcher that walks the AST once and feeds events to all registered listeners simultaneously. Model analysis uses the seven below by default; the rest are used through targeted walks (schema dumps, migrations, Gemfiles, rake tasks, initializers, components, and so on).
+
+### The 7 default Prism listeners
 
 | Listener | What it detects |
 |:---------|:---------------|
@@ -184,6 +185,51 @@ The **SourceIntrospector** uses Prism AST parsing for model analysis. It runs a
 | MacrosListener | `encrypts`, `normalizes`, `delegate`, `has_secure_password`, `serialize`, `store`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `generates_token_for`, `attribute` |
 | MethodsListener | `def`/`def self.`, visibility tracking, parameter extraction, `class << self` |
 
+### The targeted-walk listeners
+
+Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file needs reading. Several take arguments, so one class serves many callers.
+
+| Listener | What it detects |
+|:---------|:---------------|
+| GenericMacroListener | Any receiver-less macro you name: `GenericMacroListener.new(:devise, :rate_limit)`. Returns args, values (with a source-slice fallback), options, option values and option nodes |
+| ChainedCallListener | Calls on a receiver: `ChainedCallListener.new(:includes)`, or `receiver: :inflect` to pin the receiver. Reports the receiver name |
+| ConfigAssignmentListener | `config.key = value` and `config.a.b = value` in initializers, plus bare `config.jwt do ... end` section references. Takes a root name (`:config` by default, e.g. `:DatabaseCleaner`) |
+| ClassDefinitionListener | Class definitions with their superclass, namespaces resolved |
+| ComponentStructureListener | ViewComponent and Phlex structure: `renders_one`/`renders_many`, slot methods, hash/array constant tables, `case @ivar` variant branching, `CONST[@ivar]` indexing |
+| MiddlewareConfigListener | `config.middleware.use` / `insert_before` / `insert_after` |
+| SchemaDslListener | `schema.rb`: `create_table`, `t.string`, `t.index`, `add_foreign_key`, `create_enum` |
+| MigrationDslListener | Migration DSL: `create_table`, `add_column`, `add_index`, `add_reference`, and friends |
+| RoutesDslListener | `config/routes.rb`, resolving namespace/scope/resources nesting into flat routes |
+| MountListener | `mount Sidekiq::Web, at: "/sidekiq"` and the hash form |
+| GemfileDslListener | `gem "name", "version"` and `group :development do ... end` |
+| RakeTaskDslListener | `namespace`, `desc`, `task` in `.rake` files |
+| EnvAccessListener | `ENV["KEY"]`, `ENV.fetch("KEY")`, `ENV.fetch("KEY", default)` |
+| MongoidFieldsListener | Mongoid `field`, embedded relations, custom collection names |
+| MailboxRoutingListener | Action Mailbox `routing` and processing callbacks |
+| ModelReferenceListener | Model constants used in controllers: `Post.find`, `params.require(:post)`, ivar writes |
+| VariantCallListener | `variant` calls (ChainedCallListener with `:variant` preset) |
+
+### Adding a listener
+
+1. Subclass `BaseListener` in `lib/rails_ai_context/introspectors/listeners/`. Use its helpers rather than re-reading nodes: `extract_symbol_args`, `extract_keyword_options`, `extract_arg_values` (source-slice fallback for expressions like `2.hours`), `extract_keyword_sources`, `extract_keyword_nodes`, `keyword_hash`, `constant_path_string`.
+2. Implement the `on_*_node_enter` hooks you need and push plain hashes onto `@results`. Never return Prism nodes as the result itself; `option_nodes` is the one deliberate exception, for callers that must inspect an expression's shape.
+3. Register the event in `SourceIntrospector.register_listener` if it is not already in the list (call, def, class, module, block, singleton class, case, constant write).
+4. Add a spec of the same name under `spec/lib/rails_ai_context/introspectors/listeners/`.
+5. Add a row to the table above.
+
+### Choosing between AST and regex
+
+Use the AST when the thing you want **is** a Ruby construct: a macro call and its arguments, a method definition, a class and its superclass, an assignment, a constant, a `case`. If you find yourself running a regex over text you already parsed, that is a parse of a parse. Fix it at the node.
+
+Regex is the right tool, and stays, for:
+
+- **Files that are not Ruby.** `Gemfile.lock`, YAML (`database.yml`, `sidekiq.yml`, fixtures), `structure.sql`, Dockerfiles, ERB, HAML, Slim, JavaScript.
+- **Mixed-extension globs.** A view scan spanning ERB and Phlex `.rb` needs one matcher, or the two halves drift apart.
+- **Vocabulary classification.** "Does this middleware body talk about auth?" is about words, not structure; no node carries it.
+- **Anything the listeners cannot scope.** Tying a call to the enclosing action or `namespace` block needs block scope the listeners do not track, so those fall back to line scanning.
+
+Every remaining regex over `.rb` content carries a one-line comment saying which of these it is. If you add one without a reason, convert it instead.
+
 ### Confidence tagging
 
 Every AST result carries a confidence tag:

data/docs/SECURITY.md

@@ -33,8 +33,9 @@ flowchart LR
     L1 -->|"Blocked:\nINSERT, DROP,\nUNION SELECT..."| R1[Rejected]
     L1 -->|SELECT only| L2{Layer 2\nDatabase Read-Only}
     L2 -->|"SET TRANSACTION\nREAD ONLY\n+ timeout"| L3{Layer 3\nRow Limit}
-    L3 -->|"Cap: 1000 rows\nDefault: 100"| L4{Layer 4\nColumn Redaction}
-    L4 -->|"password_digest\napi_key → [REDACTED]"| OK[Safe Result]
+    L3 -->|"Cap: 1000 rows\nDefault: 100"| L4{Layer 4\nSensitive Columns}
+    L4 -->|"names password_digest,\napi_key, ..."| R1
+    L4 -->|"no sensitive column"| OK[Safe Result]
 
     style R1 fill:#e74c3c,stroke:#c0392b,color:#fff
     style OK fill:#27ae60,stroke:#1e8449,color:#fff
@@ -75,13 +76,19 @@ All queries execute inside a transaction, then rollback (even if they could writ
 - Configurable: `config.query_row_limit` (hard cap: 1000)
 - Applied as `LIMIT` clause appended to query
 
-### Layer 4 - Column redaction
+### Layer 4 - Sensitive column rejection
 
-Sensitive column values are replaced with `[REDACTED]`:
+A query that names a sensitive column is **rejected before execution**, not redacted after it:
 
 **Default redacted patterns:** `password_digest`, `encrypted_password`, `password_hash`, `reset_password_token`, `confirmation_token`, `unlock_token`, `otp_secret`, `session_data`, `secret_key`, `api_key`, `api_secret`, `access_token`, `refresh_token`, `jti`
 
-Redaction matches by **name** and **suffix** - `SELECT password_digest AS pd` still redacts `pd` because the column name is tracked through the query result.
+Matching is by name, case-insensitive and word-bounded, against both the defaults above and `config.query_redacted_columns`. `SELECT password_digest AS pd FROM users` is blocked outright: post-execution redaction reads the column names the database returns, which the caller controls through aliases and expressions, so it cannot be relied on.
+
+If one of your own columns merely looks sensitive (an `oauth_applications.secret`, say), exempt it by name:
+
+```ruby
+config.query_allowed_columns = %w[secret]
+```
 
 ### Environment guard
 
@@ -96,15 +103,16 @@ The `rails_search_code` and file-reading tools block access to sensitive files:
 
 ### Default patterns
 
-```
-.env*
-*.key
-*.pem
-credentials.yml.enc
-master.key
-secret_key_base
-config/secrets.yml
-config/credentials/*
+```text
+.env .env.*
+config/master.key
+config/credentials.yml.enc config/credentials/*.yml.enc
+config/database.yml config/secrets.yml
+config/cable.yml config/storage.yml
+config/mongoid.yml config/redis.yml
+*.pem *.key *.p12 *.pfx *.jks *.keystore
+**/id_rsa **/id_ed25519 **/id_ecdsa **/id_dsa
+.ssh/* .aws/credentials .aws/config .netrc .pgpass .my.cnf
 ```
 
 ### AI context file exclusions
@@ -158,7 +166,7 @@ File type parameters accept only alphanumeric characters.
 
 ## Regex injection prevention
 
-User-supplied regex patterns have a 1-second timeout:
+On Ruby 3.2 and newer, user-supplied regex patterns have a 1-second timeout:
 
 ```ruby
 Regexp.new(pattern, timeout: 1)
@@ -166,6 +174,9 @@ Regexp.new(pattern, timeout: 1)
 
 Complex patterns that would cause catastrophic backtracking raise `RegexpError` instead of hanging.
 
+> [!WARNING]
+> `Regexp.timeout` does not exist on Ruby 3.1, which this gem still supports. There the timeout is skipped, and a pattern crafted to backtrack catastrophically can hang the process serving the tool. If you expose `rails_search_code` to input you do not control, run it on Ruby 3.2 or newer.
+
 ---
 
 ## Safe file reading
@@ -207,7 +218,7 @@ When using HTTP transport (Rack middleware or McpController):
 
 - **Default bind**: `127.0.0.1` (localhost only - not exposed to network)
 - **`auto_mount` is `false` by default** - must be explicitly enabled
-- **Doctor checks** warn if `auto_mount` is true (security flag)
+- **Doctor checks** fail if `auto_mount` is true in production, and report it as enabled elsewhere
 
 The McpController uses thread-safe transport initialization with mutex synchronization.
 

data/docs/agents/domain.md

@@ -0,0 +1,38 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+This repo is **single-context**: one `CONTEXT.md` and one `docs/adr/` at the root.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root: the glossary and domain overview.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-example-decision.md
+│   └── 0002-another-decision.md
+├── lib/
+└── spec/
+```
+
+If this repo ever splits into multiple bounded contexts, add a root `CONTEXT-MAP.md` pointing at one `CONTEXT.md` per context, and update this file.
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because..._

data/docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

data/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

data/lib/rails_ai_context/configuration.rb

@@ -21,7 +21,7 @@ module RailsAiContext
       sensitive_patterns search_extensions concern_paths frontend_paths extra_app_paths
       max_file_size max_test_file_size max_schema_file_size max_view_total_size
       max_view_file_size max_search_results max_validate_files
-      query_timeout query_row_limit query_redacted_columns allow_query_in_production
+      query_timeout query_row_limit query_redacted_columns query_allowed_columns allow_query_in_production
       log_lines introspectors
       hydration_enabled hydration_max_hints
       instrumentation_include_arguments
@@ -244,6 +244,7 @@ module RailsAiContext
     attr_accessor :query_timeout              # Statement timeout in seconds (default: 5)
     attr_accessor :query_row_limit            # Max rows returned (default: 100, hard cap: 1000)
     attr_accessor :query_redacted_columns     # Column names whose values are redacted in output
+    attr_accessor :query_allowed_columns      # Column names to exempt from the built-in sensitive list
     attr_accessor :allow_query_in_production  # Allow rails_query in production (default: false)
 
     # Log reading settings (rails_read_logs)
@@ -317,6 +318,7 @@ module RailsAiContext
         otp_secret session_data secret_key
         api_key api_secret access_token refresh_token jti
       ]
+      @query_allowed_columns    = []
       @allow_query_in_production = false
       @log_lines                = 50
       @hydration_enabled        = true

data/lib/rails_ai_context/detail_level.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  # The `detail` parameter shared by most tools. Values arrive over the wire as
+  # strings, so this stays string-compatible rather than wrapping them; what it
+  # adds is one definition of the allowed values and an ordering, so callers can
+  # ask "is this at least standard?" instead of comparing literals.
+  module DetailLevel
+    SUMMARY  = "summary"
+    STANDARD = "standard"
+    FULL     = "full"
+
+    ALL     = [ SUMMARY, STANDARD, FULL ].freeze
+    DEFAULT = STANDARD
+
+    ORDER = { SUMMARY => 0, STANDARD => 1, FULL => 2 }.freeze
+
+    def self.valid?(detail)
+      ALL.include?(detail.to_s)
+    end
+
+    # Unknown values read as the default rather than falling through to
+    # whichever branch happens to be last.
+    def self.normalize(detail)
+      valid?(detail) ? detail.to_s : DEFAULT
+    end
+
+    def self.at_least?(detail, minimum)
+      ORDER.fetch(normalize(detail)) >= ORDER.fetch(minimum)
+    end
+
+    def self.full?(detail)
+      normalize(detail) == FULL
+    end
+
+    def self.summary?(detail)
+      normalize(detail) == SUMMARY
+    end
+  end
+end

data/lib/rails_ai_context/introspectors/active_storage_introspector.rb

@@ -112,6 +112,7 @@ module RailsAiContext
           next false unless Dir.exist?(dir)
           Dir.glob(File.join(dir, "**/*.{erb,haml,slim,js,ts,jsx,tsx,mjs,rb}")).any? do |f|
             next false if File.directory?(f)
+            # The glob spans ERB, JS and Ruby, so one text scan covers them all.
             (RailsAiContext::SafeFile.read(f) || "").match?(/direct.upload|DirectUpload|direct_upload/)
           end
         end

data/lib/rails_ai_context/introspectors/active_support_introspector.rb

@@ -102,6 +102,8 @@ module RailsAiContext
           # and would produce non-deterministic output on large monorepos.
           Dir.glob(File.join(dir, "**/*.rb")).sort.first(2000).each do |path|
             content = RailsAiContext::SafeFile.read(path) or next
+            # Mention of the class anywhere counts, so a text scan over 2000
+            # files beats parsing each one. Regex stays.
             next unless content.match?(/MessageEncryptor|MessageVerifier/)
             relative = path.sub("#{root}/", "")
             hits << { file: relative, encryptor: content.include?("MessageEncryptor"), verifier: content.include?("MessageVerifier") }