RubyGems - rails-ai-bridge - Versions diffs - 3.0.0 → 3.1.0 - Mend

rails-ai-bridge 3.0.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (43) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57b5b16d9e952041e81f752dc1a31049d576d63ff62ea99286508ae20f377043
-  data.tar.gz: 65f2dd6a121e3b3ac7b3ad23e081a5426d1d7e9212e65574db6dbb130c4ef583
+  metadata.gz: 3f1a7f2bdb4fc3a64a5a2647b829a154df6a3c39bc01bcb98e806fb9aaa713c8
+  data.tar.gz: 4d6e82d276a1398100767639804da6109cbbd4ec780c7e448d27a84591186874
 SHA512:
-  metadata.gz: '09c4d837c7fb6166f2d8f1480010a509404875b1080be01406f9efe886f17e8fbe8def7d28afcfc76e64a98ed4d56809f9c5acf4da601f11b954008451247e04'
-  data.tar.gz: d85e4f45e131a8f4475f3fb48171fa268927d8a7ee78df599e482278580fb9100b7f0f5bcc5bd06a2563cdfad83ee69a73a98d6e69e4b652a6de2e81e051b4b0
+  metadata.gz: 1b7401347104c6f8871998e485d1c58828b15b5f487bd4ea0cc080cf6d0f953e0d63a0b6a4b1dfa485d84c691b89a9224444c1d0da1761c7bb3f5f365213c427
+  data.tar.gz: 0b141263596fc4b10fab84f2dfca832ea0c371c21f1de912097e4a20bbf1b034cb736cd77938b6a507dea0302eb41452308eb4dd9f7fd019a5a57f4d0bd35b2b

data/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,61 @@ 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).
+## [3.1.0] - 2026-05-01
+### Added
+- **Task-relevance ordering for compact context** — model lists now rank by semantic tier,
+  structural complexity, route density, recent migrations, and optional database-size signals
+  instead of relying mostly on alphabetical order.
+- **Endpoint focus summaries** — compact stack/project context now surfaces the busiest route
+  targets with direct `rails_get_routes(controller:"...", detail:"summary")` drill-down hints.
+- **Database size buckets** — the optional `database_stats` introspector now annotates PostgreSQL
+  approximate row counts as `small`, `medium`, `large`, or `hot`; generated context shows these
+  hints only when `database_stats` is explicitly enabled.
+- **Context quality matrix specs** — generated-output acceptance coverage now exercises standard
+  CRUD, large-schema, API-only, Hotwire, engine-style, and regulated/no-domain-metadata profiles,
+  with real Rails-shaped fixture trees for API-only, Hotwire, large-schema, engine-style, and
+  regulated/no-domain-metadata apps plus bounded output and secret-adjacent regression checks.
+- **Serialization benchmark guard** — large-fixture compact serialization now has a small
+  performance budget to catch accidental context bloat.
+- **MCP large-payload stability checks** — route/schema tool specs now exercise truncation,
+  pagination, next-offset guidance, and section-cache reuse against large payloads.
+### Changed
+- **Claude rules** — `.claude/rules/rails-context.md` now includes bounded endpoint focus and
+  route drill-down guidance; `.claude/rules/rails-schema.md` adds optional size-bucket hints.
+- **Route MCP pagination** — `rails_get_routes` standard/full output now includes a next
+  `offset` hint when more route rows are available.
+- **Secret-bearing config paths** — generated context, `rails_get_conventions`, and the
+  `rails://conventions` MCP resource now omit dotenv files, Rails credentials files, secret/private
+  directories, master keys, and private key material from config-file listings while preserving
+  safe operational files such as `config/database.yml`.
+- **Convention detection with custom Rails paths** — architecture and directory-structure signals
+  now honor configured Rails paths for directories such as `app/models` and `app/services` while
+  keeping generated output on logical names instead of absolute local paths.
+- **Model introspection with custom Rails paths** — ActiveRecord source-derived metadata and
+  `non_ar_models` discovery now resolve every configured `app/models` path, so apps that place
+  domain models outside the conventional directory still generate useful model context.
+- **Controller and frontend introspection with custom Rails paths** — controller source metadata,
+  view summaries, Stimulus controllers, and Turbo frame/stream/broadcast detection now honor
+  configured `app/controllers`, `app/views`, `app/helpers`, `app/components`, and
+  `app/javascript/controllers` paths where Rails exposes them.
+- **View detail access with custom Rails paths** — `rails_get_view(path:"...")` and
+  `rails://views/{path}` now resolve files through configured `app/views` paths while preserving
+  traversal protection.
+- **Specialized introspectors with custom Rails paths** — Active Storage, Action Text,
+  CurrentAttributes, API serializers/GraphQL/versioning/rate-limit scans, Devise,
+  `has_secure_password`, Rails auth, Pundit, and CanCanCan detection now honor configured logical
+  Rails paths instead of assuming only conventional `app/*` directories.
+- **Copilot, Codex, Cursor, Windsurf, and shared compact serializers** — key model sections now
+  use the same relevance score so assistants see core, routed, recently changed, or hot-domain
+  models before lower-signal supporting models.
+- **Generated override guidance** — compact instructions no longer include the literal
+  omit-merge marker string unless reading the actual override stub; user-facing docs still explain
+  how to activate `config/rails_ai_bridge/overrides.md`.
 ## [3.0.0] - 2026-04-28
 ### Added

data/README.md CHANGED Viewed

@@ -11,27 +11,42 @@
 ---
-## Why this matters
+## What this gem does
-LLMs are powerful, but unreliable in real-world codebases without structure. They guess architecture, miss conventions, and waste tokens trying to understand your app.
+AI coding tools are much better when they know your Rails app before they start editing. Without that context, they guess table names, miss routes, ignore conventions, and spend tokens rediscovering structure your app already has.
-rails-ai-bridge fixes this by giving AI assistants **explicit, structured knowledge of your Rails app upfront**, plus on-demand introspection when deeper detail is needed.
+rails-ai-bridge turns a Rails app into an AI-readable project map:
-The result:
-- More accurate code generation
-- Faster time to first useful response
-- Less token waste on exploration
-- More predictable, production-ready outputs
+- **Static context files** give assistants an immediate overview of your app, conventions, schema shape, routes, and important models.
+- **A read-only MCP server** lets assistants ask for exact details only when needed, such as one model, one table, one controller, or one route group.
+- **Assistant-specific output** keeps Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, and JSON consumers aligned without making you hand-write context files.
-This shifts AI from “helpful autocomplete” → **reliable engineering assistant**
+The goal is simple: help AI assistants produce code that fits your Rails app instead of generic Rails code.
-## The problem
+## Start here
-You open Claude Code, Cursor, or Codex and ask it to add a feature. It generates code that ignores your schema, your Devise setup, your existing enums, and the conventions already in your app.
+Use the README as the shortest path to understanding and setup. Jump to deeper docs only when you need details.
-**rails-ai-bridge fixes this permanently** by introspecting your Rails app and exposing that structure through compact, assistant-specific files plus a **live MCP server** with read-only `rails_*` tools ([Model Context Protocol](https://modelcontextprotocol.io)).
+| You want to... | Read this first |
+|---|---|
+| Understand the idea in 3 minutes | [How it works](#how-it-works) |
+| Install and generate files | [Quick start](#quick-start) |
+| Check what the AI learns | [What Your AI Learns](#what-your-ai-learns) |
+| Choose `:standard`, `:full`, or opt-ins | [Pick the right preset for your app](#pick-the-right-preset-for-your-app) |
+| Use MCP safely | [MCP Server Setup](#mcp-server-setup) and [mcp-security.md](docs/mcp-security.md) |
+| Improve day-to-day AI results | [Best Practices](docs/BEST_PRACTICES.md) |
-> **[Full Guide](docs/GUIDE.md)** — every command, option, and MCP parameter.
+## When this helps
+This is useful when you want an AI assistant to work inside a real Rails codebase, especially if the app has:
+- More than a few models or routes
+- Existing conventions that new code should follow
+- Auth, background jobs, API endpoints, Hotwire, engines, or service objects
+- A team that wants shared AI guidance committed to the repo
+- Large schemas where dumping everything into context would be noisy
+For tiny apps or one-off scripts, manual context may be enough. For team Rails apps, generated context plus MCP gives the assistant a much better starting point.
 ---
@@ -41,25 +56,35 @@ You open Claude Code, Cursor, or Codex and ask it to add a feature. It generates
 flowchart LR
   app[Rails_app]
   intro[Introspectors]
+  files[Static_context_files]
   mcp[MCP_server]
   clients[AI_clients]
-  app --> intro --> mcp --> clients
+  app --> intro
+  intro --> files
+  intro --> mcp
+  files --> clients
+  mcp --> clients
 ```
-1. **Up to 27 introspectors** in the `:full` preset scan schema, models, routes, controllers, jobs, gems, conventions, and more (`:standard` runs 9 core ones by default). Opt-in extras (e.g. `non_ar_models`, `database_stats`) are not in those presets.
-2. **`rails ai:bridge`** writes bounded bridge files for Claude, Cursor, Copilot, Codex, Windsurf, Gemini, and JSON.
-3. **`rails ai:serve`** exposes **11 built-in MCP tools** (plus any `additional_tools`) so assistants pull detail on demand (`detail: "summary"` first, then drill down).
+1. **Introspect**: built-in scanners read your Rails app structure: schema, models, routes, controllers, gems, tests, conventions, and optional full-stack details.
+2. **Generate**: `rails ai:bridge` writes compact, assistant-specific files such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, and Copilot instructions.
+3. **Serve**: `rails ai:serve` exposes read-only `rails_*` MCP tools so an assistant can drill into exact details on demand.
-### Folder guides
+This creates two complementary layers:
-For contributors, key folders now include local `README.md` guides:
+| Layer | What it does | Why it matters |
+|---|---|---|
+| Static files | Give the assistant passive project orientation at session start | Fewer cold starts and fewer generic assumptions |
+| MCP tools | Return exact live details when requested | Less context bloat and fewer schema/route hallucinations |
-- [`lib/rails_ai_bridge/README.md`](lib/rails_ai_bridge/README.md)
-- [`lib/rails_ai_bridge/introspectors/README.md`](lib/rails_ai_bridge/introspectors/README.md)
-- [`lib/rails_ai_bridge/tools/README.md`](lib/rails_ai_bridge/tools/README.md)
-- [`lib/rails_ai_bridge/serializers/README.md`](lib/rails_ai_bridge/serializers/README.md)
-- [`lib/generators/rails_ai_bridge/README.md`](lib/generators/rails_ai_bridge/README.md)
-- [`spec/lib/rails_ai_bridge/README.md`](spec/lib/rails_ai_bridge/README.md)
+Compact files are ordered for usefulness: primary domain models, busy endpoints, recently migrated tables, and optional hot-table signals appear before lower-signal supporting details.
+## Safety model
+- MCP tools are **read-only**. They inspect Rails structure; they do not write files or mutate the database.
+- `database_stats` is **opt-in** because it queries PostgreSQL table statistics.
+- Generated assistant context avoids credential values and suppresses secret-bearing config paths such as `.env*`, Rails credentials, `master.key`, private key material, and custom `config/secrets` or `config/private` files.
+- HTTP MCP should stay bound to `127.0.0.1` unless you add authentication and network controls. See [docs/mcp-security.md](docs/mcp-security.md).
 ---
@@ -114,7 +139,7 @@ Optional: `gem install rails-ai-bridge` installs the gem into your Ruby environm
 ### Verify the integration in *your* Rails app
 1. **`bundle install` must finish cleanly** — until it does, `bundle exec rails -T` and `rails ai:serve` (from `.mcp.json`) cannot be verified. Merging this gem to `main` does not fix a broken or incomplete bundle on the host app.
-2. **Regenerate in one shot** — run `rails ai:bridge` (not only a single format) so route/controller summaries stay consistent across `CLAUDE.md`, `.cursor/rules/`, and `.github/instructions/`.
+2. **Regenerate in one shot** — run `rails ai:bridge` (not only a single format) so route/controller summaries and relevance ordering stay consistent across `CLAUDE.md`, `.cursor/rules/`, and `.github/instructions/`.
 3. **Keep team-specific rules** — generated files are snapshots. Use **`config/rails_ai_bridge/overrides.md`** for org-specific constraints (merged only after you **delete the first-line** `<!-- rails-ai-bridge:omit-merge -->` stub). Until then, the gem does not inject placeholder text into Copilot/Codex. See **`overrides.md.example`** for an outline. Alternatively re-merge into generated files after each `rails ai:bridge` (see `.codex/README.md`).
 4. **Tune list sizes** — `RailsAiBridge.configure { |c| c.copilot_compact_model_list_limit = 5 }` (and `codex_compact_model_list_limit`); set `0` to list no model names and point only to MCP.
 5. **Check your readiness** — `rails ai:doctor` prints a 0–100 score and flags anything missing after first install.
@@ -194,25 +219,25 @@ Each file respects the AI tool's format and size limits. **Commit these files**
 | Category | What's introspected |
 |----------|-------------------|
-| **Database** | Every table, column, index, foreign key, and migration |
+| **Database** | Every table, column, index, foreign key, and migration. Optional PostgreSQL stats add `small` / `medium` / `large` / `hot` table hints. |
 | **Models** | Associations, validations, scopes, enums, callbacks, concerns, macros (`has_secure_password`, `encrypts`, `normalizes`, etc.), **semantic tier** (`core_entity`, `pure_join`, `rich_join`, `supporting`) |
-| **Non-AR Models** | Ruby classes under `app/models` that aren't ActiveRecord, tagged as `[POJO/Service]` (opt-in via `:non_ar_models` introspector) |
-| **Routing** | Every route with HTTP verbs, paths, controller actions, API namespaces |
-| **Controllers** | Actions, filters, strong params, concerns, API controllers |
+| **Non-AR Models** | Ruby classes under the configured logical `app/models` path that aren't ActiveRecord, tagged as `[POJO/Service]` (included in `:full`, or opt in with `:non_ar_models`) |
+| **Routing** | Every route with HTTP verbs, paths, controller actions, API namespaces, plus compact endpoint-focus summaries for busy controllers |
+| **Controllers** | Actions, filters, strong params, concerns, API controllers; source metadata honors configured controller paths |
 | **Views** | Layouts, templates, partials, helpers, template engines, view components |
-| **Frontend** | Stimulus controllers (targets, values, actions, outlets), Turbo Frames/Streams, model broadcasts |
+| **Frontend** | Stimulus controllers, views, Turbo Frames/Streams, and broadcasts from configured Rails paths |
 | **Background** | ActiveJob classes, mailers, Action Cable channels |
 | **Gems** | 70+ notable gems categorized (Devise = auth, Sidekiq = jobs, Pundit = authorization, etc.) |
-| **Auth** | Devise modules, Pundit policies, CanCanCan, has_secure_password, CORS, CSP |
-| **API** | Serializers, GraphQL, versioning, rate limiting, API-only mode |
+| **Auth** | Devise modules, Pundit policies, CanCanCan, has_secure_password, Rails auth, CORS, CSP; source scans honor configured Rails paths |
+| **API** | Serializers, GraphQL, versioning, rate limiting, API-only mode; source scans honor configured Rails paths |
 | **Testing** | Framework, factories/fixtures, CI config, coverage, system tests |
-| **Config** | Cache store, session store, middleware, initializers, timezone |
+| **Config** | Cache store, session store, middleware, initializers, timezone, CurrentAttributes from configured model paths |
 | **DevOps** | Puma, Procfile, Docker, deployment tools, asset pipeline |
 | **Architecture** | Service objects, STI, polymorphism, state machines, multi-tenancy, engines |
 The `:full` preset runs 27 introspectors. The `:standard` preset runs 9 core ones by default.
-Start with `:standard` for most apps, then selectively enable additional introspectors (like `:non_ar_models` or `:database_stats`) as your use case requires.
+Start with `:standard` for most apps, then selectively enable additional introspectors (like `:database_stats`) as your use case requires. Use `config.core_models` to tell the generator which models are primary domain entities.
 This keeps context focused and avoids unnecessary token usage while still allowing deep introspection when needed.
@@ -233,7 +258,7 @@ The gem exposes **11 built-in tools** via MCP that AI clients call on-demand (ho
 | `rails_get_gems` | Notable gems categorized by function |
 | `rails_get_conventions` | Architecture patterns, directory structure |
 | `rails_search_code` | Ripgrep (or Ruby) search under `Rails.root` with allowlisted extensions, pattern size cap, and optional wall-clock timeout |
-| `rails_get_view` | View layouts, templates, partials; optional per-file detail under `app/views` |
+| `rails_get_view` | View layouts, templates, partials; optional per-file detail under the configured `app/views` path |
 | `rails_get_stimulus` | Stimulus controllers: targets, values, actions, outlets (requires `:stimulus` introspector) |
 All tools are **read-only** — they never modify your application or database.
@@ -332,7 +357,7 @@ end
 Clients must send `Authorization: Bearer <token>` when a token is configured.
-Security note: keep the HTTP transport bound to `127.0.0.1` unless you add your own network and authentication controls. The tools are read-only, but they can still expose sensitive application structure. In **production**, `rails ai:serve_http` and `auto_mount` require a configured MCP token; `auto_mount` also requires `allow_auto_mount_in_production = true`. For operational hardening (tokens, proxies, `require_http_auth`, stdio threat model), see **[docs/mcp-security.md](docs/mcp-security.md)** and **[SECURITY.md](SECURITY.md)**.
+Security note: keep the HTTP transport bound to `127.0.0.1` unless you add your own network and authentication controls. The tools are read-only, but they can still expose sensitive application structure. Generated context and the built-in conventions resource filter secret-bearing config paths, but MCP access should still be treated as internal. In **production**, `rails ai:serve_http` and `auto_mount` require a configured MCP token; `auto_mount` also requires `allow_auto_mount_in_production = true`. For operational hardening (tokens, proxies, `require_http_auth`, stdio threat model), see **[docs/mcp-security.md](docs/mcp-security.md)** and **[SECURITY.md](SECURITY.md)**.
 </details>
 ---
@@ -350,68 +375,21 @@ Codex support is centered on **`AGENTS.md`** at the repository root.
 ## Best Practices
-> See **[docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md)** for the full guide — including a client compatibility matrix, token optimization patterns, staleness management, and per-assistant workflow tips.
-After testing with Cursor, Windsurf, Copilot, Codex, and Claude Code in real projects, these patterns consistently produce the best results.
-### Layer 1: Commit your static files
+The shortest path to good results:
-The generated files (`.cursorrules`, `.cursor/rules/`, `AGENTS.md`, `.windsurfrules`, `CLAUDE.md`, `.github/copilot-instructions.md`) are loaded **passively** by AI tools on every session start — giving the assistant immediate project grounding before it reads a single line of your code.
+1. **Commit generated static files** so every teammate gets the same passive AI context.
+2. **Run MCP when doing real implementation work** so assistants can drill into current schema, routes, models, controllers, and views.
+3. **Regenerate after meaningful app changes** so static files do not drift from the code.
+4. **Start MCP calls with `detail: "summary"`** and drill into one table, model, route group, or controller only when needed.
+5. **Put team-specific rules in `config/rails_ai_bridge/overrides.md`** instead of hand-editing generated files.
-**Always commit these files.** The whole team benefits, not just the developer who ran `rails ai:bridge`.
-### Layer 2: Run the MCP server
-Static files cover overview. The MCP server covers depth. When an assistant needs full schema details, specific model associations, or a filtered route listing, the `rails_*` tools fetch live data on demand — without inflating your initial context window.
-The combination is additive:
-| Setup | What you get |
-|-------|-------------|
-| Static files only | Passive overview: project structure always loaded |
-| MCP server only | On-demand depth: accurate live data, no passive grounding |
-| **Both (recommended)** | **Passive overview + on-demand depth = best coverage** |
-This is the pattern that consistently outperforms either layer alone. The files reduce orientation overhead; the server handles the details when the assistant actually needs them.
-### Keep files fresh — regenerate after every significant change
-Static files are snapshots. An assistant working from a schema that is 20 commits out of date will still make assumptions based on the old structure. After any significant change — a new model, a migration, a refactor, a feature merged — run:
+Static files are snapshots. After a new model, migration, route change, significant refactor, or feature merge, run:
 ```bash
 rails ai:bridge
 ```
-**Rule of thumb:** treat `rails ai:bridge` the same way you treat `bundle install` after a `Gemfile` change — a routine step, not a one-time setup. Commit the regenerated files alongside the code change so the whole team stays in sync.
-#### Auto-regeneration during active development
-```bash
-rails ai:watch
-```
-Watches for file changes and regenerates relevant context files automatically. Useful when you are actively adding models, routes, or controllers and want the assistant to track along in the same session.
-By default `rails ai:watch` regenerates all formats. To limit regeneration to only the formats you actively use:
-```ruby
-# config/initializers/rails_ai_bridge.rb
-RailsAiBridge.configure do |config|
-  config.watcher_formats = %i[claude cursor]   # only CLAUDE.md + .cursorrules on change
-end
-```
-### Use `detail: "summary"` first with the MCP server
-When the MCP server is running, start broad and drill down:
-```
-1. rails_get_schema(detail: "summary")      → all tables, no noise
-2. rails_get_schema(table: "orders")        → full detail for one table
-3. rails_get_model_details(model: "Order")  → associations, validations, scopes
-```
-This keeps token usage low and answer quality high. Requesting full detail on every table at once is rarely necessary and wastes context on data the assistant does not need yet.
+For the full guide to client compatibility, token usage, overrides, staleness, and per-assistant workflow tips, read [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md).
 ### Pick the right preset for your app
@@ -427,6 +405,14 @@ config.preset = :standard
 config.introspectors += %i[non_ar_models views auth api]
 ```
+For PostgreSQL apps where row-volume context matters, opt into safe approximate table-size hints:
+```ruby
+config.introspectors += %i[database_stats]
+```
+This adds `small`, `medium`, `large`, or `hot` hints to generated context without exposing row data.
 ### Check your readiness score
 ```bash
@@ -442,11 +428,11 @@ Prints a 0–100 AI readiness score and flags anything missing: `.mcp.json`, gen
 ```ruby
 # config/initializers/rails_ai_bridge.rb
 RailsAiBridge.configure do |config|
-  # Presets: :standard (9 introspectors, default) or :full (27). Add :non_ar_models etc. as needed.
+  # Presets: :standard (9 introspectors, default) or :full (27). Add opt-in extras as needed.
   config.preset = :standard
   # Cherry-pick on top of a preset
-  # config.introspectors += %i[non_ar_models views turbo auth api]
+  # config.introspectors += %i[non_ar_models views turbo auth api database_stats]
   # Context mode: :compact (≤150 lines, default) or :full (dump everything)
   # config.context_mode = :compact
@@ -603,16 +589,17 @@ The gem parses `db/schema.rb` as text when no database is connected. Works in CI
 ## Documentation
-| Document | Description |
-|----------|-------------|
-| [docs/GUIDE.md](docs/GUIDE.md) | Full reference — every command, option, MCP parameter, and AI assistant setup |
-| [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md) | Client compatibility matrix, token optimization, staleness management, per-assistant tips |
-| [docs/mcp-security.md](docs/mcp-security.md) | MCP HTTP hardening — tokens, `require_http_auth`, rate limits, proxies, stdio model |
-| [UPGRADING.md](UPGRADING.md) | Migration guide when upgrading between major versions |
-| [CHANGELOG.md](CHANGELOG.md) | Full version history and release notes |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, adding introspectors/tools, PR process, and release checklist |
-| [SECURITY.md](SECURITY.md) | Security policy, vulnerability reporting, design notes, and HTTP MCP authentication |
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards |
+The docs are layered so new users do not need to read everything at once.
+| If you need... | Start here |
+|---|---|
+| A quick install and mental model | This README |
+| How to get better AI output day to day | [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md) |
+| Every command, config option, generated file, and MCP parameter | [docs/GUIDE.md](docs/GUIDE.md) |
+| HTTP MCP hardening and production safety | [docs/mcp-security.md](docs/mcp-security.md) and [SECURITY.md](SECURITY.md) |
+| Upgrade notes between major versions | [UPGRADING.md](UPGRADING.md) |
+| Release history | [CHANGELOG.md](CHANGELOG.md) |
+| Development and contribution workflow | [CONTRIBUTING.md](CONTRIBUTING.md) |
 ---
@@ -627,11 +614,20 @@ bundle exec rubocop     # lint
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide: adding introspectors, adding MCP tools, code style rules, PR process, and the maintainer release checklist.
+For contributors, key folders include local guides:
+- [`lib/rails_ai_bridge/README.md`](lib/rails_ai_bridge/README.md)
+- [`lib/rails_ai_bridge/introspectors/README.md`](lib/rails_ai_bridge/introspectors/README.md)
+- [`lib/rails_ai_bridge/tools/README.md`](lib/rails_ai_bridge/tools/README.md)
+- [`lib/rails_ai_bridge/serializers/README.md`](lib/rails_ai_bridge/serializers/README.md)
+- [`lib/generators/rails_ai_bridge/README.md`](lib/generators/rails_ai_bridge/README.md)
+- [`spec/lib/rails_ai_bridge/README.md`](spec/lib/rails_ai_bridge/README.md)
 Bug reports and pull requests: [github.com/igmarin/rails-ai-bridge/issues](https://github.com/igmarin/rails-ai-bridge/issues)
 ## Acknowledgments & Origins
-This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **3.0.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
+This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **3.1.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
 RailsMCP evolved from
 [crisnahine/rails-ai-context](https://github.com/crisnahine/rails-ai-context),

data/docs/BEST_PRACTICES.md CHANGED Viewed

@@ -17,6 +17,7 @@ This document consolidates the patterns that consistently produce the best resul
 - [Per-Assistant Workflow Tips](#per-assistant-workflow-tips)
 - [MCP Drill-Down Workflow](#mcp-drill-down-workflow)
 - [Choosing the Right Preset](#choosing-the-right-preset)
+- [Reading the Generated Context](#reading-the-generated-context)
 - [What to Commit and What to Ignore](#what-to-commit-and-what-to-ignore)
 ---
@@ -299,6 +300,25 @@ config.introspectors += %i[views auth api tests]
 The `tests` introspector is particularly valuable — it tells the AI your test framework (RSpec vs Minitest), factory setup (FactoryBot vs fixtures), and CI config. Without it, the AI may generate Minitest assertions in an RSpec project.
+For large PostgreSQL apps, consider adding `database_stats` when row-volume hints matter:
+```ruby
+config.introspectors += %i[database_stats]
+```
+It uses PostgreSQL's approximate table statistics and renders only coarse buckets (`small`, `medium`, `large`, `hot`). Keep it opt-in for regulated apps or environments where table-volume metadata is sensitive.
+## Reading the Generated Context
+Compact generated files are ordered for action, not inventory completeness:
+- Core entities from `config.core_models` are intentionally promoted.
+- Models with more associations, validations, callbacks, scopes, routed endpoints, recent migrations, or optional hot-table signals appear earlier.
+- Endpoint focus highlights busy controllers and points the assistant to `rails_get_routes(controller:"...", detail:"summary")`.
+- Full schema, route, and model details stay behind MCP tools to avoid always-on token bloat.
+Use this ordering as a starting point, not a replacement for live checks. When a change touches data access, ask the assistant to verify the exact table, route, or model through MCP before editing.
 ---
 ## What to Commit and What to Ignore

data/docs/GUIDE.md CHANGED Viewed

@@ -134,8 +134,8 @@ end
 | File | Purpose | Notes |
 |------|---------|-------|
 | `CLAUDE.md` | Main context file | ≤150 lines in compact mode. Claude Code reads this automatically. |
-| `.claude/rules/rails-context.md` | Semantic layer | App metadata + models grouped by `semantic_tier`. In **compact** mode, at most 20 names per tier with an overflow line pointing to `rails_get_model_details`; **full** mode lists all. |
-| `.claude/rules/rails-schema.md` | Database table listing | Auto-loaded by Claude Code alongside CLAUDE.md. |
+| `.claude/rules/rails-context.md` | Semantic layer | App metadata + models grouped by `semantic_tier`, ordered by task relevance, plus bounded endpoint focus. In **compact** mode, at most 20 names per tier with an overflow line pointing to `rails_get_model_details`; **full** mode lists all. |
+| `.claude/rules/rails-schema.md` | Database table listing | Auto-loaded by Claude Code alongside CLAUDE.md. Adds coarse table-size buckets when `database_stats` is enabled. |
 | `.claude/rules/rails-models.md` | Model listing with associations | Includes `tier: …` per ActiveRecord model; adds **Non-ActiveRecord classes (POJO/Service)** for plain Ruby classes under `app/models`. |
 | `.claude/rules/rails-mcp-tools.md` | Full MCP tool reference | Parameters, detail levels, pagination, workflow guide. |
@@ -145,8 +145,8 @@ end
 |------|---------|-------|
 | `.cursorrules` | Legacy context file | Compact mode: engineering rules + stack + MCP (aligned with Copilot order). |
 | `.cursor/rules/rails-engineering.mdc` | Engineering essentials | `alwaysApply: true` — strong params, auth, N+1, security; points to overrides + full docs. |
-| `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` — stack counts, gems (capped), `routes_stack_line`. |
-| `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` — auto-attaches when editing models. |
+| `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` — stack counts, endpoint focus, gems (capped), `routes_stack_line`. |
+| `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` — auto-attaches when editing models; rows are ordered by task relevance. |
 | `.cursor/rules/rails-controllers.mdc` | Controller reference | `globs: app/controllers/**/*.rb` — auto-attaches when editing controllers. |
 | `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: true` — always available. |
@@ -482,7 +482,7 @@ rails_search_code(pattern: "def create", path: "app/controllers", file_type: "rb
 View-layer context: layouts, templates, partials, helpers, components. Requires the `:views` introspector (included in the `:full` preset, or add `config.introspectors << :views`).
-**Parameters:** optional `path` (file under `app/views`), `controller`, `partial`, and `detail` (`summary` / `standard` / `full`).
+**Parameters:** optional `path` (file under the configured logical `app/views` path), `controller`, `partial`, and `detail` (`summary` / `standard` / `full`).
 ### rails_get_stimulus
@@ -523,7 +523,7 @@ In addition to tools, the gem registers static MCP resources that AI clients can
 | `rails://tests` | Test infrastructure details (JSON) |
 | `rails://migrations` | Migration history and statistics (JSON) |
 | `rails://engines` | Mounted engines with paths and descriptions (JSON) |
-| `rails://views` | View-layer summary (JSON); template `rails://views/{path}` |
+| `rails://views` | View-layer summary (JSON); template `rails://views/{path}` resolves through the configured logical `app/views` path |
 | `rails://stimulus` | Stimulus summary (JSON); template `rails://stimulus/{name}` |
 | `rails://models/{name}` | Per-model details (resource template) |
@@ -748,27 +748,28 @@ These run by default. Fast and cover core Rails structure.
 | `jobs` | ActiveJob classes with queue names. Mailers with action methods. Action Cable channels. |
 | `gems` | 70+ notable gems categorized: auth, background_jobs, admin, monitoring, search, pagination, forms, file_upload, testing, linting, security, api, frontend, utilities. |
 | `conventions` | Architecture patterns (MVC, service objects, STI, polymorphism, etc.), directory structure with file counts, config files, detected patterns. |
-| `controllers` | Actions, filters (before/after/around with only/except), strong params methods, parent class, API controller detection, concerns. |
+| `controllers` | Actions, filters (before/after/around with only/except), strong params methods, parent class, API controller detection, concerns. Source-derived metadata honors the configured logical `app/controllers` path. |
 | `tests` | Test framework (rspec/minitest), factories/fixtures with locations and counts, system tests, CI config files, coverage tool, test helpers, VCR cassettes. |
 | `migrations` | Total count, schema version, pending migrations, recent migration history with detected actions (create_table, add_column, etc.), migration statistics. |
-**Opt-in:** `non_ar_models` — Ruby classes under `app/models` that are not subclasses of `ActiveRecord::Base`, tagged **`[POJO/Service]`** in `rails_get_model_details` listings and Claude `rails-models.md`. Enable with `config.introspectors << :non_ar_models` (typically immediately after `:models`). Uses `Object.const_source_location` after eager load.
+**Standard opt-in:** `non_ar_models` — Ruby classes under the configured logical `app/models` Rails path that are not subclasses of `ActiveRecord::Base`, tagged **`[POJO/Service]`** in `rails_get_model_details` listings and Claude `rails-models.md`. Included in `:full`; add it manually when staying on `:standard`. Uses `Object.const_source_location` after eager load and reports stable logical paths instead of absolute custom directories.
-### Full preset (26 introspectors)
+### Full preset (27 introspectors)
 Includes all standard introspectors plus:
 | Introspector | What it discovers |
 |-------------|-------------------|
-| `stimulus` | Stimulus controllers with targets, values (with types), actions, outlets, classes. Extracted from JS/TS files. |
-| `views` | Layouts, templates grouped by controller, partials (per-controller and shared), helpers with methods, template engines (erb, haml, slim), view components. |
-| `turbo` | Turbo Frames (IDs and files), Turbo Stream templates, model broadcasts (`broadcasts_to`, `broadcasts`). |
+| `non_ar_models` | Ruby classes under the configured logical `app/models` path that are not subclasses of `ActiveRecord::Base`, tagged **`[POJO/Service]`** in model listings. |
+| `stimulus` | Stimulus controllers with targets, values (with types), actions, outlets, classes. Extracted from JS/TS files under the configured logical `app/javascript/controllers` path. |
+| `views` | Layouts, templates grouped by controller, partials (per-controller and shared), helpers with methods, template engines (erb, haml, slim), view components. Honors configured logical `app/views`, `app/helpers`, and `app/components` paths. |
+| `turbo` | Turbo Frames (IDs and files), Turbo Stream templates, model broadcasts (`broadcasts_to`, `broadcasts`). Honors configured logical `app/views` and `app/models` paths. |
 | `i18n` | Default locale, available locales, locale files with key counts, backend class, parse errors. |
-| `config` | Cache store, session store, timezone, middleware stack, initializers, credentials keys, CurrentAttributes classes. |
-| `active_storage` | Attachments (has_one_attached, has_many_attached per model), storage services, direct upload config. |
-| `action_text` | Rich text fields (has_rich_text per model), Action Text installation status. |
-| `auth` | Devise models with modules, Rails 8 built-in auth, has_secure_password, Pundit policies, CanCanCan, CORS config, CSP config. |
-| `api` | API-only mode, API versioning (from directory structure), serializers (Jbuilder, AMS, etc.), GraphQL (types, mutations), rate limiting (Rack::Attack). |
+| `config` | Cache store, session store, timezone, middleware stack, initializers, credentials keys, CurrentAttributes classes from the configured logical `app/models` path. |
+| `active_storage` | Attachments (has_one_attached, has_many_attached per model), storage services, direct upload config. Attachment and direct-upload scans honor configured `app/models`, `app/views`, and `app/javascript` paths. |
+| `action_text` | Rich text fields (has_rich_text per model), Action Text installation status. Model scans honor the configured logical `app/models` path. |
+| `auth` | Devise models with modules, Rails 8 built-in auth, has_secure_password, Pundit policies, CanCanCan, CORS config, CSP config. Model and policy scans honor configured `app/models` and `app/policies` paths. |
+| `api` | API-only mode, API versioning (from directory structure), serializers (Jbuilder, AMS, etc.), GraphQL (types, mutations), rate limiting (Rack::Attack). View, serializer, GraphQL, and controller scans honor configured Rails paths. |
 | `rake_tasks` | Custom rake tasks in `lib/tasks/` with names, descriptions, namespaces, file paths. |
 | `assets` | Asset pipeline (Propshaft/Sprockets), JS bundler (importmap/esbuild/webpack/vite), CSS framework, importmap pins, manifest files. |
 | `devops` | Puma config (threads, workers, port), Procfile entries, Docker (multi-stage detection), deployment tools, health check routes. |
@@ -777,7 +778,7 @@ Includes all standard introspectors plus:
 | `middleware` | Custom Rack middleware in app/middleware/ with detected patterns (auth, rate limiting, tenant isolation, logging). Full middleware stack. |
 | `engines` | Mounted Rails engines from routes.rb with paths and descriptions for 23+ known engines (Sidekiq::Web, Flipper::UI, PgHero, ActiveAdmin, etc.). |
 | `multi_database` | Multiple databases, replicas, sharding config, model-specific `connects_to` declarations. database.yml parsing fallback. |
-| `database_stats` | PostgreSQL approximate row counts via `pg_stat_user_tables`. Opt-in, requires PostgreSQL. |
+| `database_stats` | PostgreSQL approximate row counts via `pg_stat_user_tables`, bucketed as `small`, `medium`, `large`, or `hot`. Opt-in only, requires PostgreSQL. |
 ### Enabling the full preset
@@ -938,6 +939,7 @@ Works in:
 - Code search uses `Open3.capture2` with array arguments — **no shell injection**
 - File paths are validated against **path traversal** attacks
 - Credentials and secret values are **never exposed** — only key names are introspected (unless you opt in with `expose_credentials_key_names`)
+- Generated config-file listings and the `rails://conventions` MCP resource omit secret-bearing paths such as `.env*`, Rails credentials files, secret/private directories, `master.key`, and private key material
 - The gem makes **no outbound network requests**
 - File type validation prevents arbitrary file access in code search
 - `max_results` is capped at 100 to prevent resource exhaustion; `pattern` length is capped (`search_code_pattern_max_bytes`); optional per-invocation timeout (`search_code_timeout_seconds`)

data/docs/roadmap-context-assistants.md CHANGED Viewed

@@ -14,10 +14,69 @@ This track is **separate** from [roadmap-mcp-v2.md](roadmap-mcp-v2.md) (MCP HTTP
 - DRY the formatter hierarchy (done: `SectionFormatter` template method base).
 - Align tool references and workflow hints across Claude, Cursor, Copilot, Windsurf, Codex, and **Gemini** (v2.1.0).
 - Refactor provider serializers with a shared `BaseProviderSerializer` for consistent, high-fidelity output (v2.1.0).
+- Rank compact context by task relevance: semantic tier, structural complexity, endpoint density, recent migrations, and optional database-size hints (v3.1.0).
+- Add bounded endpoint-focus summaries and context-quality fixture matrix coverage for common Rails app shapes (v3.1.0).
+- Back the matrix with real Rails-shaped fixture trees for API-only, Hotwire, large-schema, engine-style, and regulated/no-domain-metadata applications (v3.1.0).
+- Add MCP large-payload stability checks for truncation, pagination hints, and section-cache reuse (v3.1.0).
+- Filter secret-bearing config paths from generated context, `rails_get_conventions`, and `rails://conventions` output (v3.1.0).
+- Honor configured Rails paths in convention detection so custom `app/models` and `app/services`
+  locations still produce useful architecture and directory-structure context without exposing absolute paths (v3.1.0).
+- Honor configured `app/models` paths in ActiveRecord source metadata and `non_ar_models`
+  discovery, mapping custom filesystem locations back to stable logical paths in generated context (v3.1.0).
+- Honor configured controller and frontend paths in controller metadata, view summaries,
+  Stimulus controllers, and Turbo frame/stream/broadcast discovery (v3.1.0).
+- Honor configured `app/views` paths in file-level view detail reads for `rails_get_view(path:)`
+  and `rails://views/{path}` while preserving traversal checks (v3.1.0).
+- Honor configured Rails paths in specialized Active Storage, Action Text, Config, Auth, and API
+  scans so attachments, rich text fields, CurrentAttributes, API layers, and auth/policy signals
+  remain useful in non-conventional app layouts (v3.1.0).
-## In progress
+## Release closure
-- Custom Rails directory introspection coverage gaps
+The v3.1.0 context-quality implementation is complete for the default `:standard` preset and the
+highest-value generated-context signals. Before merging or tagging the release, run the final gate:
+- `rtk bundle exec rspec`
+- `env PERF=true rtk bundle exec rspec --tag perf`
+- `rtk bundle exec rubocop --cache false --format simple`
+- `rtk bundle exec reek`
+- `rtk bundle exec reek spec/fixtures/apps`
+- `rtk bundle exec yard stats --list-undoc`
+Any future code-producing slice should continue to apply the `yard-documentation` skill: every new
+or changed public Ruby class/method needs an English summary plus `@param`, `@return`, and `@raise`
+tags where applicable before the slice is considered complete.
+## Custom Path Support Coverage
+For **v3.1.0**, custom Rails path support is considered complete for the default `:standard`
+context-quality promise and the highest-value `:full` signals:
+- **Standard preset coverage:** `models`, `controllers`, and `conventions` honor configured Rails
+  paths where those introspectors read application source. `schema`, `routes`, `jobs`, `gems`,
+  `tests`, and `migrations` are not primarily driven by `app.paths`.
+- **High-value full-preset coverage:** `non_ar_models`, `views`, `stimulus`, `turbo`,
+  `active_storage`, `action_text`, `config`, `auth`, `api`, and file-level view detail reads honor
+  configured logical Rails paths where they scan source files.
+- **Deferred parity candidates:** `assets`, `i18n`, `rake_tasks`, `action_mailbox`, `devops`,
+  and `middleware` remain full-preset follow-up candidates. Treat these as targeted future work
+  when a real fixture or user app shows custom path value, not as a blocker for the 3.1.0 release.
+## Documentation readability recommendations
+Because this gem serves Rails developers with different experience levels, documentation should
+prefer a layered path over one large linear read:
+- **README:** keep as the shortest product path: problem, value, quick start, generated files,
+  common presets, and safe MCP setup. Link out before diving into every option.
+- **Best Practices:** make this the "how to get value" guide: choosing a preset, reading generated
+  context, writing useful overrides, and avoiding token/security pitfalls.
+- **Guide:** keep exhaustive reference material here: every command, config option, MCP tool, and
+  generated file behavior.
+- **Security docs:** keep threat-model and deployment advice out of the README except for clear
+  links and short warnings.
+- **Examples:** add small scenario-first examples over time, such as API-only, Hotwire CRUD,
+  regulated app, and large-schema CRM. These are easier for new users to follow than option tables.
 ## Relation to versioning