rails-ai-context 5.6.0 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b89e4a41169c9ddd8a649833f96c6792b6c75ec24101ac220d9c3f431c6126e2
-  data.tar.gz: b2e4c8d0fa16d62b8fd2b67e0dddcd6f9754eb085a1b0cbae59d7b6e0d6898d0
+  metadata.gz: 313744756e1399207abeb841866440c3de88da5863f92163fd7d344b60c479c5
+  data.tar.gz: 4de97686b1d62c8444a76ed78fc709aade9e0e004adae1a7a655c7d0eae8ce23
 SHA512:
-  metadata.gz: 670a61dd4524c7cae544b3277947191fe4e8ab6f0de54eca4e14eb27c8255e1b1b36c6ad10c99e76e9eac46bc4954676fae9f4680d7108dbc3134422ab9e5d13
-  data.tar.gz: f6ca688b6ae4e2c1c41cde1fdba672596cc25815f72d32cd85f039e64596c8c61f30cd24ff2d0996cd7acacb8217abace18eee32ae5ea1d0569d2376d217fad8
+  metadata.gz: 0df4cd4cd7c0e99f8c1e662baae65a960819ed8bea551e8bb536bf06cf2b1ba6c42fee462668e990c2bf48572d5b65b66b6f38c730f643c2cd6e19b751ab7a9c
+  data.tar.gz: 88df4ee906be73bb71212bf47acc88e09efe0ac82a87abef786a3f9a829c5aed57bdb63d19c58d6f5a4361d8ebf5955b3ce29a09235a84aa01e9c204e7ee9471

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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).
 
+## [5.7.0] — 2026-04-09
+
+### Quickstart — Two commands. Problem gone.
+
+```bash
+gem "rails-ai-context", group: :development
+rails generate rails_ai_context:install
+```
+
+### Fixed — Bug Fixes from Codebase Audit
+
+6 bug fixes discovered via automated codebase audit (bug-finder, code-reviewer, doc-consistency-checker agents).
+
+- **AnalyzeFeature service/mailer method extraction** (HIGH) — `\A` (start-of-string) anchor in `scan` regex replaced with `^` (start-of-line). Services and mailers now correctly list all methods instead of always returning empty arrays.
+
+- **SearchCode exact_match + definition double-escaping** (HIGH) — Word boundaries (`\b`) were applied before `Regexp.escape`, producing unmatchable regex when combining `exact_match: true` with `match_type: "definition"` or `"class"`. Boundaries now applied per-match_type after escaping.
+
+- **MigrationAdvisor empty string column bypass** (MEDIUM) — Empty string `""` column names bypassed the "column required" validation (Ruby truthiness). Now normalized via `.presence` so empty strings become `nil` and are caught.
+
+- **GetConcern class method block tracking** — Regex no longer matches `def self.method` as a `class_methods do` block entry, preventing instance methods after `def self.` from being incorrectly skipped.
+
+- **AstCache eviction comment accuracy** — Comment corrected from "evicts oldest entries" to "arbitrary selection" since `Concurrent::Map` has no ordering guarantee.
+
+- **SECURITY.md supported versions** — Added missing 5.6.x row to supported versions table.
+
+- **CONFIGURATION.md preset count** — Fixed stale `:standard` preset count from 13 to 17.
+
 ## [5.6.0] — 2026-04-09
 
 ### Added — Auto-Registration, TestHelper & Bug Fixes

data/README.md

@@ -10,7 +10,7 @@
 <a href="https://github.com/features/copilot"><img src="https://img.shields.io/badge/GitHub_Copilot-000000?style=for-the-badge&logo=githubcopilot&logoColor=white" alt="GitHub Copilot"></a>
 <a href="https://opencode.ai"><img src="https://img.shields.io/badge/OpenCode-4285F4?style=for-the-badge&logoColor=white" alt="OpenCode"></a>
 <a href="https://codex.openai.com"><img src="https://img.shields.io/badge/Codex_CLI-412991?style=for-the-badge&logo=openai&logoColor=white" alt="Codex CLI"></a>
-<a href="#-cli--works-everywhere"><img src="https://img.shields.io/badge/Any_Terminal-4EAA25?style=for-the-badge&logo=gnubash&logoColor=white" alt="Any Terminal"></a>
+<a href="docs/CLI.md"><img src="https://img.shields.io/badge/Any_Terminal-4EAA25?style=for-the-badge&logo=gnubash&logoColor=white" alt="Any Terminal"></a>
 
 
 
@@ -187,20 +187,18 @@ rails 'ai:tool[analyze_feature]' feature=billing
 <br>
 
 ```bash
-# Step 1: Check what exists
 rails 'ai:tool[schema]' table=users
-# → 20 columns, types, indexes, encrypted hints, defaults
-
-# Step 2: Understand the model
-rails 'ai:tool[model_details]' model=User
-# → associations, validations, scopes, enums, callbacks, Devise modules
-
-# Step 3: See the full feature
-rails 'ai:tool[analyze_feature]' feature=subscription
-# → models + controllers + routes + services + jobs + views + tests in one shot
+```
+```
+## Table: users
+| Column              | Type    | Null | Default |
+|---------------------|---------|------|---------|
+| email               | string  | NO   | [unique] |
+| subscription_status | string  | yes  | "free"   |
+| created_at          | datetime| NO   |          |
 ```
 
-AI writes a correct migration, model change, and controller update on the **first attempt**.
+AI sees `subscription_status` already exists. Checks the model, then generates a correct migration — **first attempt**.
 
 </details>
 
@@ -210,19 +208,18 @@ AI writes a correct migration, model change, and controller update on the **firs
 <br>
 
 ```bash
-# Trace what happens
 rails 'ai:tool[controllers]' controller=CooksController action=create
-# → source code + inherited filters + strong params + render map + side effects
-
-# Check the routes
-rails 'ai:tool[routes]' controller=cooks
-# → code-ready helpers (cook_path(@record)) + required params
+```
+```
+# CooksController#create
 
-# Validate after fixing
-rails 'ai:tool[validate]' files=app/controllers/cooks_controller.rb level=rails
-# → syntax + semantics + Brakeman security scan
+Filters: before_action :authenticate_user!, before_action :set_cook (only: show, edit)
+Strong params: cook_params → name, specialty, bio
+Renders: redirect_to @cook | render :new
 ```
 
+AI sees the inherited `authenticate_user!` filter, the actual strong params, and the render paths. No guessing.
+
 </details>
 
 <details>
@@ -252,7 +249,7 @@ rails 'ai:tool[stimulus]' controller=chart
 
 Every tool is **read-only** and returns data verified against your actual app — not guesses, not training data.
 
-<details>
+<details open>
 <summary><strong>Search & Trace</strong></summary>
 
 | Tool | What it does |
@@ -262,7 +259,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Understand</strong></summary>
 
 | Tool | What it does |
@@ -273,7 +270,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Schema & Models</strong></summary>
 
 | Tool | What it does |
@@ -285,7 +282,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Controllers & Routes</strong></summary>
 
 | Tool | What it does |
@@ -295,7 +292,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Views & Frontend</strong></summary>
 
 | Tool | What it does |
@@ -308,7 +305,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Testing & Quality</strong></summary>
 
 | Tool | What it does |
@@ -321,7 +318,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>App Config & Services</strong></summary>
 
 | Tool | What it does |
@@ -337,7 +334,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Data & Debugging</strong></summary>
 
 | Tool | What it does |
@@ -354,7 +351,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-> **[Full parameter docs →](docs/GUIDE.md)**
+> **[All 38 tools with parameters →](docs/TOOLS.md)** &nbsp;|&nbsp; **[Real-world recipes →](docs/RECIPES.md)**
 
 <br>
 
@@ -398,26 +395,21 @@ Enabled by default. Disable with `config.anti_hallucination_rules = false` if yo
 
 ## How it works
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  Your Rails App                                          │
-│  models + schema + routes + controllers + views + jobs   │
-└────────────────────────┬────────────────────────────────┘
-                         │ introspects (31 introspectors)
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│  rails-ai-context                                        │
-│  Prism AST parsing. Cached. Confidence-tagged results.    │
-│  VFS: rails-ai-context:// URIs introspected fresh.        │
-└────────┬──────────────────┬──────────────┬──────────────┘
-         │                  │              │
-         ▼                  ▼              ▼
-┌──────────────────┐ ┌────────────┐ ┌────────────────────┐
-│  Static Files     │ │  MCP Server │ │  CLI Tools          │
-│  CLAUDE.md        │ │  38 tools   │ │  Same 38 tools      │
-│  .cursor/rules/   │ │  5 templates│ │  No server needed   │
-│  .github/instr... │ │  stdio/HTTP │ │  rails 'ai:tool[X]' │
-└──────────────────┘ └────────────┘ └────────────────────┘
+```mermaid
+graph TD
+    A["Your Rails App\nmodels + schema + routes + controllers + views + jobs"] -->|"31 introspectors"| B
+
+    B["rails-ai-context\nPrism AST parsing · Cached · Confidence-tagged\nVFS: rails-ai-context:// URIs introspected fresh"]
+
+    B --> C["MCP Server\nstdio / HTTP\n38 tools · 5 templates"]
+    B --> D["CLI Tools\nRake / Thor\nSame 38 tools"]
+    B --> E["Static Files\nCLAUDE.md · .cursor/rules/\n.github/instructions/"]
+
+    style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
+    style B fill:#2d2d2d,stroke:#555,color:#fff
+    style C fill:#0984e3,stroke:#0770c2,color:#fff
+    style D fill:#00cec9,stroke:#00b5b0,color:#fff
+    style E fill:#a29bfe,stroke:#8c83f0,color:#fff
 ```
 
 <br>
@@ -456,6 +448,58 @@ Both paths ask which AI tools you use (Claude Code, Cursor, GitHub Copilot, Open
 
 <br>
 
+## Documentation
+
+| | |
+|:------|:------------|
+| **[Quickstart](docs/QUICKSTART.md)** | 5-minute getting started |
+| **[Tools Reference](docs/TOOLS.md)** | All 38 tools with every parameter |
+| **[Recipes](docs/RECIPES.md)** | Real-world workflows and examples |
+| **[Custom Tools](docs/CUSTOM_TOOLS.md)** | Build and test your own MCP tools |
+| **[Configuration](docs/CONFIGURATION.md)** | 40+ config options with defaults |
+| **[AI Tool Setup](docs/SETUP.md)** | Claude, Cursor, Copilot, OpenCode, Codex |
+| **[Architecture](docs/ARCHITECTURE.md)** | System design and internals |
+| **[Introspectors](docs/INTROSPECTORS.md)** | All 31 introspectors and AST engine |
+| **[Security](docs/SECURITY.md)** | 4-layer SQL safety and file blocking |
+| **[CLI Reference](docs/CLI.md)** | Commands and argument syntax |
+| **[Standalone](docs/STANDALONE.md)** | Use without Gemfile entry |
+| **[Troubleshooting](docs/TROUBLESHOOTING.md)** | Common issues and fixes |
+| **[FAQ](docs/FAQ.md)** | Frequently asked questions |
+
+<br>
+
+## Build your own tools
+
+Register custom MCP tools alongside the 38 built-in ones:
+
+```ruby
+# app/mcp_tools/rails_get_business_metrics.rb
+class RailsGetBusinessMetrics < MCP::Tool
+  tool_name "rails_get_business_metrics"
+  description "Key business metrics for this app"
+
+  def call(period: "week")
+    MCP::Tool::Response.new([{ type: "text", text: "Users this #{period}: #{User.recent.count}" }])
+  end
+end
+
+# config/initializers/rails_ai_context.rb
+config.custom_tools = [RailsGetBusinessMetrics]
+```
+
+Test with the built-in `TestHelper` (works with RSpec and Minitest):
+
+```ruby
+include RailsAiContext::TestHelper
+
+response = execute_tool("business_metrics", period: "month")
+assert_tool_response_includes(response, "Users")
+```
+
+> **[Custom Tools Guide →](docs/CUSTOM_TOOLS.md)**
+
+<br>
+
 ## Configuration
 
 ```ruby
@@ -469,31 +513,13 @@ if defined?(RailsAiContext)
 end
 ```
 
-<details>
-<summary><strong>All configuration options</strong></summary>
-
-<br>
-
-| Option | Default | Description |
-|:-------|:--------|:------------|
-| `preset` | `:full` | `:full` (31 introspectors) or `:standard` (17) |
-| `context_mode` | `:compact` | `:compact` (150 lines) or `:full` |
-| `generate_root_files` | `true` | Set `false` for split rules only |
-| `anti_hallucination_rules` | `true` | Embed 6-rule verification protocol in generated context files |
-| `cache_ttl` | `60` | Cache TTL in seconds |
-| `max_tool_response_chars` | `200_000` | Safety cap for tool responses |
-| `live_reload` | `:auto` | `:auto`, `true`, or `false` |
-| `custom_tools` | `[]` | Additional MCP tool classes |
-| `skip_tools` | `[]` | Built-in tools to exclude |
-| `excluded_models` | `[]` | Models to skip during introspection |
-
-</details>
+> **[All 40+ configuration options →](docs/CONFIGURATION.md)**
 
 <br>
 
 ## Observability
 
-Every MCP tool call and resource read fires an `ActiveSupport::Notifications` event. Subscribe with standard Rails patterns:
+Every MCP tool call fires an `ActiveSupport::Notifications` event:
 
 ```ruby
 ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
@@ -501,8 +527,6 @@ ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
 end
 ```
 
-Events: `rails_ai_context.tools.call`, `rails_ai_context.resources.read`, and more. All 38 tools declare `output_schema` in the MCP protocol, so clients know the response format before calling.
-
 <br>
 
 ## Requirements

data/SECURITY.md

@@ -4,6 +4,8 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 5.7.x   | :white_check_mark: |
+| 5.6.x   | :white_check_mark: |
 | 5.5.x   | :white_check_mark: |
 | 5.4.x   | :white_check_mark: |
 | 5.3.x   | :white_check_mark: |

data/docs/ARCHITECTURE.md

@@ -0,0 +1,244 @@
+<div align="center" markdown="1">
+
+# Architecture
+
+**How rails-ai-context is built, and why.**
+
+[Tools Reference](TOOLS.md) · [Introspectors](INTROSPECTORS.md) · [Security](SECURITY.md) · [Custom Tools](CUSTOM_TOOLS.md)
+
+</div>
+
+---
+
+## System overview
+
+```mermaid
+graph TD
+    subgraph app["Your Rails App"]
+        A["models + schema + routes + controllers + views + jobs + config"]
+    end
+
+    A -->|"31 introspectors"| gem
+
+    subgraph gem["rails-ai-context"]
+        direction TB
+
+        subgraph engine["Introspection Engine"]
+            direction LR
+            I["Introspectors\n31 modules\nPresets\nCached"]
+            AST["AST Engine\nPrism\n7 listeners\nConfidence tags"]
+            H["Hydration Layer\nSchema hints\ninjected into\ntool responses"]
+        end
+
+        engine --> R["Tool Registry\n38 tools auto-discovered via inherited\n+ custom_tools - skip_tools = active tools"]
+    end
+
+    R --> MCP
+    R --> CLI
+    R --> S
+
+    subgraph outputs["Output"]
+        direction LR
+        MCP["MCP Server\nstdio / HTTP\nResources\nVFS URIs"]
+        CLI["CLI Runner\nRake / Thor\nSame 38 tools\nNo server needed"]
+        S["Serializers\n14 modules\nStatic files\nPer-AI-tool"]
+    end
+
+    style app fill:#4a9eff,stroke:#2d7ad4,color:#fff
+    style gem fill:#2d2d2d,stroke:#555,color:#fff
+    style engine fill:#3a3a3a,stroke:#666,color:#fff
+    style outputs fill:#1a1a1a,stroke:#444,color:#fff
+    style I fill:#6c5ce7,stroke:#5a4bd1,color:#fff
+    style AST fill:#e17055,stroke:#c0392b,color:#fff
+    style H fill:#00b894,stroke:#00a381,color:#fff
+    style R fill:#fdcb6e,stroke:#f0b429,color:#333
+    style MCP fill:#0984e3,stroke:#0770c2,color:#fff
+    style CLI fill:#00cec9,stroke:#00b5b0,color:#fff
+    style S fill:#a29bfe,stroke:#8c83f0,color:#fff
+```
+
+### Data flow
+
+```mermaid
+sequenceDiagram
+    participant AI as AI Assistant
+    participant MCP as MCP Server
+    participant TR as Tool Registry
+    participant Cache as Cache Layer
+    participant App as Rails App
+
+    AI->>MCP: rails_get_schema(table: "users")
+    MCP->>TR: resolve tool + execute
+    TR->>Cache: check introspection cache
+    alt cache hit (TTL + fingerprint valid)
+        Cache-->>TR: cached context
+    else cache miss
+        Cache->>App: introspect (31 modules)
+        App-->>Cache: structured data
+        Cache-->>TR: fresh context
+    end
+    TR-->>MCP: MCP::Tool::Response
+    MCP-->>AI: schema with columns, indexes, hints
+```
+
+### Request lifecycle
+
+```mermaid
+flowchart LR
+    A[Tool Call] --> B{Registered?}
+    B -->|Yes| C{Cache Valid?}
+    B -->|No| E[ToolNotFoundError]
+    C -->|Hit| D[Return Cached]
+    C -->|Miss| F[Introspect]
+    F --> G[Cache Result]
+    G --> D
+    D --> H[Hydrate\nSchema Hints]
+    H --> I[Truncate\nmax_chars]
+    I --> J[MCP::Tool::Response]
+```
+
+## Core modules
+
+### Introspectors (`lib/rails_ai_context/introspectors/`)
+
+31 modules that extract structured data from your Rails app. Each introspector:
+
+- Returns a Hash (never raises — wraps errors in `{ error: msg }`)
+- Is registered in `INTROSPECTOR_MAP` with a symbol key
+- Belongs to one or both presets (`:standard`, `:full`)
+- Results are cached with TTL + fingerprint invalidation
+
+The `Introspector` orchestrator runs configured introspectors and merges results.
+
+### AST Engine
+
+**Prism AST parsing** replaced all regex-based Ruby source parsing in v5.2.0.
+
+- **AstCache** — Thread-safe parse cache (`Concurrent::Map`), keyed by path + SHA256 + mtime
+- **SourceIntrospector** — Single-pass Prism Dispatcher walks the AST once, feeds events to all 7 listeners simultaneously
+- **7 Listeners** — Associations, Validations, Scopes, Enums, Callbacks, Macros, Methods
+- **Confidence** — Every result carries `[VERIFIED]` (static literals) or `[INFERRED]` (dynamic expressions)
+
+### Tool Registry (`lib/rails_ai_context/tools/base_tool.rb`)
+
+Auto-registration via Ruby's `inherited` hook:
+
+1. `BaseTool.inherited(subclass)` fires when any file in `tools/` defines a subclass
+2. Subclass is appended to `@descendants` (protected by `@registry_mutex`)
+3. `BaseTool.registered_tools` eager-loads all tool files and returns non-abstract classes
+4. `BaseTool` itself is marked `abstract!` — excluded from the registry
+
+**Deadlock-free design**: `eager_load!` collects constants to load inside the mutex, loads them outside (because `const_get` triggers Zeitwerk autoloading which calls `inherited` which needs the mutex), then sets the flag inside the mutex.
+
+### MCP Server (`lib/rails_ai_context/server.rb`)
+
+Built on the official `mcp` Ruby SDK:
+
+- **Transports**: stdio (default) or HTTP (Streamable HTTP via `MCP::Server::Transports::StreamableHTTPTransport`)
+- **Tools**: all active tools (builtin + custom − skip_tools)
+- **Resources**: 9 static resources + 5 dynamic VFS resource templates
+- **Instrumentation**: bridges to `ActiveSupport::Notifications`
+- **Live Reload**: watches files, invalidates caches, notifies clients
+
+### VFS (`lib/rails_ai_context/vfs.rb`)
+
+Virtual File System for `rails-ai-context://` URIs:
+
+```
+rails-ai-context://models/Post         → model details + schema
+rails-ai-context://controllers/Posts   → actions, filters, params
+rails-ai-context://controllers/Posts/index → action source
+rails-ai-context://views/posts/show.html.erb → template content
+rails-ai-context://routes/posts        → filtered routes
+```
+
+Every resolve call introspects fresh — zero stale data.
+
+### Hydration Layer (`lib/rails_ai_context/hydrators/`)
+
+Cross-tool semantic hydration (v5.3.0):
+
+- **ControllerHydrator** — Parses controller source via Prism AST to detect model references, injects schema hints
+- **ViewHydrator** — Maps `@post` → `Post` by convention, injects schema hints
+- **SchemaHintBuilder** — Resolves model names to `SchemaHint` value objects from cached context
+- **HydrationFormatter** — Renders hints as compact Markdown sections
+
+Result: controller and view tools automatically include relevant schema information without extra tool calls.
+
+### Serializers (`lib/rails_ai_context/serializers/`)
+
+14 modules that format introspection output for different AI tools:
+
+| Serializer | Output |
+|:-----------|:-------|
+| `ClaudeSerializer` | `CLAUDE.md` |
+| `ClaudeRulesSerializer` | `.claude/rules/*.md` |
+| `CursorRulesSerializer` | `.cursor/rules/*.mdc` |
+| `CopilotSerializer` | `.github/copilot-instructions.md` |
+| `CopilotInstructionsSerializer` | `.github/instructions/*.instructions.md` |
+| `OpencodeSerializer` | `AGENTS.md` (root) |
+| `OpencodeRulesSerializer` | `app/*/AGENTS.md` |
+| `JsonSerializer` | `.ai-context.json` |
+| `MarkdownSerializer` | Base formatting |
+| `ContextFileSerializer` | Atomic file writes with section markers |
+| `CompactSerializerHelper` | Compact mode (≤150 lines) |
+| `StackOverviewHelper` | Stack overview sections |
+| `ToolGuideHelper` | MCP/CLI tool reference sections |
+| `TestCommandDetection` | Test framework detection |
+
+### CLI (`exe/rails-ai-context`, `lib/rails_ai_context/cli/`)
+
+Thor-based CLI that works standalone (no Gemfile entry):
+
+- `ToolRunner` — Parses CLI args, resolves tool names, executes tools, formats output
+- Supports `--json` mode for machine-readable output
+- Same 38 tools available as MCP and CLI
+
+### Caching
+
+Three cache layers:
+
+1. **Introspection cache** (`BaseTool.SHARED_CACHE`) — Mutex-protected, TTL + fingerprint invalidation
+2. **AST cache** (`AstCache`) — `Concurrent::Map`, SHA256 fingerprint per file
+3. **Session cache** (`BaseTool.SESSION_CONTEXT`) — Mutex-protected call history, resets on server restart
+
+`LiveReload` watches files and calls `reset_all_caches!` when changes are detected.
+
+### Fingerprinter (`lib/rails_ai_context/fingerprinter.rb`)
+
+SHA256-based change detection:
+
+- Watches: `app/`, `config/`, `db/`, `lib/tasks/`, Gemfile.lock
+- Computes a composite fingerprint from all watched files
+- Used by introspection cache and live reload to detect actual changes
+
+## Key design decisions
+
+1. **Official MCP SDK** — Not a custom protocol. Uses `mcp` gem's `MCP::Tool`, `MCP::Server`, transports.
+2. **Read-only tools** — All 38 tools annotated as non-destructive. Defense-in-depth for query tool.
+3. **Graceful degradation** — Works without database (parses schema.rb as text), without Brakeman, without ripgrep, without listen gem.
+4. **Zeitwerk autoloading** — Files loaded on-demand. No `require_relative` in the gem.
+5. **Diff-aware generation** — Context file regeneration skips unchanged files using fingerprinting.
+6. **Section markers** — Root file content wrapped in `<!-- BEGIN/END rails-ai-context -->` to preserve user-added content.
+
+## Dependencies
+
+| Gem | Purpose | Required? |
+|:----|:--------|:----------|
+| `mcp` | MCP SDK — server, tools, transports | Yes |
+| `prism` | AST parsing (stdlib in Ruby 3.3+) | Yes |
+| `concurrent-ruby` | Thread-safe caches | Yes |
+| `zeitwerk` | Autoloading | Yes |
+| `thor` | CLI framework | Yes |
+| `brakeman` | Security scanning | Optional |
+| `listen` | File watching for live reload | Optional |
+
+---
+
+<div align="center" markdown="1">
+
+**[← AI Tool Setup](SETUP.md)** · **[Introspectors →](INTROSPECTORS.md)**
+
+[Back to Home](index.md)
+
+</div>