rails-ai-bridge 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8392971b0bc2f8bf98ebe626062b79e7ff271e8aa009ace229702948862eace
-  data.tar.gz: d3e358ef11eef6c9050289d73ab69ec5ad09684d7d8e7d8b25b5da4350306c9e
+  metadata.gz: 89c1de6e57a12e9e993e3a6648f08829ebd7c59e975e70b33c1b8a73fd9e940d
+  data.tar.gz: 24b0733e1c31510a0c8876524cb670ec79ff6b53ed7fad477983ddbeff7d23a2
 SHA512:
-  metadata.gz: d174446e69dddabd9f99457af197d607793f26b09ef346f2c27f124be15700fb1b7961e4ba76dd43959d32bfcfe108787c611505043ecf12e61ba7fd1735b7e9
-  data.tar.gz: 6bb2d7c5290441e76359de520d3e7e737890d3d6456b6e269bfba579c79540a900cccdd872ec580dc5d392c09c6f053e2f0516842aa8e222f0d994111de2b5de
+  metadata.gz: 8a42be12f415b7957931b3c88cbd5a7ecf81af08357052b9d7d4c5d5ce20c40c0b93ab57a73c02c337e4fd22297780732b6d1dea073d47972df29d371b26456b
+  data.tar.gz: f6b2bc0cec702dc34388dd1606981d8d7169dafa5b35f3715e7dbfb8ac027d651e52d0e5504a7030af9cc92ce9f99d7ee4281e7fed54f6324149c10fc2c84c9d

data/CHANGELOG.md

@@ -5,8 +5,41 @@ 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).
 
+## [2.2.0] - 2026-04-04
+
+### Added
+
+- **`non_ar_models` introspector** — Lists Ruby classes under `app/models` that are not ActiveRecord models, tagged **`[POJO/Service]`** in MCP listings and `.claude/rules/rails-models.md`. Context key: `:non_ar_models` with `{ non_ar_models: [{ name, relative_path, tag }] }`. **Not** in `:standard` or `:full` presets (opt in via `config.introspectors << :non_ar_models`). Included in the `domain_metadata` disable category when enabled.
+- **Model semantic classification** — Each ActiveRecord model in introspection output now includes `semantic_tier` (`core_entity`, `pure_join`, `rich_join`, `supporting`) and `semantic_tier_reason` for MCP transparency. Join tables used in `has_many :through` are detected; payload columns beyond FKs and metadata yield `rich_join`.
+- **`config.core_models`** — List model class names to tag as `core_entity` for AI-focused context (initializer comment + `Config::Introspection`).
+- **`RailsAiBridge::ModelSemanticClassifier`** — PORO that computes tiers from columns, `belongs_to` foreign keys, and through-association membership.
+- **`.claude/rules/rails-context.md`** — Semantic layer summary (app metadata + models grouped by tier) for Claude Code, alongside existing split rules.
+
+### Changed
+
+- **`rails-context.md` tier lists** — In compact `context_mode`, at most 20 model names per `semantic_tier` with an overflow line referencing `rails_get_model_details(detail:"summary")`; full mode lists all names per tier.
+- **Claude rules `rails-models.md`** — Each model line includes `tier: …` when present.
+- **`rails_get_model_details` formatters** — Summary, standard, full, and single-model views include semantic tier where applicable.
+- **Combustion test setup** — `Combustion.path` is set to `spec/internal`, `Combustion::Database.setup` runs after boot so `:memory:` SQLite has schema before examples, and the internal `ExampleJob` no longer subclasses `ActiveJob::Base` (Active Job is not loaded in the minimal stack).
+
 ## [Unreleased]
 
+_Targeting **v2.3.0** when Phase 2–3 and final review are done; gem version remains **2.2.0** until that release tag._
+
+## [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

data/CLAUDE.md

@@ -8,8 +8,8 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `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/introspectors/` — Built-in introspector classes; `:standard` preset runs **9**, `:full` runs **26** (see `Configuration::PRESETS`). Registry: `Introspector::BUILTIN_INTROSPECTORS` (includes opt-in symbols such as `database_stats`, `non_ar_models` not listed in those presets).
+- `lib/rails_ai_bridge/tools/` — 11 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
 - `lib/rails_ai_bridge/serializers/` — Output formatters (claude, claude_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON)
 - `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)
@@ -30,7 +30,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 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
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (26 introspectors; optional extras such as `database_stats`, `non_ar_models`) 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/`
@@ -38,7 +38,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (364 examples)
+bundle exec rspec           # Run specs
 bundle exec rubocop         # Lint
 ```
 

data/CONTRIBUTING.md

@@ -18,8 +18,8 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 
 ```
 lib/rails_ai_bridge/
-├── introspectors/     # 27 introspectors (schema, models, routes, etc.)
-├── tools/             # 9 MCP tools with detail levels and pagination
+├── introspectors/     # Built-in introspectors (schema, models, non_ar_models, routes, …)
+├── tools/             # 11 built-in MCP tools (detail levels, pagination, extensible)
 ├── serializers/       # Per-assistant formatters (claude, cursor, windsurf, copilot, JSON)
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── engine.rb          # Rails Engine for auto-integration
@@ -30,7 +30,7 @@ lib/rails_ai_bridge/
 
 1. Create `lib/rails_ai_bridge/introspectors/your_introspector.rb` (auto-loaded by Zeitwerk)
 2. Implement `#initialize(app)` and `#call` → returns a Hash (never raises)
-3. Register it in `lib/rails_ai_bridge/introspector.rb` (the `INTROSPECTOR_MAP`)
+3. Register it in `lib/rails_ai_bridge/introspector.rb` (`BUILTIN_INTROSPECTORS`)
 4. Add the key to the appropriate preset(s) in `Configuration::PRESETS` (`:standard` for core, `:full` for all)
 5. Write specs in `spec/lib/rails_ai_bridge/your_introspector_spec.rb`
 
@@ -45,6 +45,8 @@ lib/rails_ai_bridge/
 ## Code Style
 
 - Follow `rubocop-rails-omakase` style (run `bundle exec rubocop`)
+- Optional complexity check: `bundle exec skunk lib/rails_ai_bridge/…` (gem in `:development`/`:test`) — keep new or refactored files lean (project goal: Skunk score around **≤ 25** where practical).
+
 - Ruby 3.2+ features welcome (pattern matching, etc.)
 - Every introspector must return a Hash and never raise — wrap errors in `{ error: msg }`
 - MCP tools return `MCP::Tool::Response` objects

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/` — Built-in introspector classes; `:standard` preset runs **9**, `:full` runs **26** (see `Configuration::PRESETS`). Registry: `Introspector::BUILTIN_INTROSPECTORS` (includes opt-in symbols such as `database_stats`, `non_ar_models` not listed in those presets).
+- `lib/rails_ai_bridge/tools/` — 11 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
+- `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 introspectors; optional extras such as `database_stats`) 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

@@ -7,6 +7,7 @@
 [![Gem Version](https://badge.fury.io/rb/rails-ai-bridge.svg)](https://rubygems.org/gems/rails-ai-bridge)
 [![CI](https://github.com/igmarin/rails-ai-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/igmarin/rails-ai-bridge/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/igmarin/rails-ai-bridge?utm_source=oss&utm_medium=github&utm_campaign=igmarin%2Frails-ai-bridge&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
 
 ---
 
@@ -31,9 +32,9 @@ flowchart LR
   app --> intro --> mcp --> clients
 ```
 
-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.
-3. **`rails ai:serve`** exposes **9 MCP tools** so assistants pull detail on demand (`detail: "summary"` first, then drill down).
+1. **Up to 26 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).
 
 ### Folder guides
 
@@ -94,7 +95,7 @@ The install generator creates **`.mcp.json`** (MCP auto-discovery) and generates
 | Zero config | Yes — Railtie + install generator | No — per-project `projects.yml` | No |
 | Token optimization | Yes — compact files + `detail:"summary"` workflow | Varies | No |
 | Codex-oriented repo files | Yes — `AGENTS.md`, `.codex/README.md` | No | DIY |
-| Live MCP tools | Yes — 9 read-only `rails_*` tools | Yes | No |
+| Live MCP tools | Yes — 11 read-only `rails_*` tools (extensible) | Yes | No |
 | Auto-introspection | Yes — up to **27** domains (`:full`) | No — server points at projects you configure | DIY |
 
 *Comparison reflects typical documented setups; verify against each project before treating any row as absolute.*
@@ -111,8 +112,9 @@ your-rails-app/
 ├── 🟣 Claude Code
 │   ├── CLAUDE.md                                         ≤150 lines (compact)
 │   └── .claude/rules/
+│       ├── rails-context.md                              semantic layer (compact: capped per tier + MCP hint)
 │       ├── rails-schema.md                               table listing
-│       ├── rails-models.md                               model listing
+│       ├── rails-models.md                               model listing (includes semantic tier)
 │       └── rails-mcp-tools.md                            full tool reference
 │
 ├── 🟡 OpenAI Codex
@@ -142,6 +144,9 @@ your-rails-app/
 │       ├── rails-controllers.instructions.md             applyTo: app/controllers/**
 │       └── rails-mcp-tools.instructions.md               applyTo: **/*
 │
+├── 🔴 Gemini
+│   └── GEMINI.md                                         directive briefing + MCP guide
+│
 ├── 📋 .ai-context.json                                   full JSON (programmatic)
 └── .mcp.json                                             MCP auto-discovery
 ```
@@ -157,7 +162,8 @@ 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 |
-| **Models** | Associations, validations, scopes, enums, callbacks, concerns, macros (`has_secure_password`, `encrypts`, `normalizes`, etc.) |
+| **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 |
 | **Views** | Layouts, templates, partials, helpers, template engines, view components |
@@ -171,25 +177,27 @@ Each file respects the AI tool's format and size limits. **Commit these files**
 | **DevOps** | Puma, Procfile, Docker, deployment tools, asset pipeline |
 | **Architecture** | Service objects, STI, polymorphism, state machines, multi-tenancy, engines |
 
-27 introspectors total. The `:standard` preset runs 9 core ones by default; use `:full` for all 27.
+The `:full` preset runs 26 introspectors. The `:standard` preset runs 9 core ones by default. Add symbols such as `:non_ar_models` or `:database_stats` to `config.introspectors` when you need them.
 
 ---
 
 ## MCP Tools
 
-The gem exposes **9 live tools** via MCP that AI clients call on-demand:
+The gem exposes **11 built-in tools** via MCP that AI clients call on-demand (hosts can append more via `config.additional_tools`):
 
 | Tool | What it returns |
 |------|----------------|
 | `rails_get_schema` | Tables, columns, indexes, foreign keys |
-| `rails_get_model_details` | Associations, validations, scopes, enums, callbacks |
+| `rails_get_model_details` | Associations, validations, scopes, enums, callbacks, semantic tier, non-AR models (when enabled) |
 | `rails_get_routes` | HTTP verbs, paths, controller actions |
 | `rails_get_controllers` | Actions, filters, strong params, concerns |
 | `rails_get_config` | Cache, session, timezone, middleware, initializers |
 | `rails_get_test_info` | Test framework, factories, CI config, coverage |
 | `rails_get_gems` | Notable gems categorized by function |
 | `rails_get_conventions` | Architecture patterns, directory structure |
-| `rails_search_code` | Ripgrep-powered regex search across the codebase |
+| `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_stimulus` | Stimulus controllers: targets, values, actions, outlets (requires `:stimulus` introspector) |
 
 All tools are **read-only** — they never modify your application or database.
 
@@ -280,12 +288,14 @@ RailsAiBridge.configure do |config|
   # Production only: explicit opt-in + token required (see SECURITY.md)
   # config.allow_auto_mount_in_production = true
   config.http_path  = "/mcp"
+  # Optional: reject HTTP requests when no Bearer/JWT/static auth is configured (safer beyond localhost)
+  # config.mcp.require_http_auth = true
 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`.
+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)**.
 </details>
 
 ---
@@ -301,16 +311,96 @@ 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 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` | 26 | 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[non_ar_models 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
 # config/initializers/rails_ai_bridge.rb
 RailsAiBridge.configure do |config|
-  # Presets: :standard (9 introspectors, default) or :full (all 27)
+  # Presets: :standard (9 introspectors, default) or :full (26). Add :non_ar_models etc. as needed.
   config.preset = :standard
 
   # Cherry-pick on top of a preset
-  # config.introspectors += %i[views turbo auth api]
+  # config.introspectors += %i[non_ar_models views turbo auth api]
 
   # Context mode: :compact (≤150 lines, default) or :full (dump everything)
   # config.context_mode = :compact
@@ -318,6 +408,9 @@ RailsAiBridge.configure do |config|
   # Exclude models from introspection
   config.excluded_models += %w[AdminUser InternalAuditLog]
 
+  # Tag primary domain models as core_entity (semantic context for AI + Claude rules)
+  # config.core_models += %w[User Order Project]
+
   # Exclude paths from code search
   config.excluded_paths += %w[vendor/bundle]
 
@@ -337,11 +430,18 @@ end
 | `claude_max_lines` | `150` | Max lines for CLAUDE.md in compact mode |
 | `max_tool_response_chars` | `120_000` | Safety cap for MCP tool responses |
 | `excluded_models` | internal Rails models | Models to skip during introspection |
+| `core_models` | `[]` | Model names tagged as `core_entity` in introspection and `.claude/rules/` |
 | `excluded_paths` | `node_modules tmp log vendor .git` | Paths excluded from code search |
 | `auto_mount` | `false` | Auto-mount HTTP MCP endpoint |
 | `allow_auto_mount_in_production` | `false` | Allow `auto_mount` in production (requires MCP token) |
 | `http_mcp_token` | `nil` | Bearer token for HTTP MCP; `ENV["RAILS_AI_BRIDGE_MCP_TOKEN"]` overrides when set |
 | `search_code_allowed_file_types` | `[]` | Extra extensions allowed for `rails_search_code` `file_type` |
+| `search_code_pattern_max_bytes` | `2048` | Maximum `pattern` size (bytes) for `rails_search_code` |
+| `search_code_timeout_seconds` | `5.0` | Wall-clock limit per search (`0` disables); mitigates runaway regex / CPU |
+| `require_http_auth` | `false` | When `true`, HTTP MCP returns `401` if no Bearer/JWT/static auth is configured |
+| `rate_limit_max_requests` | `nil` (profile default) | Per-IP sliding window ceiling (`0` disables); not shared across workers |
+| `rate_limit_window_seconds` | `60` | Sliding window length for HTTP rate limiting |
+| `http_log_json` | `false` | One JSON log line per HTTP MCP response when enabled |
 | `expose_credentials_key_names` | `false` | Include `credentials_keys` in config introspection / `rails://config` |
 | `additional_introspectors` | `{}` | Optional custom introspector classes keyed by symbol |
 | `additional_tools` | `[]` | Optional MCP tool classes appended to the built-in toolset |
@@ -349,6 +449,8 @@ end
 | `http_path` | `"/mcp"` | HTTP endpoint path |
 | `http_port` | `6029` | HTTP server port |
 | `cache_ttl` | `30` | Cache TTL in seconds |
+
+Other HTTP MCP knobs live only on the nested object, for example `RailsAiBridge.configuration.mcp.authorize`, `mcp.mode`, `mcp.security_profile`, and `mcp.require_auth_in_production` — see [docs/GUIDE.md](docs/GUIDE.md) and [docs/mcp-security.md](docs/mcp-security.md).
 </details>
 
 ### Extending the built-ins
@@ -402,6 +504,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) |
@@ -442,23 +545,33 @@ 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 |
+
+---
+
 ## Contributing
 
 ```bash
 git clone https://github.com/igmarin/rails-ai-bridge.git
 cd rails-ai-bridge && bundle install
-bundle exec rspec       # runs the full suite; SimpleCov runs locally by default
-bundle exec rubocop     # Lint
+bundle exec rspec       # runs the full suite (SimpleCov enforces ≥80% coverage)
+bundle exec rubocop     # lint
 ```
 
-### Test coverage (SimpleCov)
-
-- Running `bundle exec rspec` locally enables **SimpleCov** and enforces **at least 80% line coverage** across `lib/**/*.rb` (see [`spec/simplecov_helper.rb`](spec/simplecov_helper.rb)).
-- After the run, open **`coverage/index.html`** in a browser for a per-file report (`coverage/` is gitignored).
-- CI runs coverage enforcement on **one matrix job** (Ruby **3.3** + Rails **8.0**) with `COVERAGE=true` and uploads the HTML report as a workflow artifact for inspection on PRs.
-- For a **prioritized backlog of files below 80%** (refreshed after substantive test work), see [`docs/COVERAGE.md`](docs/COVERAGE.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide: adding introspectors, adding MCP tools, code style rules, PR process, and the maintainer release checklist.
 
-Bug reports and pull requests for this fork are handled at [github.com/igmarin/rails-ai-bridge](https://github.com/igmarin/rails-ai-bridge).
+Bug reports and pull requests: [github.com/igmarin/rails-ai-bridge/issues](https://github.com/igmarin/rails-ai-bridge/issues)
 
 ## Acknowledgments & Origins
 

data/SECURITY.md

@@ -27,17 +27,20 @@ This fork is maintained by **Ismael Marin**. If you discover a security vulnerab
 - Code search (`rails_search_code`) uses `Open3.capture2` with array arguments to prevent shell injection.
 - File paths are validated against path traversal attacks, and invalid regex input now returns a controlled tool response in the Ruby fallback path.
 - Search is limited to an **allowlisted set of file extensions** by default; arbitrary extensions (e.g. `key`, `pem`, `env`) are rejected. See `config.search_code_allowed_file_types` to extend the list.
+- `rails_search_code` caps **pattern length** (`config.search_code_pattern_max_bytes`, default 2048) and applies an optional **wall-clock timeout** per invocation (`config.search_code_timeout_seconds`, default 5; `0` disables).
 - Credential **values** are never exposed. Top-level **key names** from encrypted credentials are omitted from introspection and the `rails://config` resource by default; set `config.expose_credentials_key_names = true` only if you accept that metadata exposure.
 - The gem does not make any outbound network requests.
 - The main risk is **information exposure**, not mutation: schema names, routes, controller structure, and code excerpts may still be sensitive in some environments.
 
 ## HTTP MCP authentication
 
+For day-to-day hardening (tokens, `require_http_auth`, proxies, stdio threat model), see **[docs/mcp-security.md](docs/mcp-security.md)**.
+
 - **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.
+- **`require_http_auth`:** set `config.require_http_auth = true` (or `config.mcp.require_http_auth = true`) so HTTP MCP returns **401** when no auth strategy is configured — useful when the bind address is not strictly localhost.
 - **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).