rails-ai-bridge 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 179af8f51240a13daa27c526299db931aaac585186cb55b4f1ca440c24cd66a8
-  data.tar.gz: 295dd64afcefc38f247612020fd9933246a1948123ca785293e5f2350bb39b58
+  metadata.gz: 89c1de6e57a12e9e993e3a6648f08829ebd7c59e975e70b33c1b8a73fd9e940d
+  data.tar.gz: 24b0733e1c31510a0c8876524cb670ec79ff6b53ed7fad477983ddbeff7d23a2
 SHA512:
-  metadata.gz: 98b696d49e6dfd9fffbac01d4cda299b2e0d518eea998bb703dafb71e5577b7d21e9f1024b6d126907808281f48f05cdb73b80c442a72c950c5a8db046198ab5
-  data.tar.gz: a0590ccdc592b161e289313d45f2820b9b793661201b318f68f89c8c4a3535c849d6422327879edd60b7e7a8c14356ab9ea35bcfb4ca9cb6caecf0fac908247d
+  metadata.gz: 8a42be12f415b7957931b3c88cbd5a7ecf81af08357052b9d7d4c5d5ce20c40c0b93ab57a73c02c337e4fd22297780732b6d1dea073d47972df29d371b26456b
+  data.tar.gz: f6b2bc0cec702dc34388dd1606981d8d7169dafa5b35f3715e7dbfb8ac027d651e52d0e5504a7030af9cc92ce9f99d7ee4281e7fed54f6324149c10fc2c84c9d

data/CHANGELOG.md

@@ -5,8 +5,27 @@ 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

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

@@ -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, 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)
@@ -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`) 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/`

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).
+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 **9 MCP tools** so assistants pull detail on demand (`detail: "summary"` first, then drill down).
+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>
 
 ---
@@ -303,6 +313,8 @@ 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
@@ -360,13 +372,13 @@ This keeps token usage low and answer quality high. Requesting full detail on ev
 | 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 |
+| `: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[views auth api]
+config.introspectors += %i[non_ar_models views auth api]
 ```
 
 ### Check your readiness score
@@ -384,11 +396,11 @@ Prints a 0–100 AI readiness score and flags anything missing: `.mcp.json`, gen
 ```ruby
 # config/initializers/rails_ai_bridge.rb
 RailsAiBridge.configure do |config|
-  # Presets: :standard (9 introspectors, default) or :full (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
@@ -396,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]
 
@@ -415,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 |
@@ -427,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
@@ -521,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).