rails-ai-bridge 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94459120e6365ac608ed9a403e16a622e7ef664b377f8585980827c28dd911f0
-  data.tar.gz: e3561760ceb930242a6d344ae3938dfdca49879639e7776a19cc2fa08adff4eb
+  metadata.gz: f8392971b0bc2f8bf98ebe626062b79e7ff271e8aa009ace229702948862eace
+  data.tar.gz: d3e358ef11eef6c9050289d73ab69ec5ad09684d7d8e7d8b25b5da4350306c9e
 SHA512:
-  metadata.gz: c595b9b20dc56cef6adf370d931f06083137691cd5323dd8fe43615eba819eb7d725d5ee62160c0305fb311f3d2592ad767cd2eb8b69bfc3f075aae380b9209e
-  data.tar.gz: d6ee1293103eccc654bbed37f67b9deb022ecede51ee8bc4f4714db86f7f18d73a3ebe0054d86c6c8350107dd1bf6239520ff137c5b828faeb75152095c158bd
+  metadata.gz: d174446e69dddabd9f99457af197d607793f26b09ef346f2c27f124be15700fb1b7961e4ba76dd43959d32bfcfe108787c611505043ecf12e61ba7fd1735b7e9
+  data.tar.gz: 6bb2d7c5290441e76359de520d3e7e737890d3d6456b6e269bfba579c79540a900cccdd872ec580dc5d392c09c6f053e2f0516842aa8e222f0d994111de2b5de

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--output-dir doc/yard
+--protected
+--no-private
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-03-31
+
 ### Added
 
 - **Shared runtime context provider** — MCP tools and `rails://...` resources now read through `RailsAiBridge::ContextProvider`, keeping cache invalidation and snapshot semantics aligned across both entry points.
@@ -15,15 +17,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Section-level context reads** — `ContextProvider.fetch_section` and `BaseTool.cached_section` let single-section tools avoid rebuilding or materializing the full snapshot path when unnecessary.
 - **Folder-level contributor docs** — key runtime folders now include local `README.md` guides for structure, boundaries, and extension points.
 - **Extensibility integration coverage** — specs now prove that a custom introspector, tool, and resource can be registered and used together from the host app configuration surface.
+- **Serializer formatter objects** — `MarkdownSerializer` is now a thin orchestrator delegating to 37 single-responsibility `Formatters::*` classes; each formatter is independently testable and injectable.
+- **Tool response formatters** — `GetSchema` and `GetModelDetails` delegate all rendering to `Tools::Schema::*` and `Tools::ModelDetails::*` formatter classes; tool `call` methods are ≤20 lines each.
+- **`Config::Auth`, `Config::Server`, `Config::Introspection`, `Config::Output`** — `Configuration` is now a `Forwardable` facade over four focused sub-objects; each is independently readable and injectable.
+- **`Mcp::Authenticator`** — consolidates strategy resolution, static-token lookup, and configuration predicates into a single entry point, replacing the previous split between `McpHttpAuth` and `Mcp::HttpAuth`.
+- **`Mcp::HttpRateLimiter`** — optional in-process sliding-window rate limiter per client IP; configured via `config.mcp.rate_limit_max_requests` and `config.mcp.rate_limit_window_seconds`. Returns 429 with `Retry-After` header when exceeded.
+- **`Mcp::HttpStructuredLog`** — optional one-JSON-line-per-request logger for the MCP HTTP path; enabled via `config.mcp.http_log_json = true`. Logs `event`, `http_status`, `path`, `client_ip`, and `request_id`; never logs tokens or full Rack env.
+- **`Config::Mcp`** — new `config.mcp` sub-object (5th façade sub-config) for MCP HTTP operational settings: `mode`, `security_profile`, `rate_limit_max_requests`, `rate_limit_window_seconds`, `http_log_json`, `authorize`, `require_auth_in_production`.
+- **`config.mcp.authorize`** — optional post-auth lambda `(context, request) { truthy }`; returning falsey yields HTTP 403 on the MCP path.
+- **`config.mcp.require_auth_in_production`** — when `true`, boot fails in production unless an auth mechanism is configured.
+- **`HttpTransportApp`** updated — request pipeline is now: path check → auth → authorize → rate limit → structured log → transport.
+- **`SectionFormatter` template method base** — 22 of 37 formatters now inherit from `SectionFormatter`, which handles the nil/error guard in one place; each formatter only implements `render(data)`.
+- **`Serializers::Providers` namespace** — 10 LLM provider serializers extracted into `lib/rails_ai_bridge/serializers/providers/`, separating provider concerns from domain infrastructure (`MarkdownSerializer`, `JsonSerializer`, formatters).
+- **`UPGRADING.md`** — new upgrade guide documenting `config.mcp` settings, rate limit semantics, structured logging, `authorize` behaviour, and the `require_auth_in_production` flag.
+- **Contributor roadmaps** — `docs/roadmaps.md`, `docs/roadmap-mcp-v2.md`, `docs/roadmap-context-assistants.md` added.
 
 ### Changed
 
 - **Install generator messages** — the install flow now reports created vs unchanged files correctly and the generated initializer comments reflect the current preset sizes.
 - **Fingerprint reuse on invalidation** — context refresh reuses a single fingerprint snapshot per fetch cycle instead of scanning twice when cached context becomes stale.
+- **`FullClaudeSerializer`, `FullRulesSerializer`, `FullCopilotSerializer`, `FullCodexSerializer` removed** — full-mode rendering is now handled by injecting header/footer formatter classes into `MarkdownSerializer` via constructor arguments; no subclassing needed.
+- **Test suite expanded to 841 examples at ≥87% line coverage.**
 
 ### Fixed
 
 - **Install generator output bug** — `generate_context` results are no longer iterated as raw hash pairs during install-time file generation.
+- **`StandardFormatter` pagination hint** — navigation hint now correctly uses `offset + limit < total` (consistent with `SummaryFormatter` and `FullFormatter`), preventing a spurious hint on the last page.
+
+### Upgrading from 1.x
+
+**No configuration changes required.** Every `config.*` attribute from 1.x is still available unchanged — `Configuration` now delegates to focused sub-objects (`Config::Auth`, `Config::Server`, `Config::Introspection`, `Config::Output`, `Config::Mcp`) but exposes the same flat DSL.
+
+The following internal classes were removed; they were never part of the documented public API:
+
+| Removed | Replacement |
+|---------|-------------|
+| `Mcp::HttpAuth` / `McpHttpAuth` | `Mcp::Authenticator` (same behaviour, single entry point) |
+| `FullClaudeSerializer` | Pass `header_class: Formatters::ClaudeHeaderFormatter` to `MarkdownSerializer` |
+| `FullCopilotSerializer` | Pass `header_class: Formatters::CopilotHeaderFormatter` to `MarkdownSerializer` |
+| `FullCodexSerializer` | Pass `header_class: Formatters::CodexHeaderFormatter` to `MarkdownSerializer` |
+| `FullRulesSerializer` | Pass `header_class: Formatters::RulesHeaderFormatter` to `MarkdownSerializer` |
+
+If you were only using the gem through its initializer, rake tasks, or MCP server — no action needed.
 
 ## [1.1.0] - 2026-03-20
 

data/Rakefile

@@ -5,4 +5,7 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+require "yard"
+YARD::Rake::YardocTask.new(:yard)
+
 task default: :spec

data/SECURITY.md

@@ -33,14 +33,18 @@ This fork is maintained by **Ismael Marin**. If you discover a security vulnerab
 
 ## HTTP MCP authentication
 
-- Set `config.http_mcp_token` and/or `ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]` (**ENV overrides** the config value when set).
-- When a token is configured, clients must send `Authorization: Bearer <token>` to the HTTP MCP endpoint (`auto_mount` or `rails ai:serve_http`).
-- When no token is configured, HTTP MCP is **unauthenticated** (backward compatible for local use); **set a token** before exposing the port beyond localhost.
+- **Shared secret:** set `config.http_mcp_token` and/or `ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]` (**ENV overrides** the config value when set). Clients send `Authorization: Bearer <token>`.
+- **Custom resolver / JWT:** configure `config.mcp_token_resolver` or `config.mcp_jwt_decoder` (see [docs/GUIDE.md](docs/GUIDE.md)); clients still use a Bearer header; the gem does not ship a JWT library — you verify and decode inside your lambda.
+- **Rack env context:** after a successful auth, `env["rails_ai_bridge.mcp.context"]` may contain **PII or claims** (e.g. JWT payload). Do not dump full Rack `env` to logs or APM; treat this key like session-derived data.
+- When **no** auth mechanism is configured, HTTP MCP is **unauthenticated** (backward compatible for local use); configure one of the above before exposing the port beyond localhost.
+- **Misconfiguration guard:** setting `:bearer_token` strategy without a `token_resolver` and without a static token causes **boot failure** (`ConfigurationError`) so the endpoint cannot start in an accidentally open state.
+- **Rate limiting:** optional `config.mcp.rate_limit_max_requests` is an **in-memory, per-process** sliding window keyed by client IP (`request.ip`). It is **not** shared across Puma workers or hosts. Treat this as a light guard — use a reverse proxy, WAF, or `rack-attack` for strict distributed quotas.
+- **MCP HTTP JSON logs:** when `config.mcp.http_log_json` is enabled, log lines include `client_ip` and path; treat log sinks like any operational data store (retention, access control).
 
 ## Production
 
-- `config.auto_mount = true` in **production** raises at boot unless **both** `config.allow_auto_mount_in_production = true` and a non-empty MCP token are set.
-- `rails ai:serve_http` in **production** requires a non-empty MCP token (config or ENV).
+- `config.auto_mount = true` in **production** raises at boot unless **both** `config.allow_auto_mount_in_production = true` and an MCP auth mechanism is configured (shared token, `mcp_token_resolver`, or `mcp_jwt_decoder`).
+- `rails ai:serve_http` in **production** requires an auth mechanism (not necessarily a static shared secret).
 
 ## Operational Security Guidance
 
@@ -48,3 +52,7 @@ This fork is maintained by **Ismael Marin**. If you discover a security vulnerab
 - If you enable HTTP transport, keep it bound to `127.0.0.1` unless you add your own network isolation and authentication controls.
 - Do **not** expose `auto_mount` on public or shared production surfaces without an explicit threat model review.
 - Treat generated files such as `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and `.ai-context.json` as internal engineering documentation.
+
+## Presets, exclusions, and MCP
+
+`rails_get_schema`, `rails_get_model_details`, and other tools build on the same introspection pipeline as `rails ai:bridge`. When you use `config.excluded_tables`, `config.excluded_models`, `config.disabled_introspection_categories`, or presets such as `:regulated`, treat the HTTP/stdio MCP surface with the **same data-classification assumptions** as your committed context files: the tools remain read-only but can still reveal structure you chose to omit from markdown.

data/UPGRADING.md

@@ -0,0 +1,87 @@
+# Upgrading rails-ai-bridge
+
+## Upgrading from 1.x to 2.x
+
+**No configuration changes required.** Every `config.*` attribute from 1.x is still available — `Configuration` now delegates to focused sub-objects but exposes the same flat DSL. See `CHANGELOG.md` for the full list of internal changes.
+
+---
+
+## New in 2.x — `config.mcp` settings
+
+MCP HTTP operational configuration lives under `config.mcp` (a `Config::Mcp` object). All attributes are also accessible as flat delegators on `config` directly.
+
+### Rate limiting
+
+```ruby
+RailsAiBridge.configure do |config|
+  # Explicit ceiling: 100 requests per 60-second sliding window per client IP
+  config.mcp.rate_limit_max_requests  = 100
+  config.mcp.rate_limit_window_seconds = 60
+
+  # Set to 0 to disable rate limiting entirely
+  # config.mcp.rate_limit_max_requests = 0
+end
+```
+
+When `rate_limit_max_requests` is `nil` (default), the gem may apply an **implicit** per-IP ceiling from `security_profile` (`:strict` / `:balanced` / `:relaxed`), unless `mode` suppresses it:
+
+- **`mode: :dev`** — no implicit limit.
+- **`mode: :hybrid`** (default) — implicit limit only when `Rails.env.production?`.
+- **`mode: :production`** — implicit limit in every Rails environment.
+
+Set `config.mcp.rate_limit_max_requests = 0` to **disable** limiting entirely (including implicit). A **positive integer** always overrides the profile.
+
+> **Note:** the rate limiter is **in-memory and per-process**. It is not shared across Puma workers or hosts. Use a reverse proxy, WAF, or `rack-attack` for strict distributed quotas.
+
+### Structured logging
+
+```ruby
+RailsAiBridge.configure do |config|
+  # Emit one JSON line per MCP HTTP response to Rails.logger
+  config.mcp.http_log_json = true
+end
+```
+
+Each log line includes `msg`, `event`, `http_status`, `path`, `client_ip`, and `request_id` (when present). Tokens and full Rack `env` are never logged. The flag is read **on each request** (unlike the rate-limit snapshot taken at `HttpTransportApp.build`).
+
+### Post-auth authorization (`authorize`)
+
+```ruby
+RailsAiBridge.configure do |config|
+  # Called after successful auth; returning falsey yields HTTP 403
+  config.mcp.authorize = ->(context, request) {
+    context[:role] == "admin"
+  }
+end
+```
+
+The lambda is read and called **on every request** (like `http_log_json`), so changes take effect immediately without rebuilding the transport app. If the lambda raises a `StandardError`, the gem treats it as a 403 and logs the error — it does not propagate as a 500.
+
+### Production boot guard
+
+```ruby
+RailsAiBridge.configure do |config|
+  # Raise at boot in production unless an auth mechanism is configured
+  config.mcp.require_auth_in_production = true
+end
+```
+
+When `true` in a production environment, Rails boot fails unless at least one MCP HTTP auth mechanism is configured:
+- `config.http_mcp_token`, or
+- `ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]`, or
+- `config.mcp_token_resolver`, or
+- `config.mcp_jwt_decoder`
+
+Default is `false`.
+
+---
+
+## `strategy :bearer_token` misconfiguration guard
+
+Rails **boot** raises `RailsAiBridge::ConfigurationError` if you configure `:bearer_token` strategy without a resolver or static token — that combination would leave HTTP MCP unauthenticated.
+
+---
+
+## Resolver / JWT return values
+
+Return **`nil`** (or `false`) when a token is invalid. Returning `false` explicitly is treated as auth failure (401).

data/docs/roadmap-context-assistants.md

@@ -0,0 +1,27 @@
+# Roadmap: context files & assistant UX (pre–major release)
+
+This track is **separate** from [roadmap-mcp-v2.md](roadmap-mcp-v2.md) (MCP HTTP auth, rate limits, logging). It covers **improving the static context** the gem generates (CLAUDE.md, Cursor rules, Copilot instructions, etc.) so IDEs and AI clients get **clearer, more actionable** help from the same introspection data.
+
+**Progress summary:** [roadmaps.md](roadmaps.md).
+
+## Goals (high level)
+
+- Sharpen per-assistant formats (structure, length, cross-links) based on real usage feedback.
+- Reduce duplication and noise while keeping "always-on" rules discoverable.
+- Align tool references and workflow hints across Claude, Cursor, Copilot, Windsurf, Codex, etc.
+- Separate LLM provider serializers from domain infrastructure (done: `Serializers::Providers::` namespace).
+- DRY the formatter hierarchy (done: `SectionFormatter` template method base).
+
+## In progress
+
+- Refining per-provider serializer output (context quality improvements on `pr5-context-quality` branch)
+- Custom Rails directory introspection coverage gaps
+
+## Relation to versioning
+
+**No semver bump is implied by this doc alone.** A future **major release** (e.g. 2.0.0) should follow **after** this work when the maintainers are ready to communicate breaking or wide-ranging changes to generated files and defaults — not as a fixed milestone on the MCP roadmap.
+
+## References
+
+- [docs/GUIDE.md](GUIDE.md) — install, formats, MCP setup
+- [CHANGELOG.md](../CHANGELOG.md) — user-visible changes

data/docs/roadmap-mcp-v2.md

@@ -0,0 +1,45 @@
+# Roadmap: MCP HTTP auth (v2 track)
+
+High-level direction for the `RailsAiBridge::Mcp` HTTP authentication layer, rate limiting, and related docs. The detailed task list may live in your issue tracker; this file is the **human-readable** anchor for contributors.
+
+## Engineering principles (this track)
+
+These are **priorities** for code that lands under `lib/rails_ai_bridge/mcp/` and related Rack paths — not optional polish at the end.
+
+1. **Tests gate implementation** — Write or extend a failing spec for the behavior, run it, then implement. No "implement first, test later" for new behavior.
+
+2. **YARD on every public surface** — Any new or changed public Ruby class or method needs an English YARD summary, `@param`, `@return`, and `@raise` when applicable — before the change is considered done.
+
+3. **Clear method boundaries** — Keep Rack/guard logic separate from "run host lambda safely." Strategies stay easy to read, review, and extend without growing god methods.
+
+4. **Self-review before merge** — Run through `rails-code-review` (and security/architecture skills when touching auth or production boot).
+
+5. **User-facing documentation per slice** — Update `CHANGELOG` `[Unreleased]`, and touch `GUIDE` / `SECURITY` / `UPGRADING` when user-visible behavior changes.
+
+## Done (v2 snapshot)
+
+- `Mcp::Authenticator` — consolidated strategy resolution (replaces `McpHttpAuth` + `Mcp::HttpAuth`)
+- `Mcp::Auth::Strategies::BearerToken` — static token + optional `token_resolver`, digest compare
+- `Mcp::Auth::Strategies::Jwt` — host-supplied `jwt_decoder`; no JWT gem bundled
+- `Config::Auth` — flat auth sub-config (`http_mcp_token`, `mcp_token_resolver`, `mcp_jwt_decoder`)
+- `Config::Mcp` — MCP HTTP operational config (`rate_limit_*`, `http_log_json`, `authorize`, `require_auth_in_production`, `mode`, `security_profile`)
+- `Mcp::HttpRateLimiter` — in-process sliding window per IP, mutex, prune empty buckets
+- `Mcp::HttpStructuredLog` — one JSON line per MCP HTTP outcome; no token logging
+- `HttpTransportApp` — single Rack entry: path match → auth → authorize → rate limit → log → transport
+- Boot / config validation — `:bearer_token` requires resolver or static token; `require_auth_in_production` alignment
+- Docs: GUIDE / SECURITY / UPGRADING / CHANGELOG / roadmaps
+
+## Next (follow-up, non-blocking)
+
+- Log sampling (emit every Nth request instead of every request)
+- Metrics hooks (expose request counts / rate-limit hits for APM)
+- Heavier load testing / benchmarks
+- Community-driven tweaks (e.g. per-route rate limits, response-size logging)
+
+## References
+
+- [docs/roadmaps.md](roadmaps.md) — quick progress tables for all tracks
+- [docs/GUIDE.md](GUIDE.md) — MCP HTTP configuration
+- [docs/roadmap-context-assistants.md](roadmap-context-assistants.md) — IDE / context file improvements
+- [SECURITY.md](../SECURITY.md) — threat model and production notes
+- [UPGRADING.md](../UPGRADING.md) — breaking / new config knobs

data/docs/roadmaps.md

@@ -0,0 +1,48 @@
+# Roadmaps — progress index
+
+Entry point to see **which tracks exist** and **what is left**. Details live in each linked file; update the tables here when you close slices (or track work in GitHub Issues / Projects instead).
+
+**Audience:** These documents are mainly for **maintainers and contributors**. Gem users usually rely on [GUIDE.md](GUIDE.md), [CHANGELOG.md](../CHANGELOG.md), and the README. Keeping roadmaps **in git** is normal for open-source gems (transparency, onboarding); they are not required to *use* the gem.
+
+## MCP HTTP track (`RailsAiBridge::Mcp`)
+
+**Primary doc:** [roadmap-mcp-v2.md](roadmap-mcp-v2.md) (engineering principles + narrative snapshot).
+
+| Area | Status |
+|------|--------|
+| Auth (`Mcp::Authenticator`, Bearer, JWT, resolver, boot guards) | Done |
+| `authorize` + 403 | Done |
+| In-process rate limit + bucket prune (`Mcp::HttpRateLimiter`) | Done |
+| `mode` / `security_profile` + effective limits (`Config::Mcp`) | Done |
+| JSON HTTP logging (`http_log_json`, `Mcp::HttpStructuredLog`) | Done |
+| Docs (GUIDE / SECURITY / UPGRADING / CHANGELOG) for the above | Done |
+
+**Optional / follow-up (non-blocking):** log sampling, metrics hooks, heavier load testing, community-driven tweaks.
+
+---
+
+## v2.0.0 — context files & assistant UX
+
+**Primary doc:** [roadmap-context-assistants.md](roadmap-context-assistants.md).
+
+| Area | Status |
+|------|--------|
+| Serializer formatter extraction (37 `Formatters::*` classes) | Done |
+| `Config::Auth`, `Config::Server`, `Config::Introspection`, `Config::Output` façade | Done |
+| `Config::Mcp` sub-object for MCP HTTP config | Done |
+| `Mcp::Authenticator` consolidation | Done |
+| Provider serializers extracted to `Serializers::Providers::` | Done |
+| `SectionFormatter` template method base (DRY guard pattern) | Done |
+| Concrete tasks per assistant / format | **In progress** |
+| Major release (2.0.0) | **Deferred** until this track + communication plan |
+
+---
+
+## Where to look in the repo
+
+| Need | File |
+|------|------|
+| Implementation rules (tests, YARD, docs per slice) | [roadmap-mcp-v2.md](roadmap-mcp-v2.md) § Engineering principles |
+| What the MCP stack already includes (narrative) | [roadmap-mcp-v2.md](roadmap-mcp-v2.md) § Done vs upcoming |
+| Plan for generated context (CLAUDE.md, rules, etc.) | [roadmap-context-assistants.md](roadmap-context-assistants.md) |
+| User-facing shipped / upcoming changes | [CHANGELOG.md](../CHANGELOG.md) `[Unreleased]` and version sections |

data/lib/generators/rails_ai_bridge/install/install_generator.rb

@@ -24,53 +24,81 @@ module RailsAiBridge
 
       def create_initializer
         standard_count = RailsAiBridge::Configuration::PRESETS[:standard].size
-        full_count = RailsAiBridge::Configuration::PRESETS[:full].size
+        full_count     = RailsAiBridge::Configuration::PRESETS[:full].size
+        regulated_count = RailsAiBridge::Configuration::PRESETS[:regulated].size
 
         create_file "config/initializers/rails_ai_bridge.rb", <<~RUBY
           # frozen_string_literal: true
 
           RailsAiBridge.configure do |config|
-            # Introspector preset:
-            #   :standard — #{standard_count} core introspectors (schema, models, routes, jobs, gems, conventions, controllers, tests, migrations)
-            #   :full     — all #{full_count} introspectors (adds views, turbo, auth, API, config, assets, devops, etc.)
+            # --- Introspector preset ---
+            #   :standard  — #{standard_count} core introspectors (schema, models, routes, jobs, gems, conventions, controllers, tests, migrations)
+            #   :full      — all #{full_count} introspectors (adds views, turbo, auth, API, config, assets, devops, etc.)
+            #   :regulated — #{regulated_count} introspectors — no schema/models/migrations (for apps with strict data governance)
             # config.preset = :standard
 
             # Or cherry-pick individual introspectors:
             # config.introspectors += %i[views turbo auth api]
 
-            # Models to exclude from introspection
+            # Disable whole product categories at runtime (schema + models + migrations, api, views/turbo/i18n):
+            # config.disabled_introspection_categories << :domain_metadata
+
+            # --- Security exclusions ---
+            # Tables to hide from schema + model introspection (exact name or glob, e.g. "pii_*"):
+            # config.excluded_tables += %w[secrets audit_logs pii_*]
+
+            # Models to exclude from introspection:
             # config.excluded_models += %w[AdminUser InternalThing]
 
-            # Paths to exclude from code search
+            # Paths excluded from rails_search_code:
             # config.excluded_paths += %w[vendor/bundle]
 
-            # Context mode for generated files (CLAUDE.md, .cursorrules, etc.)
-            # :compact — smart, ≤150 lines, references MCP tools for details (default)
-            # :full    — dumps everything into context files (good for small apps <30 models)
+            # --- Context output ---
+            # :compact — ≤150 lines, references MCP tools for details (default)
+            # :full    — full dump (good for small apps)
             # config.context_mode = :compact
-
-            # Max lines for CLAUDE.md in compact mode
             # config.claude_max_lines = 150
-
-            # Max response size for MCP tool results (chars). Safety net for large apps.
             # config.max_tool_response_chars = 120_000
 
-            # Optional: path to markdown merged into compact Copilot + Codex (default: config/rails_ai_bridge/overrides.md).
-            # The install stub uses <!-- rails-ai-bridge:omit-merge --> on line 1 — delete it when adding real rules
-            # (until then nothing is merged). See config/rails_ai_bridge/overrides.md.example for an outline.
+            # Team rules merged into compact Copilot/Codex output (remove omit-merge line when ready):
             # config.assistant_overrides_path = "config/rails_ai_bridge/overrides.md"
 
-            # Compact file model name caps (0 = MCP pointer only, no names listed)
+            # Compact model list caps (0 = MCP pointer only, no names listed):
             # config.copilot_compact_model_list_limit = 5
             # config.codex_compact_model_list_limit = 3
 
-            # Auto-mount HTTP MCP endpoint at /mcp (see SECURITY.md — production needs token + explicit opt-in)
+            # ==========================================================================
+            # HTTP MCP / auto_mount — SECURITY CRITICAL
+            # ==========================================================================
+            # Exposes read-only MCP tools over HTTP. Still reveals routes, schema, and
+            # code layout — treat as sensitive. Prefer stdio (`rails ai:serve`) for local
+            # AI clients.
+            #
+            # In production you MUST configure one auth mechanism AND set
+            # allow_auto_mount_in_production = true. Options (highest priority first):
+            #
+            #   1. JWT decoder (no JWT gem required — supply your own lambda):
+            #      config.mcp_jwt_decoder = ->(token) {
+            #        JWT.decode(token, credentials.jwt_secret, true, algorithm: "HS256").first
+            #      rescue JWT::DecodeError
+            #        nil
+            #      }
+            #
+            #   2. Token resolver (Devise, database lookup, etc.):
+            #      config.mcp_token_resolver = ->(token) { User.find_by(mcp_api_token: token) }
+            #
+            #   3. Static shared secret:
+            #      config.http_mcp_token = "generate-a-long-random-secret"
+            #      # ENV["RAILS_AI_BRIDGE_MCP_TOKEN"] overrides this when set
+            #
+            # IMPORTANT: Token comparison is timing-safe but does NOT prevent
+            # brute-force guessing. Add rate limiting on the MCP endpoint in
+            # production (e.g. Rack::Attack throttle on config.http_path).
+            #
             # config.auto_mount = false
             # config.allow_auto_mount_in_production = false
-            # config.http_mcp_token = "generate-a-long-random-secret"
-            # ENV["RAILS_AI_BRIDGE_MCP_TOKEN"] overrides http_mcp_token when set
-            # config.http_path  = "/mcp"
-            # config.http_port  = 6029
+            # config.http_path = "/mcp"
+            # config.http_port = 6029
           end
         RUBY
 

data/lib/rails_ai_bridge/assistant_formats_preference.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RailsAiBridge
+  # Reads and writes which assistant formats +rails ai:bridge+ regenerates by default.
+  #
+  # The install generator creates {RELATIVE_PATH} with a YAML +formats+ list (a subset of
+  # {FORMAT_KEYS}). When the file is missing, invalid, or lists no recognized formats,
+  # callers treat the result as +nil+ and fall back to generating all formats.
+  #
+  # @example install.yml
+  #   formats:
+  #     - claude
+  #     - codex
+  #
+  # @see RailsAiBridge::Generators::InstallGenerator
+  class AssistantFormatsPreference
+    # Path of the preference file relative to +Rails.root+.
+    RELATIVE_PATH = "config/rails_ai_bridge/install.yml"
+
+    # All recognized format keys (order is not significant).
+    FORMAT_KEYS = %i[claude codex cursor windsurf copilot json].freeze
+
+    class << self
+      # Absolute path to the preference file for the current Rails application.
+      #
+      # @return [Pathname, nil] +nil+ when +Rails.application+ is unavailable
+      def config_path
+        return nil unless defined?(Rails) && Rails.application
+
+        Rails.root.join(RELATIVE_PATH)
+      end
+
+      # Returns the subset of formats requested for the default +rails ai:bridge+ task.
+      # Returns +nil+ when the file is absent, invalid, or contains no recognized formats
+      # (callers should interpret +nil+ as "generate all formats").
+      #
+      # @return [Array<Symbol>, nil]
+      def formats_for_default_bridge_task
+        path = config_path
+        return nil unless path&.file?
+
+        data = load_yaml(path)
+        return nil unless data.is_a?(Hash)
+
+        raw = data["formats"] || data[:formats]
+        return nil if raw.nil?
+
+        fmts = Array(raw).map { |f| f.to_s.downcase.to_sym } & FORMAT_KEYS
+        fmts.empty? ? nil : fmts.uniq
+      end
+
+      # Writes +install.yml+ with the requested formats filtered against {FORMAT_KEYS}.
+      #
+      # @param formats [Array<Symbol, String>] desired format keys
+      # @raise [RailsAiBridge::Error] when +Rails.application+ is unavailable
+      # @return [void]
+      def write!(formats:)
+        path = config_path
+        raise Error, "Rails app not available" unless path
+
+        path.dirname.mkpath
+        list = Array(formats).map { |f| f.to_s.downcase }.uniq & FORMAT_KEYS.map(&:to_s)
+        File.write(path.to_s, YAML.dump({ "formats" => list }))
+      end
+
+      private
+
+      # @param path [Pathname]
+      # @return [Hash, nil] parsed data or +nil+ on syntax/IO error
+      def load_yaml(path)
+        YAML.safe_load(
+          File.read(path),
+          permitted_classes: [ Symbol ],
+          permitted_symbols: [],
+          aliases: true
+        )
+      rescue Psych::SyntaxError, Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/config/auth.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Config
+    # Holds authentication and authorization settings for the MCP HTTP endpoint.
+    #
+    # Strategy priority (highest → lowest):
+    # 1. {#mcp_jwt_decoder} — caller-supplied JWT decoding lambda
+    # 2. {#mcp_token_resolver} — caller-supplied token resolution lambda
+    # 3. {#http_mcp_token} / +ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]+ — static bearer token
+    # 4. None configured — open access
+    #
+    # @see Mcp::Authenticator
+    class Auth
+      # @return [String, nil] static bearer token for HTTP MCP auth
+      attr_accessor :http_mcp_token
+
+      # @return [Boolean] allow auto-mounting the MCP endpoint in production
+      attr_accessor :allow_auto_mount_in_production
+
+      # @return [Proc, nil] lambda resolving a raw bearer token to an auth context
+      attr_accessor :mcp_token_resolver
+
+      # @return [Proc, nil] lambda decoding a raw JWT to a payload hash
+      attr_accessor :mcp_jwt_decoder
+
+      def initialize
+        @http_mcp_token               = nil
+        @allow_auto_mount_in_production = false
+        @mcp_token_resolver           = nil
+        @mcp_jwt_decoder              = nil
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/config/introspection.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Config
+    # Holds introspector selection, exclusion rules, and caching settings.
+    class Introspection
+      # @return [Array<Symbol>] active introspector keys
+      attr_accessor :introspectors
+
+      # @return [Array<String>] directory names excluded from code search
+      attr_accessor :excluded_paths
+
+      # @return [Array<String>] model class names excluded from introspection
+      attr_accessor :excluded_models
+
+      # @return [Array<String>] table names/patterns excluded from schema introspection
+      attr_accessor :excluded_tables
+
+      # @return [Array<Symbol>] product-level category keys that subtract introspectors at runtime
+      attr_accessor :disabled_introspection_categories
+
+      # @return [Integer] TTL in seconds for cached introspection results
+      attr_accessor :cache_ttl
+
+      # @return [Boolean] include credential key names in config introspection output
+      attr_accessor :expose_credentials_key_names
+
+      # @return [Hash{Symbol => Class}] additional custom introspector classes
+      attr_accessor :additional_introspectors
+
+      # @return [Array<String>] extra file extensions allowed for rails_search_code
+      attr_accessor :search_code_allowed_file_types
+
+      def initialize
+        @introspectors      = Configuration::PRESETS[:standard].dup
+        @excluded_paths     = %w[node_modules tmp log vendor .git]
+        @excluded_models    = %w[
+          ApplicationRecord
+          ActiveStorage::Blob ActiveStorage::Attachment ActiveStorage::VariantRecord
+          ActionText::RichText ActionText::EncryptedRichText
+          ActionMailbox::InboundEmail ActionMailbox::Record
+        ]
+        @excluded_tables                   = []
+        @disabled_introspection_categories = []
+        @cache_ttl                         = 30
+        @expose_credentials_key_names      = false
+        @additional_introspectors          = {}
+        @search_code_allowed_file_types    = []
+      end
+
+      # Switch the active introspector list to a named preset.
+      #
+      # @param name [Symbol, String] preset key from {Configuration::PRESETS}
+      # @raise [ArgumentError] when the preset is unknown
+      def preset=(name)
+        name = name.to_sym
+        unless Configuration::PRESETS.key?(name)
+          raise ArgumentError, "Unknown preset: #{name}. Valid presets: #{Configuration::PRESETS.keys.join(', ')}"
+        end
+
+        @introspectors = Configuration::PRESETS[name].dup
+      end
+
+      # Introspectors after removing those disabled by {#disabled_introspection_categories}.
+      #
+      # @return [Array<Symbol>]
+      def effective_introspectors
+        disabled = @disabled_introspection_categories.flat_map do |c|
+          Configuration::INTROSPECTION_CATEGORY_INTROSPECTORS[c.to_sym] || []
+        end.uniq
+        @introspectors.reject { |i| disabled.include?(i) }
+      end
+
+      # Whether a table name matches any {#excluded_tables} pattern (exact or glob).
+      #
+      # @param table_name [String, nil]
+      # @return [Boolean]
+      def excluded_table?(table_name)
+        return false if table_name.nil? || table_name.to_s.empty?
+
+        @excluded_tables.any? { |pat| ExclusionHelper.table_pattern_match?(pat.to_s, table_name.to_s) }
+      end
+    end
+  end
+end