rails-ai-bridge 4.1.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7810f4efa4400b60d813b2344b82f38e0a731ccc89e68a3be51aabe2526a3d
-  data.tar.gz: 7faa7fe7f2f731d572806596a3f60d756d85b589ba46b6dfa7ef2e614bea8749
+  metadata.gz: d937341388cd5f16ca5c4df0bfb3e540b0aabd88f21fb7edd8a99c4109a504e2
+  data.tar.gz: 92b5ef03eed9e1a2a3c2f3161543e2f3143724e2af146b941a83b159ca9f7324
 SHA512:
-  metadata.gz: 1d4cf0bdcf2dcf203a30b112ac940709dcf3222af18efaeb10625d08594197f38d49cfb23f5edc328fce6a4fd6242b02aa545cb6075c5c142ab81b3a5b89d1d5
-  data.tar.gz: 2f7dad1ecef89cc739b7a8031f16e753b0b4a55bdabbc52f8692f6b42f05f0cf7a14acc80700d819f401649eb384fc7109d98569372462f651eee2ea608d7767
+  metadata.gz: '09bdcacd48c5a46c069a90468cd772b0179d4b5464cd48438923b27e8ac8e4895afbcaecfa08136bd70e51231d70a439dfb4ddc5b3b153488fa1f16caf1ed22c'
+  data.tar.gz: 64715803d3c38e8827dfdd9200bbed447663d5751854193f1ae5f5a818c8eb9f2a9aabbf14fc3c84bc1a79b47f48e8bf3007cd6b1f26f10c1dab98771f300f74

data/.aider.conf.yml

@@ -0,0 +1,23 @@
+read:
+  - AGENTS.md
+  - repomix.config.json
+
+mcp_servers:
+  codegraph:
+    command: "/Users/igmarin/.local/bin/codegraph"
+    args:
+      - serve
+      - --mcp
+      - --path
+      - "/Volumes/minimini/Developer/Projects/rails-ai-bridge"
+  graphify:
+    command: "/Users/igmarin/.local/bin/graphify-mcp"
+    args:
+      - --graph
+      - "/Volumes/minimini/Developer/Projects/rails-ai-bridge/graphify-out/graph.json"
+  repomix:
+    command: "/opt/homebrew/bin/repomix"
+    args:
+      - --mcp
+      - --sandbox
+      - "/Volumes/minimini/Developer/Projects/rails-ai-bridge"

data/.graphifyignore

@@ -0,0 +1,19 @@
+.git
+.idea
+.cursor
+.claude
+.grok
+.zed
+.codegraph
+graphify-out
+repomix-output.xml
+repomix-output.md
+coverage
+review-result.txt
+rs-guard-metrics.json
+*.gem
+.DS_Store
+tmp/
+doc/
+vendor/bundle/
+coverage/

data/.mutant.yml

@@ -0,0 +1,29 @@
+---
+# Mutant configuration for rails-ai-bridge critical paths.
+#
+# Run with: BUNDLE_GEMFILE=Gemfile-mutation bundle exec mutant run [subject expressions]
+# Example: BUNDLE_GEMFILE=Gemfile-mutation bundle exec mutant run RailsAiBridge::Registry::FrontmatterParser
+#
+# The open-source usage mode is used because rails-ai-bridge is an
+# open-source project. A commercial license is required for private
+# repositories or advanced features (full operator set, isolation).
+#
+# Target: >80% mutation coverage on registry/tools.
+#
+# Subject expressions are passed on the CLI to target critical paths:
+#   RailsAiBridge::Registry            — registry resolution
+#   RailsAiBridge::Tools               — MCP tools
+#   RailsAiBridge::Tools::SearchCode::Validator
+#   RailsAiBridge::ViewFileAnalyzer
+#   RailsAiBridge::ExclusionHelper
+#   RailsAiBridge::Serializers         — output serializers
+usage: opensource
+integration: rspec
+includes:
+  - lib
+  - spec
+requires:
+  - spec_helper
+fail_fast: false
+mutation:
+  timeout: 5.0

data/.rubocop.yml

@@ -9,6 +9,7 @@ AllCops:
     - "vendor/**/*"
     - "spec/internal/**/*"
     - "gemfiles/**/*"
+    - ".mutant.yml"
 Naming/FileName:
   Exclude:
     - "lib/rails-ai-bridge.rb"
@@ -39,6 +40,8 @@ Layout/LineLength:
   Max: 180
 Metrics/ModuleLength:
   Max: 240
+  Exclude:
+    - "lib/rails_ai_bridge/resources.rb"
 Metrics/MethodLength:
   Max: 70
 RSpec/NestedGroups:
@@ -57,6 +60,12 @@ RSpec/MultipleDescribes:
   Enabled: false
 RSpec/MessageSpies:
   Enabled: false
+RSpec/Output:
+  Exclude:
+    - "spec/support/perf_baseline.rb"
+Rails/RakeEnvironment:
+  Exclude:
+    - "lib/tasks/*.rake"
 Metrics/PerceivedComplexity:
   Max: 35
   Exclude:

data/AGENTS.md

@@ -1,16 +1,16 @@
 # AGENTS.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).
+Ruby gem that reads a Rails app and gives assistants that map over MCP and
+committed context files. It does not write to the host database.
 
 ## 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/` — 16 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
-- `lib/rails_ai_bridge/serializers/` — Output formatters (Codex, claude_rules, cursor_rules, devin, devin_rules, copilot, copilot_instructions, rules, markdown, JSON)
+- `lib/rails_ai_bridge/introspectors/` — Built-in introspector classes; `:standard` preset runs **9**, `:full` runs **27** (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/` — 19 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, codex, cursor_rules, devin, devin_rules, copilot, copilot_instructions, gemini, 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)
 - `lib/rails_ai_bridge/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
@@ -30,10 +30,10 @@ 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 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 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** — `.Codex/rules/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`
+12. **Per-tool split rules** — `.codex/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`
 
 ## Testing
 
@@ -54,9 +54,38 @@ Uses combustion gem for testing Rails engine behavior in isolation.
 - `generate_context` returns `{ written: [], skipped: [] }` hash
 - Zeitwerk autoloads all files — no `require_relative` needed for new classes
 
+## Multi-Issue Workflow
+
+When working on a milestone with 3+ issues:
+
+- **Group** issues by independence — parallel work streams get one git worktree each
+- **Stack** dependent PRs within a group using `gh stack` (each PR's base is the previous branch)
+- **Merge** bottom-up: the first PR in a stack merges to `main`, then `gh stack rebase` restacks the rest
+- **Clean up** worktrees after all PRs in a group are merged
+
+```bash
+# One worktree per independent group
+git worktree add ../project-worktrees/group-a -b group-a-branch
+
+# Stack dependent PRs within a group
+gh stack create "feat: description (#issue)"
+
+# Restack after bottom PR merges
+gh stack rebase
+```
+
 <!-- lean-ctx -->
 ## lean-ctx
 
 Prefer lean-ctx MCP tools over native equivalents for token savings.
 Full rules: @LEAN-CTX.md
 <!-- /lean-ctx -->
+
+## Code intelligence
+
+Use these tools before dumping whole files or grepping the tree.
+
+1. If `.codegraph/` exists, run `codegraph explore "<symbol or question>"` (or the CodeGraph MCP tools).
+2. If `graphify-out/graph.json` exists, use Graphify (`graphify explain`, `graphify path`, or the Graphify MCP).
+3. For a whole-repo pack, run `repomix` using `repomix.config.json`. Do not commit `repomix-output.*`.
+4. Regenerate Graphify with `graphify extract . --backend deepseek --no-cluster` (DeepSeek is the global LLM). Rust workspaces also pass `--cargo`.

data/CHANGELOG.md

@@ -5,6 +5,76 @@ 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).
 
+## [Unreleased]
+
+## [4.3.0] - 2026-08-16
+
+### Added
+
+- **PathResolver glob/file cap** — `config.introspection.max_files_per_path` (default `2000`) truncates `PathResolver#glob_for` and `#files_for` after a stable sort. Documented alongside `snapshot_ttl` (5s section snapshot; raise for HTTP MCP only), `cache_ttl` (30s), and `parallel_introspection` (off).
+- **Inherited controller filters** (#190) — `rails_get_controllers` lists `before_action` / `after_action` filters from the controller and its ancestors. Filters whose `only` / `except` do not apply to any action are omitted. `detail: summary` stays at filter names; `standard` / `full` include the defining class. ActionFilter `only`/`except` conditions are parsed on Rails 7.1+.
+- **MCP exclusion parity spec** (#186) — `spec/lib/rails_ai_bridge/mcp/exclusion_parity_spec.rb` fails when `Server::TOOLS` or resource templates grow without a policy entry, and asserts `excluded_models`, `excluded_tables`, `:regulated`, and `disabled_introspection_categories` do not leak omitted names through listing tools or `rails://` resources. Composite `rails_get_context` is a listing-surface policy row, invoked only when that tool is already in `Server::TOOLS` (#181).
+- **`rails_explain_symbol` MCP tool** (#192) — optional in-process explanation of a `symbol` or `query` from a **local** CodeGraph index (`.codegraph/`). Runs `codegraph explore` with a timeout and argv arrays (no shell, no network). Missing index or CLI failure returns setup instructions (`codegraph init` / `codegraph index`) instead of raising. Always registered so doc-parity stays a single tool list. Built-in MCP tools: **19**.
+- **`rails_get_context` MCP tool** (#181) — in-process composite for one model, controller, or feature (table + model + routes + controller actions/filters + cheap related tests). Reuses `[VERIFIED]` / `[INFERRED]` tags from #187. No HTTP; provider fan-out stays on a different name. Built-in MCP tools: **19**.
+- **Confidence tags on schema and model MCP tools** (#187) — `rails_get_schema` and `rails_get_model_details` markdown now marks facts as `[VERIFIED]` (live ActiveRecord reflection or rubydex/Prism) or `[INFERRED]` (source-regex macros and static schema parses). Missing sections are omitted rather than tagged empty.
+- **Shared anti-hallucination rules in compact assistant files** (#188) — compact Claude, Cursor, Copilot, Codex, Gemini, and `AGENTS.md` output now include a short verify-before-write block from `SharedAssistantGuidance`. Disable with `config.output.anti_hallucination_rules = false` (default: on).
+- **`rails_get_routes` URL helpers and required params** (#191) — named routes now include the Rails path helper (from the route set's declared name, e.g. `post_path`) and required parameter names (from Journey `required_parts`). Unnamed routes are left without a helper. Summary stays a compact per-controller overview (counts plus one sample helper); standard/full list helpers and required params (paginated).
+- **Partition-child tables in `structure.sql` introspection** (#166) — `StaticStructureSqlParser` now expands PostgreSQL `CREATE TABLE … PARTITION OF …` children as table entries with `partition_of` / `partition_bound`, and marks parents with `partitioned` / `partition_by`. `rails_get_schema` surfaces the parent/child relationship at `detail: standard` and `full`.
+
+### Changed
+
+- **Public docs wording** (#212) — README, GUIDE, and AGENTS/CLAUDE/GEMINI openers say what the gem does in plain language. Comparison table is four durable rows (setup, files in git, read-only, presets) instead of tool-count marketing.
+- **Skunk CI gate ratcheted to 20 and made blocking** (#183) — measured 4.2/4.3 SkunkScore averages were 15.93, 15.97, 15.96, 16.18, 15.89 (mean ≈ 15.99). Threshold 20 leaves ~25% headroom above the worst sample. The skunk job still runs rspec first for coverage. Perf stays advisory (`continue-on-error`). Mutation stays advisory but now also targets `Tools::SearchCode::Validator`, `ViewFileAnalyzer`, and `ExclusionHelper`.
+- **Advisory perf compare** — `rake perf:compare` takes the median of five iterations after one warmup. `introspection_time_sec` rebased to 0.028s after 4.3 schema/routes work (CI was 0.0269s on main, 0.0277s with PathResolver realpath). Context and MCP baselines stay at their 4.2 values because CI still measures well under them.
+- **Documentation and gemspec humanization** (#189) — gemspec is one plain sentence (maps a Rails
+  app so assistants stop guessing); Windsurf dropped from the gemspec; `:full` YARD comment is 27
+  to match `Configuration::PRESETS[:full]`; README comparison uses four durable rows
+  (zero-config, committed files, read-only, presets) plus a dated checked-against line;
+  `docs/gem-general-improvements.md` marked done-in-4.1; `docs/offline-mode.md` labeled
+  5.0 / registry. SECURITY.md outbound policy unchanged (git packs only).
+
+### Fixed
+
+- **`Config::Introspection#preset=` accepts `nil`** — `preset = nil` now sets `@preset` to `nil` and leaves `introspectors` unchanged, so around-hooks can restore an unset preset. Named presets (`:standard`, `:regulated`, `:full`) are unchanged.
+- **Namespaced model exclusions no longer collide on the last path segment** — `excluded_models: ['User']` still matches `User` / `Users` / `users` / `UsersController`, but not `Admin::User`, `Admin::UsersController`, `UserSession`, or `Superuser`. `excluded_models: ['Admin::User']` matches `Admin::User` and `Admin::UsersController` only. Table-only exclusions are unchanged (`patient_records` still drops `PatientRecord`).
+- **MCP `fetch_section` honored disabled introspectors** (#186) — `Introspector#selected_introspectors` now intersects `only:` with `effective_introspectors`, so `:regulated` and `disabled_introspection_categories` cannot be bypassed by `rails_get_schema` / `rails://schema`.
+- **Excluded association names no longer leak via model details** (#186) — associations, generated accessors, and rubydex `similar_models` that name an excluded model or table are omitted from MCP output.
+- **`similar_models` honors `excluded_tables`** (#186) — rubydex sibling names such as `PatientRecord` are dropped when only `patient_records` is excluded (`ExclusionHelper.excluded_class_or_table?`).
+- **Routes and controllers honor model or table exclusions** (#186) — `RouteIntrospector` and `ControllerIntrospector` omit `/users` and `UsersController` when `excluded_models` includes `User` or `excluded_tables` includes `users`. Conventions stay a non-inventory surface (`:does_not_list_models_or_tables`).
+
+### Security
+
+- **HTTP MCP auth defaults documented more clearly** — README and SECURITY.md now lead with: HTTP MCP is unauthenticated unless you set a token or `require_http_auth`; bind to `127.0.0.1` unless you add auth. Default remains `require_http_auth = false`.
+- **`PathResolver` symlink escape** — existing files from `existing_file_for` and `glob_for` are accepted only when `File.realpath` stays inside the realpath of the resolved directory or the application root. File and directory symlinks under a configured path that point outside the root are omitted. Missing paths still return `nil` without calling `realpath`. Allowed roots are realpathed once per resolver instance.
+- **`ViewFileAnalyzer` symlink escape** (#185) — existing view files are resolved with `File.realpath` and compared against the realpath of every configured `app/views` root (including custom Rails paths). A symlink under views that points outside every root now raises `SecurityError` instead of emitting the target file contents.
+
+## [4.2.0] - 2026-08-13
+
+### Added
+
+- **`rails_list_context_providers` MCP tool and dynamic resources** (#147) — new tool reads the registry manifest's `context_providers` section and returns formatted markdown with provider name, type, endpoint, optional flag, and tool specs. Context providers are also registered as dynamic MCP resources (URI template `rails://context-providers/{name}`), bringing the tool count from 16 to 17.
+- **Registry health checker for Doctor** (#145) — new `Doctor::Checkers::RegistryChecker` validates manifest existence, JSON parsing, `RegistryManifest.validate!`, resolver construction, and lockfile presence (when configured). Returns pass/warn/fail with actionable fix hints. Doctor check count: 17.
+- **Request-level resolver memoization** (#159) — `Registry.with_request_resolver` wraps each tool invocation in a thread-local request scope so `build_resolver` is called once per request instead of once per tool. Nil results are never memoized; thread-local storage is always cleaned up (even on error).
+- **Dependabot configuration** (#153) — `.github/dependabot.yml` with grouped updates for bundler, github-actions, and gomod ecosystems, plus automatic PR labeling.
+- **Rails 8.1 in release workflow matrix** (#164) — `.github/workflows/release.yml` now includes Rails 8.1 alongside 7.1, 7.2, and 8.0.
+- **Skunk score threshold CI job** (#157) — advisory CI job runs `skunk lib/` after tests generate coverage data, fails if the SkunkScore average exceeds 30. Threshold to be ratcheted down over time.
+- **Performance regression baseline** (#160) — `spec/support/perf_baseline.json` with three metrics (introspection, context generation, MCP tool response). `rake perf:compare` fails on >20% regression. CI uploads the baseline as a 30-day artifact.
+- **Mutation testing for critical paths** (#163) — `mutant-rspec` via separate `Gemfile-mutation` (eval'd from the main Gemfile) to avoid breaking Ruby 3.2 CI resolution. Advisory CI job targets `Registry::Resolver`, `FrontmatterParser`, `RegistryManifest`, `PackResolver`, `SkillSourceResolver`, and key tools/serializers. Initial coverage: 94.39% on `FrontmatterParser`.
+- **YARD documentation for 9 uncovered files** (#156) — `@param`/`@return` tags added to `search_code.rb`, all 6 introspectors, `json_serializer.rb`, and `usage_formatter.rb`. `yard stats` now 100% for `lib/`.
+- **Dedicated `UsageFormatter` spec** (#151) — comprehensive spec coverage for `Tools::UsageFormatter` formatting logic.
+- **Registry server specs and integration tests** (#149, #150) — `server_spec.rb` extended with registry tool assertions; new `mcp/registry_integration_spec.rb` covers `rails_list_registry`, `rails_resolve_skill`, and `rails_use_skill` end-to-end through the MCP server.
+- **Documentation parity guard spec** — `spec/lib/rails_ai_bridge/doc_parity_spec.rb` fails when README/AGENTS/CLAUDE tool or introspector counts drift from the actual constants.
+
+### Changed
+
+- **Standardized registry manifest and lockfile paths** (#155) — defaults changed from `config/rails_ai_bridge_registry.json` / `config/rails_ai_bridge_registry.lock` to `config/rails_ai_bridge/registry.json` / `config/rails_ai_bridge/registry.lock`. Backward-compat fallback: when the new path doesn't exist but the legacy path does, the getter returns the legacy path. Custom user paths are never overridden.
+- **Documentation humanization and Windsurf purge** (#144, #148) — README, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, and SECURITY.md updated: tool count 16→17, introspector count 26→27, serializer list humanized (alphabetical with Claude/Codex/Gemini), bogus `.Codex/rules/` path fixed to `.codex/`, Windsurf support claims removed (no serializer will be implemented), Mermaid diagrams added to docs.
+
+### Fixed
+
+- **`Instrumentation::InstrumentedTool` server_context parameter translation** — tools without caching received `server_context:` but expected `_server_context:`, causing `ArgumentError` when caching was disabled. `InstrumentedTool` now detects the tool's parameter name and translates accordingly.
+- **`ContextProvider` cache key fork safety** (#162) — replaced `object_id`-based cache key with a stable digest, preventing stale cache hits after `Process.fork`.
+
 ## [4.1.0] - 2026-08-11
 
 ### Added

data/CLAUDE.md

@@ -1,7 +1,7 @@
 # CLAUDE.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).
+Ruby gem that reads a Rails app and gives assistants that map over MCP and
+committed context files. It does not write to the host database.
 
 ## Architecture
 
@@ -9,14 +9,14 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `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:
+  runs **9**, `:full` runs **27** (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/` — 16 built-in MCP tools using the official mcp SDK
+- `lib/rails_ai_bridge/tools/` — 19 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, devin, devin_rules, copilot, copilot_instructions, rules,
-  markdown, JSON)
+  codex, cursor_rules, devin, devin_rules, copilot, copilot_instructions,
+  gemini, 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)
 - `lib/rails_ai_bridge/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
@@ -36,7 +36,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 introspectors; optional extras such as `database_stats`, `non_ar_models`) for power users
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 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/`, `.devin/rules/`, `.github/instructions/`

data/CONTRIBUTING.md

@@ -19,13 +19,13 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 ```
 lib/rails_ai_bridge/
 ├── introspectors/          # Built-in introspectors (schema, models, non_ar_models, routes, …)
-├── tools/                  # 11 built-in MCP tools (detail levels, pagination, extensible)
+├── tools/                  # 19 built-in MCP tools (detail levels, pagination, extensible)
 ├── rubydex_adapter.rb       # Rubydex API wrapper (singleton + query interface + stats)
 ├── rubydex_adapter/         # Extracted collaborators (one concern each)
 │   ├── serializer.rb        # Hash serialization (declaration_to_hash, definition_to_hash, …)
 │   ├── indexer.rb           # Graph building + source file scanning
 │   └── method_counter.rb    # Flat method counting pipeline (no nested conditionals)
-├── serializers/            # Per-assistant formatters (claude, cursor, windsurf, copilot, JSON)
+├── serializers/            # Per-assistant formatters (claude, codex, cursor, devin, copilot, gemini, JSON)
 ├── server.rb               # MCP server setup (stdio + HTTP)
 ├── engine.rb               # Rails Engine for auto-integration
 └── configuration.rb        # User-facing config (presets, context_mode, limits)

data/GEMINI.md

@@ -1,7 +1,7 @@
 # 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).
+Ruby gem that reads a Rails app and gives assistants that map over MCP and
+committed context files. It does not write to the host database.
 
 ## Architecture
 
@@ -9,8 +9,9 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `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/` — 16 built-in MCP tools using the official mcp SDK (hosts can add more via `additional_tools`)
+- `lib/rails_ai_bridge/tools/` — 19 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)
+  runs **9**, `:full` runs **27** (see `Configuration::PRESETS`). Registry:
 - `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
@@ -30,10 +31,11 @@ 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 introspectors; optional extras such as `database_stats`) for power users
+9. **Introspector presets** — `:standard` (9 core) default, `:full` (27 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/`
+12. **Per-tool split rules** — `.codex/`, `.cursor/rules/`, `.devin/rules/`, `.github/instructions/`
 
 ## Testing
 

data/README.md

@@ -2,9 +2,9 @@
 
 ![Rails AI Bridge Logo](https://github.com/user-attachments/assets/ee7b04bd-2d67-483e-be4a-cffdefdbdc50)
 
-> **Turn any Rails app into an AI-ready system — with real context, not guesswork.**
+> Maps your Rails app so assistants stop guessing table names, routes, and conventions.
 
-**One command. Zero config. Structured context + live introspection for AI assistants** via compact project files and an MCP server.
+The install generator writes compact context files and starts a read-only MCP server. Assistants can read the files at session start, then ask for one model, table, or controller when they need detail.
 
 [![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)
@@ -24,7 +24,7 @@ rails-ai-bridge turns a Rails app into an AI-readable project map:
 - **A read-only MCP server** lets assistants ask for exact details only when needed, such as one model, one table, one controller, or one route group.
 - **Assistant-specific output** keeps Claude Code, Cursor, Codex, Copilot, Devin, Gemini, and JSON consumers aligned without making you hand-write context files.
 
-The goal is simple: help AI assistants produce code that fits your Rails app instead of generic Rails code.
+The point is that generated code should match this app, not a generic Rails tutorial.
 
 ## Start here
 
@@ -52,7 +52,7 @@ This is useful when you want an AI assistant to work inside a real Rails codebas
 - A team that wants shared AI guidance committed to the repo
 - Large schemas where dumping everything into context would be noisy
 
-For tiny apps or one-off scripts, manual context may be enough. For team Rails apps, generated context plus MCP gives the assistant a much better starting point.
+Skip this on a tiny app or a one-off script. On a team app with real models and conventions, generated files plus MCP beat a hand-written notes file.
 
 ---
 
@@ -74,23 +74,23 @@ flowchart LR
 
 1. **Introspect**: built-in scanners read your Rails app structure: schema, models, routes, controllers, gems, tests, conventions, and optional full-stack details.
 2. **Generate**: `rails ai:bridge` writes compact, assistant-specific files such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, and Copilot instructions.
-3. **Serve**: `rails ai:serve` exposes read-only `rails_*` MCP tools so an assistant can drill into exact details on demand.
+3. **Serve**: `rails ai:serve` exposes 19 read-only `rails_*` tools so an assistant can drill into exact details on demand.
 
 This creates two complementary layers:
 
 | Layer | What it does | Why it matters |
 |---|---|---|
-| Static files | Give the assistant passive project orientation at session start | Fewer cold starts and fewer generic assumptions |
-| MCP tools | Return exact live details when requested | Less context bloat and fewer schema/route hallucinations |
+| Static files | Overview the assistant sees when the session starts | Less time spent rediscovering models and routes |
+| MCP tools | Exact live details when the assistant asks | Smaller prompts; fewer invented columns and helpers |
 
-Compact files are ordered for usefulness: primary domain models, busy endpoints, recently migrated tables, and optional hot-table signals appear before lower-signal supporting details.
+Compact files are ordered for usefulness: primary domain models, busy endpoints, recently migrated tables, and optional hot-table hints appear before less important details.
 
 ## Safety model
 
 - MCP tools are **read-only**. They inspect Rails structure; they do not write files or mutate the database.
 - `database_stats` is **opt-in** because it queries PostgreSQL table statistics.
 - Generated assistant context avoids credential values and suppresses secret-bearing config paths such as `.env*`, Rails credentials, `master.key`, private key material, and custom `config/secrets` or `config/private` files.
-- HTTP MCP should stay bound to `127.0.0.1` unless you add authentication and network controls. See [docs/mcp-security.md](docs/mcp-security.md).
+- HTTP MCP is unauthenticated unless you set a token or `require_http_auth`. Bind to `127.0.0.1` unless you add auth. See [docs/mcp-security.md](docs/mcp-security.md).
 
 ---
 
@@ -152,23 +152,23 @@ Optional: `gem install rails-ai-bridge` installs the gem into your Ruby environm
 
 ---
 
-## Why rails-ai-bridge over alternatives?
+## Compared with writing the files yourself, or rails-mcp-server
 
-| | **rails-ai-bridge** | **[rails-mcp-server](https://github.com/maquina-app/rails-mcp-server)** | **Manual context** |
+| | **rails-ai-bridge** | **[rails-mcp-server](https://github.com/maquina-app/rails-mcp-server)** | **Hand-written notes** |
 | --- | --- | --- | --- |
-| 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 — 13 read-only `rails_*` tools (extensible) | Yes | No |
-| Auto-introspection | Yes — up to **27** domains (`:full`) | No — server points at projects you configure | DIY |
+| Setup | Railtie and an install generator | Per-project `projects.yml` | You write everything |
+| Files in git | Assistant files committed in the app | Configured projects only | Whatever you remember to commit |
+| Read-only | Inspects structure; does not write or mutate | Yes | Yes |
+| Presets | `:standard`, `:full`, and `:regulated` | No | No |
 
-*Comparison reflects typical documented setups; verify against each project before treating any row as absolute.*
+*Checked against rails-mcp-server README and typical manual-context workflows on 2026-08-15.
+This table lists durable product differences, not tool or introspector counts that change release to release.*
 
 ---
 
-## What Gets Generated
+## What `rails ai:bridge` writes
 
-`rails ai:bridge` generates assistant-specific files tailored to each AI workflow:
+It writes one set of files per assistant. Compact files stay near 150 lines. Split rules live next to the tool that reads them:
 
 ```text
 your-rails-app/
@@ -229,7 +229,7 @@ Each file respects the AI tool's format and size limits. **Commit these files**
 | **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 the configured logical `app/models` path that aren't ActiveRecord, tagged as `[POJO/Service]` (included in `:full`, or opt in with `:non_ar_models`) |
 | **Routing** | Every route with HTTP verbs, paths, controller actions, API namespaces, plus compact endpoint-focus summaries for busy controllers |
-| **Controllers** | Actions, filters, strong params, concerns, API controllers; source metadata honors configured controller paths |
+| **Controllers** | Actions, inherited filters (with `only`/`except` and source class), strong params, concerns, API controllers; source metadata honors configured controller paths |
 | **Views** | Layouts, templates, partials, helpers, template engines, view components |
 | **Frontend** | Stimulus controllers, views, Turbo Frames/Streams, and broadcasts from configured Rails paths |
 | **Background** | ActiveJob classes, mailers, Action Cable channels |
@@ -251,14 +251,15 @@ This keeps context focused and avoids unnecessary token usage while still allowi
 
 ## MCP Tools
 
-The gem exposes **16 built-in tools** via MCP that AI clients call on-demand (hosts can append more via `config.additional_tools`):
+The gem exposes **19 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, semantic tier, non-AR models (when enabled) |
+| `rails_get_schema` | Tables, columns, indexes, foreign keys — tagged `[VERIFIED]` (live ActiveRecord) or `[INFERRED]` (static schema.rb / structure.sql parse) |
+| `rails_get_model_details` | Associations, validations, scopes, enums, callbacks, source macros, semantic tier, non-AR models (when enabled) — tagged `[VERIFIED]` (reflection / rubydex) or `[INFERRED]` (source regex) |
+| `rails_get_context` | In-process composite for one model, controller, or feature: table + model + routes + controller actions + cheap related tests (no HTTP) |
 | `rails_get_routes` | HTTP verbs, paths, controller actions |
-| `rails_get_controllers` | Actions, filters, strong params, concerns |
+| `rails_get_controllers` | Actions, inherited filters (source class at standard/full), 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 |
@@ -266,11 +267,13 @@ The gem exposes **16 built-in tools** via MCP that AI clients call on-demand (ho
 | `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 the configured `app/views` path |
 | `rails_search_semantic` | Semantic code search using rubydex — find declarations by name with types, locations, and relationships |
+| `rails_explain_symbol` | Local CodeGraph explanation for a `symbol` or `query` when `.codegraph/` exists; otherwise setup instructions |
 | `rails_get_stimulus` | Stimulus controllers: targets, values, actions, outlets (requires `:stimulus` introspector) |
-| `rails_list_registry` | Skill pack catalog — list skills, agents, or active packs; requires `config/rails_ai_bridge_registry.json` |
+| `rails_list_registry` | Skill pack catalog — list skills, agents, or active packs; requires `config/rails_ai_bridge/registry.json` |
 | `rails_resolve_skill` | Full content of a named skill or agent from the registry (priority ordering + deprecation redirects); optional `pack=` pin and `type=agent` |
 | `rails_use_skill` | Loads a skill framed as an application directive (apply it step by step to the current task) |
 | `rails_use_agent` | Loads an agent/workflow framed as an activation directive (follow it end to end) |
+| `rails_list_context_providers` | Context providers declared in the registry manifest — external services (e.g. MCP servers) the bridge can query for project context; shows type, endpoint, optional flag, and tool specs |
 
 All tools are **read-only** — they never modify your application or database.
 
@@ -307,7 +310,7 @@ A safety net (`max_tool_response_chars`, default 120K) truncates oversized respo
 
 Early project-level trials suggest the biggest improvement is not always dramatic token reduction by itself. In several runs, `rails-ai-bridge` led to faster, more focused responses even when total token usage only dropped modestly.
 
-This is expected: compact assistant-specific files and the summary-first MCP workflow reduce orientation overhead, help the model navigate the codebase earlier, and improve the quality of the initial context.
+This makes sense: compact assistant-specific files and the summary-first MCP workflow help the model find relevant code faster and start with better context.
 
 Observed benefits so far:
 - Less exploratory reading before the assistant reaches the relevant files
@@ -393,6 +396,11 @@ Codex reads `AGENTS.md` at the repository root. MCP can be configured in `.codex
 
 ### HTTP transport (alternative for all clients)
 
+HTTP MCP is unauthenticated unless you set a token (`http_mcp_token` /
+`RAILS_AI_BRIDGE_MCP_TOKEN`, or a resolver/JWT decoder) or
+`require_http_auth`. Bind to `127.0.0.1` unless you add auth. The default
+remains `require_http_auth = false`.
+
 If stdio MCP fails (usually a Ruby version manager PATH issue), start the HTTP server instead:
 
 ```bash
@@ -410,7 +418,7 @@ RailsAiBridge.configure do |config|
 end
 ```
 
-Point your AI client to `http://localhost:3000/mcp` (or whichever port your Rails server uses) using transport type `SSE`. Keep the endpoint bound to localhost unless you add authentication. See [docs/mcp-security.md](docs/mcp-security.md) for production hardening.
+Point your AI client to `http://127.0.0.1:3000/mcp` (or whichever port your Rails server uses) using transport type `SSE`. See [docs/mcp-security.md](docs/mcp-security.md) and [SECURITY.md](SECURITY.md) for production hardening.
 
 ### Claude Desktop (standalone app)
 
@@ -505,6 +513,12 @@ RailsAiBridge.configure do |config|
 
   # Cache TTL for MCP tool responses (seconds)
   config.cache_ttl = 30
+
+  # Fingerprint / section snapshot TTL (default 5s). Raise for HTTP MCP only.
+  # config.snapshot_ttl = 30
+
+  # Cap PathResolver glob/file listings (default 2000, sorted then taken).
+  # config.max_files_per_path = 2000
 end
 ```
 
@@ -537,13 +551,16 @@ end
 | `additional_resources` | `{}` | Optional MCP resources merged with the built-in `rails://...` resources |
 | `http_path` | `"/mcp"` | HTTP endpoint path |
 | `http_port` | `6029` | HTTP server port |
-| `cache_ttl` | `30` | Cache TTL in seconds |
+| `cache_ttl` | `30` | Cache TTL in seconds for introspection results |
+| `snapshot_ttl` | `5` | Fingerprint / section snapshot TTL (seconds); raise for HTTP MCP |
+| `max_files_per_path` | `2000` | Max paths from `PathResolver#glob_for` / `#files_for` (sorted, then taken) |
 | `watcher_formats` | `:all` | Formats regenerated by `rails ai:watch` (e.g. `%i[claude cursor]` to limit churn) |
 | `managed_region` | `false` | Confine generated output to a marked block so hand-authored content in `CLAUDE.md` & co. survives regeneration |
+| `anti_hallucination_rules` | `true` | Include the shared verify-before-write block in compact assistant files |
 | `parallel_introspection` | `false` | Run introspectors concurrently (requires `concurrent-ruby`, which is already a Rails dependency) |
 | `parallel_pool_size` | `4` | Max threads in the parallel pool; capped at the number of active introspectors so no idle threads are created |
 | `parallel_timeout_seconds` | `10` | Per-introspector future timeout (seconds); timed-out introspectors return `{ error: "timed out after Ns" }` without blocking the others |
-| `registry.registry_manifest_path` | `"config/rails_ai_bridge_registry.json"` | Path to the registry manifest JSON file for skill pack resolution |
+| `registry.registry_manifest_path` | `"config/rails_ai_bridge/registry.json"` | Path to the registry manifest JSON file for skill pack resolution |
 | `registry.skill_cache_dir` | `"~/.rails-ai-bridge/cache"` | Directory for caching git repositories containing skill packs |
 | `registry.skill_packs` | `nil` | Explicit pack names to load, or `nil` for auto-detection based on framework |
 | `registry.local_registry_paths` | `[]` | Local directory paths (must contain `directory.json`) loaded at priority 0 |
@@ -686,10 +703,10 @@ To customize it in your initializer (`config/initializers/rails_ai_bridge.rb`):
 rails-ai-bridge can load **skill packs** — shared collections of agent instructions — from versioned git repositories and surface them through `rails_list_registry` and rake tasks.
 
 ```ruby
-config.registry.registry_manifest_path = "config/rails_ai_bridge_registry.json"
+config.registry.registry_manifest_path = "config/rails_ai_bridge/registry.json"
 ```
 
-Quick example manifest (`config/rails_ai_bridge_registry.json`):
+Quick example manifest (`config/rails_ai_bridge/registry.json`):
 
 ```json
 {
@@ -835,7 +852,7 @@ Bug reports and pull requests: [github.com/igmarin/rails-ai-bridge/issues](https
 
 ## Acknowledgments & Origins
 
-This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **4.1.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
+This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **4.3.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
 
 RailsMCP evolved from 
 [crisnahine/rails-ai-context](https://github.com/crisnahine/rails-ai-context),

data/Rakefile

@@ -5,4 +5,6 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
+Dir.glob('lib/tasks/*.rake').each { |task| load task }
+
 task default: :spec