rails-ai-bridge 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94459120e6365ac608ed9a403e16a622e7ef664b377f8585980827c28dd911f0
-  data.tar.gz: e3561760ceb930242a6d344ae3938dfdca49879639e7776a19cc2fa08adff4eb
+  metadata.gz: 179af8f51240a13daa27c526299db931aaac585186cb55b4f1ca440c24cd66a8
+  data.tar.gz: 295dd64afcefc38f247612020fd9933246a1948123ca785293e5f2350bb39b58
 SHA512:
-  metadata.gz: c595b9b20dc56cef6adf370d931f06083137691cd5323dd8fe43615eba819eb7d725d5ee62160c0305fb311f3d2592ad767cd2eb8b69bfc3f075aae380b9209e
-  data.tar.gz: d6ee1293103eccc654bbed37f67b9deb022ecede51ee8bc4f4714db86f7f18d73a3ebe0054d86c6c8350107dd1bf6239520ff137c5b828faeb75152095c158bd
+  metadata.gz: 98b696d49e6dfd9fffbac01d4cda299b2e0d518eea998bb703dafb71e5577b7d21e9f1024b6d126907808281f48f05cdb73b80c442a72c950c5a8db046198ab5
+  data.tar.gz: a0590ccdc592b161e289313d45f2820b9b793661201b318f68f89c8c4a3535c849d6422327879edd60b7e7a8c14356ab9ea35bcfb4ca9cb6caecf0fac908247d

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,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-04-02
+
+### Added
+
+- **Gemini Support:** Added support for Google's Gemini AI assistant via `GEMINI.md`.
+- **New Rake Task:** Added `rails ai:bridge:gemini` to generate Gemini-specific context.
+- **Context Harmonization:** Refactored all provider serializers (Claude, Gemini, Codex, Copilot, Cursor, Windsurf) to use a shared `BaseProviderSerializer`.
+- **Enhanced AI Guidance:** All context files now feature directive headers, complexity-sorted model lists, and explicit behavioral rules to improve AI code generation.
+- **Improved Metadata:** Context files now include descriptions for key config files and standard maintenance commands (e.g., `rubocop`).
+
+### Changed
+
+- **Internal Refactor:** Extracted common rendering logic into `RailsAiBridge::Serializers::Providers::BaseProviderSerializer` to ensure consistency and maintainability across all AI assistants.
+
+## [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 +31,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/GEMINI.md

@@ -0,0 +1,55 @@
+# GEMINI.md — rails-ai-bridge development guide
+
+This is a Ruby gem that auto-introspects Rails applications and exposes their
+structure to AI assistants via the Model Context Protocol (MCP).
+
+## Architecture
+
+- `lib/rails_ai_bridge.rb` — Main entry point, public API (Zeitwerk autoloaded)
+- `lib/rails_ai_bridge/configuration.rb` — User-facing config with presets (:standard, :full)
+- `lib/rails_ai_bridge/introspector.rb` — Orchestrates sub-introspectors
+- `lib/rails_ai_bridge/introspectors/` — 27 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database)
+- `lib/rails_ai_bridge/tools/` — 9 MCP tools using the official mcp SDK
+- `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, gemini)
+- `lib/rails_ai_bridge/resources.rb` — MCP resources (static data AI clients read directly)
+- `lib/rails_ai_bridge/server.rb` — MCP server configuration (stdio + HTTP transports)
+- `lib/rails_ai_bridge/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
+- `lib/rails_ai_bridge/fingerprinter.rb` — SHA256 file fingerprinting for cache invalidation
+- `lib/rails_ai_bridge/doctor.rb` — Diagnostic checks and AI readiness scoring
+- `lib/rails_ai_bridge/watcher.rb` — File watcher for auto-regenerating context files
+- `lib/rails_ai_bridge/engine.rb` — Rails Engine for auto-integration
+- `lib/generators/rails_ai_bridge/install/` — Install generator (creates .mcp.json, initializer, context files)
+
+## Key Design Decisions
+
+1. **Built on official mcp SDK** — not a custom protocol implementation
+2. **Zero-config** — Railtie auto-registers at boot, introspects without setup
+3. **Graceful degradation** — works without DB by parsing schema.rb as text
+4. **Read-only tools only** — all MCP tools are annotated as non-destructive
+5. **Dual output** — static files (GEMINI.md) + live MCP server (stdio/HTTP)
+6. **Diff-aware** — context regeneration skips unchanged files
+7. **Per-assistant serializers** — each AI tool gets tailored output format
+8. **Zeitwerk autoloading** — files loaded on-demand, not all upfront
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (26) for power users
+10. **MCP auto-discovery** — `.mcp.json` generated by install generator
+11. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
+12. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
+
+## Testing
+
+```bash
+bundle exec rspec           # Run specs (364 examples)
+bundle exec rubocop         # Lint
+```
+
+Uses combustion gem for testing Rails engine behavior in isolation.
+
+## Conventions
+
+- Ruby 3.2+ features OK (pattern matching, etc.)
+- Follow rubocop-rails-omakase style
+- Every introspector returns a Hash, never raises (wraps errors in `{ error: msg }`)
+- MCP tools return `MCP::Tool::Response` objects per SDK convention
+- All tools prefixed with `rails_` per MCP naming best practices
+- `generate_context` returns `{ written: [], skipped: [] }` hash
+- Zeitwerk autoloads all files — no `require_relative` needed for new classes

data/README.md

@@ -32,7 +32,7 @@ flowchart LR
 ```
 
 1. **Up to 27 introspectors** scan schema, models, routes, controllers, jobs, gems, conventions, and more (preset `:standard` runs 9 core ones by default; `:full` runs all).
-2. **`rails ai:bridge`** writes bounded bridge files for Claude, Cursor, Copilot, Codex, Windsurf, and JSON.
+2. **`rails ai:bridge`** writes bounded bridge files for Claude, Cursor, Copilot, Codex, Windsurf, Gemini, and JSON.
 3. **`rails ai:serve`** exposes **9 MCP tools** so assistants pull detail on demand (`detail: "summary"` first, then drill down).
 
 ### Folder guides
@@ -301,6 +301,84 @@ Codex support is centered on **`AGENTS.md`** at the repository root.
 
 ---
 
+## Best Practices
+
+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 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.
+
+**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:
+
+```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.
+
+### 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.
+
+### Pick the right preset for your app
+
+| Preset | Introspectors | Best for |
+|--------|--------------|---------|
+| `:standard` (default) | 9 core | Most apps — schema, models, routes, jobs, gems, conventions |
+| `:full` | 27 | Full-stack apps where frontend, auth, API, and DevOps context matter |
+
+Add individual introspectors on top of a preset for targeted additions:
+
+```ruby
+config.preset = :standard
+config.introspectors += %i[views auth api]
+```
+
+### Check your readiness score
+
+```bash
+rails ai:doctor
+```
+
+Prints a 0–100 AI readiness score and flags anything missing: `.mcp.json`, generated context files, MCP token in production, and more. Run it after initial setup and after major configuration changes.
+
+---
+
 ## Configuration
 
 ```ruby
@@ -402,6 +480,7 @@ Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — t
 | `rails ai:bridge:cursor` | Generate Cursor files only |
 | `rails ai:bridge:windsurf` | Generate Windsurf files only |
 | `rails ai:bridge:copilot` | Generate Copilot files only |
+| `rails ai:bridge:gemini` | Generate Gemini files only |
 | `rails ai:serve` | Start MCP server (stdio) |
 | `rails ai:serve_http` | Start MCP server (HTTP) |
 | `rails ai:doctor` | Run diagnostics and AI readiness score (0-100) |

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,29 @@
+# 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.
+## Done
+
+- Separate LLM provider serializers from domain infrastructure (done: `Serializers::Providers::` namespace).
+- 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).
+
+## In progress
+
+- 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,58 @@
+# 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 |
+| Major release (2.0.0) | Done |
+
+---
+
+## v2.1.0 — Gemini & Harmonization
+
+| Area | Status |
+|------|--------|
+| Gemini Support (`GEMINI.md`, `GeminiSerializer`, Rake task) | Done |
+| Context Harmonization (Shared `BaseProviderSerializer`) | Done |
+| Enhanced directive guidance for all assistants | Done |
+| Release (2.1.0) | Done |
+
+---
+
+## 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
 
@@ -140,6 +168,7 @@ module RailsAiBridge
         say "  rails ai:bridge:claude   # Generate CLAUDE.md only"
         say "  rails ai:bridge:codex    # Generate AGENTS.md only"
         say "  rails ai:bridge:cursor   # Generate .cursorrules only"
+        say "  rails ai:bridge:gemini   # Generate GEMINI.md only"
         say "  rails ai:serve           # Start MCP server (stdio)"
         say "  rails ai:inspect         # Print introspection summary"
         say ""
@@ -149,6 +178,7 @@ module RailsAiBridge
         say "  Cursor         → .cursorrules + .cursor/rules/*.mdc (incl. rails-engineering.mdc)"
         say "  Windsurf       → .windsurfrules + .windsurf/rules/*.md"
         say "  GitHub Copilot → .github/copilot-instructions.md + .github/instructions/*.instructions.md"
+        say "  Gemini         → GEMINI.md"
         say ""
         say "MCP auto-discovery:", :yellow
         say "  .mcp.json is auto-detected by Claude Code and Cursor."