rails-ai-bridge 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24c9dd6461240b9d6864b35c171c465635f9fdacc3c76195915f43b995a27f18
-  data.tar.gz: e97756c625478c854f78f661393d26043ba36b07b8941bed7a2a2c09b3a62a4b
+  metadata.gz: d937341388cd5f16ca5c4df0bfb3e540b0aabd88f21fb7edd8a99c4109a504e2
+  data.tar.gz: 92b5ef03eed9e1a2a3c2f3161543e2f3143724e2af146b941a83b159ca9f7324
 SHA512:
-  metadata.gz: f453227c44348be19356eecb728dac22328abcb20a99cf0430f441c68557346d93576527716764cae4f68f404fcab524dd44c4454b27a4f9078955632be8937f
-  data.tar.gz: 10e975098f252c37f37108e04d0e370b03f469829f9e2520334b180e83a8844a8276b9f4ed60ae650e0f9bd47dd7361b42885dcbdf87880e37d56c04152720fa
+  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

@@ -13,6 +13,9 @@
 # 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

data/AGENTS.md

@@ -1,7 +1,7 @@
 # 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
 
@@ -9,7 +9,7 @@ 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 **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/` — 17 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, 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)
@@ -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,49 @@ 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

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
 
@@ -12,7 +12,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
   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/` — 17 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,
   codex, cursor_rules, devin, devin_rules, copilot, copilot_instructions,

data/CONTRIBUTING.md

@@ -19,7 +19,7 @@ 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/                  # 17 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, …)

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,14 +74,14 @@ 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 hints appear before less important details.
 
@@ -90,7 +90,7 @@ Compact files are ordered for usefulness: primary domain models, busy endpoints,
 - 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 — 17 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 **17 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,6 +267,7 @@ The gem exposes **17 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_resolve_skill` | Full content of a named skill or agent from the registry (priority ordering + deprecation redirects); optional `pack=` pin and `type=agent` |
@@ -394,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
@@ -411,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)
 
@@ -506,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
 ```
 
@@ -538,9 +551,12 @@ 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 |
@@ -836,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.2.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/SECURITY.md

@@ -29,6 +29,7 @@ please report it responsibly:
 
 - All MCP tools are **read-only** and never modify your application or database.
 - Code search (`rails_search_code`) uses `Open3.capture2` with array arguments to prevent shell injection.
+- Symbol explanation (`rails_explain_symbol`) uses `Open3.capture3` with array arguments against a local `.codegraph/` index only (timeout enforced; never contacts a network service).
 - 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;
@@ -47,6 +48,11 @@ please report it responsibly:
 
 ## HTTP MCP authentication
 
+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 the endpoint to `127.0.0.1` unless you add auth.
+`require_http_auth` stays **`false`** by default.
+
 For day-to-day hardening (tokens, `require_http_auth`, proxies, stdio threat model),
 see **[docs/mcp-security.md](docs/mcp-security.md)**.
 

data/docs/GUIDE.md

@@ -1,7 +1,6 @@
-# rails-ai-bridge — Complete Guide
+# rails-ai-bridge guide
 
-> Full documentation for [rails-ai-bridge](https://github.com/igmarin/rails-ai-bridge).
-> For a quick overview, see the [README](../README.md).
+Commands, tools, config, and setup. For the short path, use the [README](../README.md).
 
 ---
 
@@ -279,7 +278,7 @@ end
 
 ## MCP Tools — Full Reference
 
-All **11 built-in tools** are **read-only** and **idempotent** — they never modify your application or database. Hosts can append more via `config.additional_tools`.
+All **19 built-in tools** are **read-only** and **idempotent** — they never modify your application or database. Hosts can append more via `config.additional_tools`.
 
 ### rails_get_schema
 
@@ -381,7 +380,7 @@ rails_get_routes(detail: "standard", limit: 20, offset: 100)
 
 ### rails_get_controllers
 
-Returns controller details: actions, filters, strong params, concerns.
+Returns controller details: actions, inherited filters, strong params, concerns.
 
 **Parameters:**
 
@@ -400,7 +399,7 @@ rails_get_controllers(detail: "summary")
   → Controller names with action counts
 
 rails_get_controllers(controller: "UsersController")
-  → Full detail: parent class, actions, filters (with only/except), strong params
+  → Full detail: parent class, actions, inherited filters (with only/except and source class), strong params
 
 rails_get_controllers(detail: "full")
   → All controllers with actions, filters, and strong params
@@ -505,6 +504,19 @@ rails_search_semantic(query: "Service", max_results: 30)
 
 **Notable:** Results include ancestors, descendants, and inline definitions when available, making this a richer alternative to `rails_search_code` for understanding code structure and relationships.
 
+### rails_explain_symbol
+
+Explains a Ruby/Rails symbol from a **local** CodeGraph index (`.codegraph/` under `Rails.root`). Runs `codegraph explore` in-process with a timeout. Never contacts a network service.
+
+**Parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `query` | string | Symbol or natural-language question (e.g. `User`, `User#save`). Preferred when both are sent. |
+| `symbol` | string | Alias for `query`. |
+
+If `.codegraph/` is missing or `codegraph` fails, the tool returns setup instructions (`codegraph init` / `codegraph index`) instead of raising.
+
 ### Rubydex configuration reference
 
 | Option | Type | Default | Description |
@@ -744,6 +756,12 @@ RailsAiBridge.configure do |config|
   # Cache TTL for introspection results (seconds)
   config.cache_ttl = 30
 
+  # Fingerprint / section snapshot TTL (seconds). Default is 5 — raise for HTTP MCP.
+  # config.snapshot_ttl = 30
+
+  # Cap PathResolver glob/file listings (sorted, then taken). Default 2000.
+  # config.max_files_per_path = 2000
+
   # --- Exclusions ---
 
   # Models to skip during introspection
@@ -787,6 +805,13 @@ RailsAiBridge.configure do |config|
 end
 ```
 
+Introspection listings and caches stay bounded by default: `cache_ttl` is **30s**
+for cached introspection results, `snapshot_ttl` is **5s** for the fingerprint /
+section snapshot (do not raise the default globally — set `config.snapshot_ttl = 30`
+on a long-lived HTTP MCP process if consecutive tool calls should skip filesystem
+walks), `max_files_per_path` is **2000** (`PathResolver#glob_for` / `#files_for`
+sort then take), and `parallel_introspection` is **off**.
+
 ### Options reference
 
 | Option | Type | Default | Description |
@@ -797,6 +822,8 @@ end
 | `claude_max_lines` | Integer | `150` | Max lines for CLAUDE.md in compact mode |
 | `max_tool_response_chars` | Integer | `120_000` | Safety cap for MCP tool responses |
 | `cache_ttl` | Integer | `30` | Cache TTL in seconds for introspection results |
+| `snapshot_ttl` | Integer | `5` | Fingerprint / section snapshot TTL in seconds; raise for HTTP MCP, keep 5s for CLI |
+| `max_files_per_path` | Integer | `2000` | Max paths returned by `PathResolver#glob_for` / `#files_for` (sorted, then taken) |
 | `excluded_models` | Array | internal Rails models | Models to skip |
 | `core_models` | Array | `[]` | Model names tagged as `core_entity` in introspection output and `.claude/rules/rails-context.md`. Used by `RailsAiBridge::ModelSemanticClassifier` to mark primary domain models. |
 | `introspectors` | Array | 9 core symbols | Which introspectors to run. Add `:non_ar_models` to include non-ActiveRecord classes under `app/models`. |
@@ -837,7 +864,7 @@ These run by default. Fast and cover core Rails structure.
 | `jobs` | ActiveJob classes with queue names. Mailers with action methods. Action Cable channels. |
 | `gems` | 70+ notable gems categorized: auth, background_jobs, admin, monitoring, search, pagination, forms, file_upload, testing, linting, security, api, frontend, utilities. |
 | `conventions` | Architecture patterns (MVC, service objects, STI, polymorphism, etc.), directory structure with file counts, config files, detected patterns. |
-| `controllers` | Actions, filters (before/after/around with only/except), strong params methods, parent class, API controller detection, concerns. Source-derived metadata honors the configured logical `app/controllers` path. |
+| `controllers` | Actions, inherited filters (before/after/around with only/except and defining class), strong params methods, parent class, API controller detection, concerns. Source-derived metadata honors the configured logical `app/controllers` path. |
 | `tests` | Test framework (rspec/minitest), factories/fixtures with locations and counts, system tests, CI config files, coverage tool, test helpers, VCR cassettes. |
 | `migrations` | Total count, schema version, pending migrations, recent migration history with detected actions (create_table, add_column, etc.), migration statistics. |
 

data/docs/devin-setup.md

@@ -94,6 +94,7 @@ Once connected, Devin has access to these tools:
 | `rails_get_gems` | Gemfile dependencies and their versions |
 | `rails_search_code` | Full-text search across the codebase |
 | `rails_search_semantic` | Semantic code search by concept |
+| `rails_explain_symbol` | Local CodeGraph explanation for a symbol or query |
 | `rails_get_conventions` | Project coding conventions and patterns |
 | `rails_get_controllers` | Controller actions and before-actions |
 | `rails_get_config` | Application configuration values |

data/docs/gem-general-improvements.md

@@ -1,7 +1,16 @@
 # Gem General Improvements — Roadmap
 
+> **Status:** Done in **4.1**. Historical only — not an open backlog.
+>
+> Shipped in [4.1.0](../CHANGELOG.md#410---2026-08-11): manifest validation (#123),
+> pack lockfile (later path defaults in 4.2 #155), rake JSON (#128), full SHA-256 cache
+> keys (#122), transitive `depends_on` (#126), JWT MCP auth docs (#129), structured
+> registry git logging (#131). Treat this file as an archive of that planning, not as
+> work remaining for 4.3.
+
 Collected opportunities for improving the `rails-ai-bridge` gem beyond the issues already
-addressed in the current session. Ordered roughly by impact vs effort.
+addressed in the current session. Ordered roughly by impact vs effort. All items below
+shipped in 4.1 (or were completed as follow-ups called out in the banner).
 
 ---
 
@@ -42,6 +51,7 @@ if packs do not pin a `ref`. There is no equivalent of `Gemfile.lock` for skill
     "ruby-core-skills":  { "sha": "def456...", "resolved_at": "2025-06-01T10:00:00Z" }
   }
   ```
+
 - When the lock file is present, `SkillSourceResolver#resolve` uses the locked SHA as the
   `ref` argument, bypassing any branch-tip divergence.
 - A `rails rails_ai:registry:update` task regenerates the lock (analogous to `bundle update`).
@@ -71,6 +81,7 @@ a different, richer format. The two diverge over time.
     "skills": [{ "name": "...", "pack": "...", "description": "..." }]
   }
   ```
+
 - `RakePresenter` gains a `skills_json` and `packs_json` method alongside the existing
   `skills_table` / `resolve_skill_output`.
 

data/docs/offline-mode.md

@@ -1,5 +1,10 @@
 # Offline Mode — Design Plan
 
+> **Status:** Proposed for **5.0 / registry**. Not current work.
+> Skill-pack cache and vendoring only. 4.3 stays read-only and does not add an HTTP client.
+> The gem still makes no outbound network requests except git clone/pull for configured skill packs
+> (see [SECURITY.md](../SECURITY.md)).
+
 ## Problem
 
 The registry resolver currently requires network access on every fresh start to clone or pull

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

@@ -154,6 +154,10 @@ module RailsAiBridge
             # Never applies to .ai-context.json. Per-run override: `MERGE=1 rails ai:bridge`.
             # config.output.managed_region = true
 
+            # Shared verify-before-write rules in compact CLAUDE.md / AGENTS.md / GEMINI.md /
+            # Copilot / Cursor output. Default is on; set false to omit the block.
+            # config.output.anti_hallucination_rules = false
+
             # Model list size caps for compact output (0 = show no names, only MCP pointer):
             # Reduce these for apps with large model counts to keep files within size limits.
             # config.copilot_compact_model_list_limit = 15   # default