rails-ai-context 5.16.2 → 5.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eea6e2b178ca5641f69ba9e78d20faa743e9639c706b2a8f847e60f854618b97
-  data.tar.gz: d688b1ac2b70859c0f2cdfecfb731bf0dda802743924664967f15680b4e9042f
+  metadata.gz: ebb8d4e0ebed93183c0c019071ee63d097fb8c7495f551393991000aa5d06e7b
+  data.tar.gz: 2141cf0a281a173da2f0fa34927be843f93600ced5cdd67ccd6eb4aeef261ce0
 SHA512:
-  metadata.gz: bb7f069772ba9a58014b905eb68629cf8024b767c7cd01f409fbcd4418f252e04b7d0618c39160bcc7f2364e4535240372da158d267284f721fb365409216699
-  data.tar.gz: b22aac0130e6ee73829982f5dce526036c5e944ed2104f93664ec89868df7a1db26ea12412f5d3c6d73c7daa9a4421e2e61bf7054f67814fde12b9da70c3a206
+  metadata.gz: e1bdda115ee2c82a43af9f6389ad18204629539e5867db0ae36d8c4fe86f50547084315470ed5842adccbced095026e2a220f32626d1c1e43600b595d7224afb
+  data.tar.gz: 197fe45172ce6888fd89ee63ecc505f5e014f1b3c759a918a7244025958ce9d17801f4bf1a0ac3ce401a93063b0f3d75998b4ec485f6bdbe4df9449be333920d

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,67 @@ 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.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)

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\n21 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 other fourteen listener classes are used through targeted walks (schema dumps, migrations, Gemfiles, rake tasks, initializers, and so on), for 21 in total.
+
+### The 7 default Prism listeners
 
 | Listener | What it detects |
 |:---------|:---------------|

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/convention_introspector.rb

@@ -102,21 +102,21 @@ module RailsAiContext
 
           # STI detection via AST: extract parent class from ClassNode, check schema
           app_model_names = model_files.filter_map { |f| File.basename(f, ".rb").camelize }
-          schema_path = File.join(root, "db/schema.rb")
-          schema_content = File.exist?(schema_path) ? (RailsAiContext::SafeFile.read(schema_path) || "") : ""
+          schema = SchemaReader.new(File.join(root, "db/schema.rb"))
+          schema_readable = schema.tables.any?
 
           has_sti_subclass = false
           has_inheritance_column = false
           has_current_attributes = false
-          has_deleted_at = false
 
           model_files.first(500).each do |f|
             parent = extract_parent_class(f)
             if parent && app_model_names.include?(parent) && parent != "ApplicationRecord"
               parent_table = parent.underscore.pluralize
-              if schema_content.match?(/create_table\s+"#{Regexp.escape(parent_table)}".*?t\.\w+\s+"type"/m)
-                has_sti_subclass = true
-              end
+              # Only the dump says whether the parent table carries a type
+              # column, so an unreadable schema leaves this to the
+              # inheritance_column check below rather than a source guess.
+              has_sti_subclass = true if schema_readable && schema.column?(parent_table, "type")
             end
 
             superclass = extract_superclass_path(f)
@@ -127,12 +127,15 @@ module RailsAiContext
               inh: -> { Listeners::ChainedCallListener.new(:inheritance_column=) }
             })
             has_inheritance_column = true if inheritance_check[:inh].any?
+          end
 
-            # deleted_at is a keyword/content check, not structural -- keep regex
-            unless has_deleted_at
-              src = RailsAiContext::SafeFile.read(f)
-              has_deleted_at = true if src&.match?(/deleted_at/)
-            end
+          # A soft-delete column is a schema fact, so prefer the dump. Apps on
+          # structure.sql have no schema.rb to read, and fall back to the
+          # looser source match.
+          has_deleted_at = if schema_readable
+            schema.any_column?("deleted_at")
+          else
+            model_files.first(500).any? { |f| RailsAiContext::SafeFile.read(f)&.match?(/deleted_at/) }
           end
 
           patterns << "sti" if has_inheritance_column || has_sti_subclass

data/lib/rails_ai_context/introspectors/engine_introspector.rb

@@ -4,7 +4,7 @@ module RailsAiContext
   module Introspectors
     # Discovers mounted Rails engines and Rack apps from config/routes.rb.
     # Identifies well-known engines and provides context about what each does.
-    class EngineIntrospector # rubocop:disable Metrics/ClassLength
+    class EngineIntrospector
       attr_reader :app
 
       KNOWN_ENGINES = {

data/lib/rails_ai_context/introspectors/gem_introspector.rb

@@ -9,7 +9,6 @@ module RailsAiContext
 
       # Known gems that significantly affect how the app works.
       # The AI needs to know about these to give accurate advice.
-      # rubocop:disable Metrics/CollectionLiteralLength
       NOTABLE_GEMS = {
         # Auth
         "devise"          => { category: :auth, note: "Authentication via Devise. Check User model for devise modules." },
@@ -147,7 +146,6 @@ module RailsAiContext
         "bullet"          => { category: :utilities, note: "N+1 query detection via Bullet." },
         "rack-attack"     => { category: :utilities, note: "Rate limiting and throttling via Rack::Attack." }
       }.freeze
-      # rubocop:enable Metrics/CollectionLiteralLength
 
       def initialize(app)
         @app = app

data/lib/rails_ai_context/introspectors/listeners/schema_dsl_listener.rb

@@ -179,10 +179,21 @@ module RailsAiContext
             column_type: node.name.to_s,
             name:        col_name,
             options:     options,
+            # A proc default (`default: -> { "now()" }`) has no literal value,
+            # so keep its source for callers that report defaults verbatim.
+            default_source: default_source(node),
             location:    node.location.start_line
           }
         end
 
+        def default_source(node)
+          args = node.arguments&.arguments || []
+          assoc = args.grep(Prism::KeywordHashNode)
+                      .flat_map(&:elements)
+                      .find { |e| e.is_a?(Prism::AssocNode) && extract_key(e.key) == :default }
+          assoc&.value&.slice
+        end
+
         def extract_index(node)
           args = node.arguments&.arguments || []
           columns = resolve_index_columns(args.first)