rails-ai-context 2.0.5 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e17feb99495b6f8328eedaa95020ca097aa4ee7df658ed0a51a925cd6961cdee
-  data.tar.gz: 8b5dc406788cc2af104813e0711887bfc6a5ef0e97ddc79464291b0da74ad7df
+  metadata.gz: 6eefc7e3df780d0a0553d8d33945cba9f799ff12e0013f2f4e4d8dffe2243a08
+  data.tar.gz: fed18a63451cf2a649288c5e4f8a5a13386d98eb164cc312b2e559ebc788b739
 SHA512:
-  metadata.gz: a8b7ff36197da72c8b1d3ca1c7199da2333015fda502a37c83d819a95394732449b2d26f20084a14687b59c6fcde10445dda5fbf4705890793ae213bda2cba33
-  data.tar.gz: 22e5d0ae93d2af2c01f383197a10e454667f0d24af0bb463a191922913702d3c976f04fb918e7716833af874ee1913d86182d234e36c65bb568469a8ead8f116
+  metadata.gz: 84fc5cb59112194dbc3a6f31c1473734646f7cd5cb29777f58290a2cc12c1ebf87036186ed7cc4fd60b52365b9486adea6a9995a561ee4f00c3348487deec532
+  data.tar.gz: b74d3406587a18690aa4bffcfbd928efd4b0ead69c176e14163821dee96b3d983958c007cf0c74073b94875e098865ab73cf239b67a59a0565b4911d7d9a7cfe

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).
 
+## [3.0.0] - 2026-03-26
+
+### Removed
+
+- **Windsurf support dropped** — removed `WindsurfSerializer`, `WindsurfRulesSerializer`, `.windsurfrules` generation, and `.windsurf/rules/` split rules. v2.0.5 is the last version with Windsurf support. If you need Windsurf context files, pin `gem "rails-ai-context", "~> 2.0"` in your Gemfile.
+
+### Added
+
+- **CLI tool support** — all 25 MCP tools can now be run from the terminal: `rails 'ai:tool[schema]' table=users detail=full`. Also via Thor CLI: `rails-ai-context tool schema --table users`. `rails ai:tool` lists all tools. `--help` shows per-tool help auto-generated from input_schema. `--json` / `JSON=1` for JSON envelope. Tool name resolution: `schema` → `get_schema` → `rails_get_schema`.
+- **`tool_mode` config** — `:mcp` (default, MCP primary + CLI fallback) or `:cli` (CLI only, no MCP server needed). Selected during install and first `rails ai:context` run.
+- **ToolRunner** — `lib/rails_ai_context/cli/tool_runner.rb` handles CLI tool execution: arg parsing, type coercion from input_schema, required param validation, enum checking, fuzzy tool name suggestions on typos.
+- **ToolGuideHelper** — shared serializer module renders tool reference sections with MCP or CLI syntax based on `tool_mode`, with MANDATORY enforcement + CLI escape hatch. 3-column tool table (MCP | CLI | description).
+- **Copilot `excludeAgent`** — MCP tools instruction file uses `excludeAgent: "code-review"` (code review can't invoke MCP tools, saves 4K char budget).
+- **`.mcp.json` auto-create** — `rails ai:context` automatically creates `.mcp.json` when `tool_mode` is `:mcp` and the file doesn't exist. Existing apps upgrading to v3.0.0 get it without re-running the install generator.
+- **Full config initializer** — generated initializer documents every configuration option organized by section (AI Tools, Introspection, Models & Filtering, MCP Server, File Size Limits, Extensibility, Security, Search).
+- **Cursor MDC compliance spec** — 26 tests validating MDC format: frontmatter fields, rule types, glob syntax, line limits.
+- **Copilot compliance spec** — 25 tests validating instruction format: applyTo, excludeAgent, file naming, content quality.
+
+### Changed
+
+- Serializer count reduced from 6 to 5 (Claude, Cursor, Copilot, OpenCode, JSON).
+- Install generator renumbered (4 AI tool options instead of 5) + MCP opt-in step.
+- Cursor glob-based rules no longer combine `globs` + `description` (pure Type 2 auto-attach per Cursor best practices).
+- MCP tool instructions use MANDATORY enforcement with CLI escape hatch — AI agents use tools when available, fall back to CLI or file reading when not.
+- All CLI examples use zsh-safe quoting: `rails 'ai:tool[X]'` (brackets are glob patterns in zsh).
+- README rewritten with real-world workflow examples, categorized tool table, MCP vs CLI showcase.
+
 ## [2.0.5] - 2026-03-25
 
 ### Changed

data/CLAUDE.md

@@ -10,7 +10,8 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/introspector.rb` — Orchestrates sub-introspectors
 - `lib/rails_ai_context/introspectors/` — 29 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, view_templates, design_tokens, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database)
 - `lib/rails_ai_context/tools/` — 25 MCP tools using the official mcp SDK
-- `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, context_file_serializer, test_command_detection)
+- `lib/rails_ai_context/cli/` — CLI tool runner (`tool_runner.rb`) — executes MCP tools from rake/Thor
+- `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, copilot, copilot_instructions, rules, markdown, JSON, context_file_serializer, test_command_detection, tool_guide_helper, design_system_helper, stack_overview_helper)
 - `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
 - `lib/rails_ai_context/server.rb` — MCP server configuration (stdio + HTTP transports)
 - `lib/rails_ai_context/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
@@ -20,7 +21,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/watcher.rb` — File watcher for auto-regenerating context files
 - `lib/rails_ai_context/engine.rb` — Rails Engine for auto-integration
 - `lib/generators/rails_ai_context/install/` — Install generator (creates .mcp.json, initializer, context files)
-- `exe/rails-ai-context` — Standalone Thor CLI (serve, context, inspect, watch, doctor, version)
+- `exe/rails-ai-context` — Standalone Thor CLI (serve, context, inspect, watch, doctor, tool, version)
 
 ## Key Design Decisions
 
@@ -36,18 +37,21 @@ structure to AI assistants via the Model Context Protocol (MCP).
 10. **Introspector presets** — `:full` (28) default, `:standard` (13 core) for lightweight usage
 11. **MCP auto-discovery** — `.mcp.json` generated by install generator
 12. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
-13. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
+13. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`
 14. **Section markers** — root file content wrapped in `<!-- BEGIN/END rails-ai-context -->` to preserve user content
 15. **generate_root_files toggle** — when false, skip root files (CLAUDE.md, etc.), only generate split rules
 16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 25 built-in tools
 17. **Design system extraction** — view templates analyzed for canonical examples, color palette, typography, responsive patterns, interactive states, dark mode
 18. **skip_tools API** — `config.skip_tools` array lets users exclude specific built-in tools (e.g. `%w[rails_security_scan]`)
 19. **Security scanning** — optional Brakeman integration via `rails_security_scan` tool (graceful degradation if not installed)
+20. **tool_mode config** — `:mcp` (default, MCP primary + CLI fallback) or `:cli` (CLI only, no MCP server needed). Selected during install.
+21. **CLI tool access** — all 25 MCP tools callable from terminal: `rails ai:tool[schema]`, `rails-ai-context tool schema`. Tool name resolution: `schema` → `get_schema` → `rails_get_schema`.
+22. **Shared ToolGuideHelper** — serializers use a shared module for tool reference sections, rendering MCP or CLI syntax based on `tool_mode`
 
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (575 examples)
+bundle exec rspec           # Run specs (653 examples)
 bundle exec rubocop         # Lint
 ```
 

data/CONTRIBUTING.md

@@ -18,13 +18,14 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 
 ```
 lib/rails_ai_context/
+├── cli/               # CLI tool runner (tool_runner.rb) — executes MCP tools from rake/Thor
 ├── introspectors/     # 29 introspectors (schema, models, routes, etc.)
 ├── tools/             # 25 MCP tools with detail levels and pagination
-├── serializers/       # Per-assistant formatters (claude, opencode, cursor, windsurf, copilot, JSON)
+├── serializers/       # Per-assistant formatters + shared ToolGuideHelper
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── live_reload.rb     # MCP live reload (file watcher + cache invalidation)
 ├── engine.rb          # Rails Engine for auto-integration
-└── configuration.rb   # User-facing config (presets, context_mode, limits)
+└── configuration.rb   # User-facing config (presets, context_mode, tool_mode, limits)
 ```
 
 ## Adding a New Introspector
@@ -43,6 +44,10 @@ lib/rails_ai_context/
 4. Register in `Server::TOOLS`
 5. Write specs in `spec/lib/rails_ai_context/tools/your_tool_spec.rb`
 
+## Adding a CLI Tool Interface
+
+The `ToolRunner` (`lib/rails_ai_context/cli/tool_runner.rb`) handles CLI execution of all MCP tools. It is tested in `spec/lib/rails_ai_context/cli/tool_runner_spec.rb`. If you add a new MCP tool, it is automatically available via CLI — no extra registration needed. Tool name resolution (`schema` → `get_schema` → `rails_get_schema`) works for all tools.
+
 ## Code Style
 
 - Follow `rubocop-rails-omakase` style (run `bundle exec rubocop`)

data/README.md

@@ -7,22 +7,52 @@
 [![CI](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Works with:** Claude Code • Cursor • GitHub Copilot • Windsurf • OpenCode
+**Works with:** Claude Code • Cursor • GitHub Copilot • OpenCode • Any terminal
 
-> Built by a Rails developer with 10 years of production experience. Yes, AI helped write this gem — the same way AI helps me ship features at work. I designed the architecture, made every decision, reviewed every line, and wrote 575 tests. The gem exists because I understand Rails deeply enough to know what AI agents get wrong and what context they need to get it right.
+> Built by a Rails developer with 10+ years of production experience. AI assisted — the same way it assists me shipping features at work. I designed the architecture, made every decision, reviewed every line, and wrote 653 tests. This gem exists because I understand Rails deeply enough to know exactly what AI agents get wrong and what context they need to get it right.
 
 ```bash
 gem "rails-ai-context", group: :development
 rails generate rails_ai_context:install
 ```
 
-That's it. Your AI now has 25 live MCP tools that understand your entire Rails app. Zero config.
+That's it. Your AI now has 25 tools that understand your entire Rails app — via MCP server or CLI. Zero config.
+
+> **[Full Guide →](docs/GUIDE.md)** — every command, every parameter, every configuration option.
+
+---
+
+## Two ways to use it
+
+### MCP Server — AI calls tools directly
+
+```
+rails ai:serve
+```
+
+Your AI agent calls tools via the MCP protocol. Auto-discovered via `.mcp.json` — no manual config.
+
+```
+→ rails_search_code(pattern: "can_cook?", match_type: "trace")
+→ rails_get_schema(table: "users")
+→ rails_analyze_feature(feature: "billing")
+```
+
+### CLI — works everywhere, no server needed
+
+```bash
+rails 'ai:tool[search_code]' pattern="can_cook?" match_type=trace
+rails 'ai:tool[schema]' table=users
+rails 'ai:tool[analyze_feature]' feature=billing
+```
+
+Same 25 tools. Same output. AI agents run these as shell commands. **Works in any terminal, any AI tool, any workflow.** No MCP client required.
 
 ---
 
 ## What AI gets wrong without this
 
-Right now, your AI agent:
+Your AI agent right now:
 
 - **Reads all 2,000 lines of schema.rb** to find one column type
 - **Misses encrypted columns** — doesn't know `gemini_api_key` is encrypted
@@ -30,7 +60,6 @@ Right now, your AI agent:
 - **Doesn't see inherited filters** — misses `authenticate_user!` from ApplicationController
 - **Uses underscores in Stimulus HTML** — `data-cook_status` instead of `data-cook-status`
 - **Breaks Turbo Stream wiring** — broadcasts to channels nobody subscribes to
-- **Permits wrong params** — doesn't cross-check against your schema
 - **Guesses your UI patterns** — invents new button styles instead of matching yours
 
 **Every wrong guess = a wasted iteration.** You fix it, re-run, it breaks something else.
@@ -42,7 +71,7 @@ Right now, your AI agent:
 One call. Full picture.
 
 ```
-rails_search_code(pattern: "can_cook?", match_type: "trace")
+rails 'ai:tool[search_code]' pattern="can_cook?" match_type=trace
 ```
 
 ```
@@ -69,7 +98,61 @@ app/models/concerns/plan_limitable.rb:8
   29: assert_not @user.can_cook?
 ```
 
-Definition + source code + every caller grouped by type + what it calls internally. **One tool call replaces 6 file reads.**
+Definition + source code + every caller grouped by type + what it calls internally. **One call replaces 6 file reads.**
+
+---
+
+## Real-world examples
+
+### "Add a subscription field to users"
+
+```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
+```
+
+AI now writes a correct migration, model change, and controller update on the **first attempt**.
+
+### "Fix the broken cook creation flow"
+
+```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
+
+# Validate after fixing
+rails 'ai:tool[validate]' files=app/controllers/cooks_controller.rb level=rails
+# → syntax + semantics + Brakeman security scan
+```
+
+### "Build a new dashboard view"
+
+```bash
+# Get the design system
+rails 'ai:tool[design_system]' detail=standard
+# → your actual button classes, card patterns, color palette — copy-paste ready
+
+# Check existing view patterns
+rails 'ai:tool[view]' controller=dashboard
+# → templates with ivars, Turbo frames, Stimulus controllers, partial locals
+
+# Get Stimulus data-attributes
+rails 'ai:tool[stimulus]' controller=chart
+# → correct HTML with dashes (not underscores) + reverse view lookup
+```
 
 ---
 
@@ -79,55 +162,55 @@ Tested on a real Rails 8 app (5 models, 19 controllers, 95 routes):
 
 | Task | Without gem | With gem | Saved |
 |------|-------------|----------|-------|
-| Trace a method across the codebase | ~9,080 tokens (read 5 files) | ~198 tokens (1 MCP call) | **98%** |
-| Understand a feature (schema + model + controller) | ~5,200 tokens (read 3 files) | ~1,500 tokens (2 MCP calls) | **71%** |
-| Check all table columns | ~2,573 tokens (read schema.rb) | ~908 tokens (1 MCP call) | **65%** |
+| Trace a method across the codebase | ~9,080 tokens (read 5 files) | ~198 tokens (1 tool call) | **98%** |
+| Understand a feature (schema + model + controller) | ~5,200 tokens (read 3 files) | ~1,500 tokens (2 tool calls) | **71%** |
+| Check all table columns | ~2,573 tokens (read schema.rb) | ~908 tokens (1 tool call) | **65%** |
 
-"Without" = AI reads files it would realistically need. "With" = MCP tools return only what's relevant.
-
-> Savings scale with app size. A 50-model app reads more files per task — MCP calls stay the same size.
-
-But tokens are the side effect. The real value:
-
-- **First attempt is correct** — AI understands associations, callbacks, and constraints before writing code
-- **Cross-file validation** — catches wrong columns, missing partials, broken routes in one call
-- **Matches your patterns** — your button classes, your test style, your flash messages
+> Savings scale with app size. A 50-model app reads more files per task — tool calls stay the same size.
 
 ---
 
-## 25 Live MCP Tools
-
-Every tool is **read-only** and returns structured, token-efficient data. Start with `detail:"summary"`, drill into specifics.
-
-| Tool | One-liner |
-|------|-----------|
-| `rails_search_code` | **Trace mode**: definition + class context + source + internal calls + sibling methods + callers with route chain + test coverage. Also: `"definition"`, `"call"`, `"class"` filters, smart pagination |
-| `rails_get_context` | **Composite**: schema + model + controller + routes + views in one call |
-| `rails_analyze_feature` | **Full-stack**: everything about a feature — models, controllers, routes, services, jobs, views, Stimulus, tests |
-| `rails_validate` | **Syntax + semantic + security** in one call. Catches wrong columns, missing partials, broken routes, Brakeman vulnerabilities |
-| `rails_get_controllers` | Action source code + inherited filters + render map + side effects + private methods inline |
-| `rails_get_schema` | Columns with `[indexed]`, `[unique]`, `[encrypted]`, `[default: value]` hints + model name inline |
-| `rails_get_model_details` | Associations, validations, scopes with lambda body, enum backing types, macros, delegations, constants |
-| `rails_get_routes` | Code-ready helpers (`cook_path(@record)`), controller filters inline, required params |
-| `rails_get_view` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals — pipe-separated, scannable |
-| `rails_get_stimulus` | Copy-paste HTML data-attributes (dashes, not underscores) + reverse view lookup |
-| `rails_get_design_system` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals |
-| `rails_get_test_info` | Fixture contents with relationships + test template matching your app's patterns |
-| `rails_get_conventions` | Your app's actual patterns — auth checks, flash messages, create action template, test patterns |
-| `rails_get_turbo_map` | Broadcast → subscription wiring with mismatch warnings |
-| `rails_get_partial_interface` | Partial locals contract — what to pass, what methods are called on each local |
-| `rails_get_concern` | Public methods, signatures, which models include it |
-| `rails_get_callbacks` | Callbacks in Rails execution order with source code |
-| `rails_get_service_pattern` | Interface, dependencies, side effects, error handling, who calls it |
-| `rails_get_job_pattern` | Queue, retries, guard clauses, Turbo broadcasts, schedules |
-| `rails_get_env` | Environment variables, credentials keys (not values), external service dependencies |
-| `rails_get_helper_methods` | App + framework helpers with view usage cross-references |
-| `rails_get_config` | Database adapter, auth framework, assets stack, Action Cable, middleware |
-| `rails_get_gems` | Notable gems with versions, categories, and config file locations |
-| `rails_get_edit_context` | Method-aware code extraction with class/method context header |
-| `rails_security_scan` | Brakeman static analysis — SQL injection, XSS, mass assignment |
-
-> **[Full parameter documentation →](docs/GUIDE.md)**
+## 25 Tools
+
+Every tool is **read-only** and returns structured, token-efficient data.
+
+| Tool | MCP | CLI | What it does |
+|------|-----|-----|-------------|
+| **Search & Trace** | | | |
+| `search_code` | `rails_search_code(pattern:"X", match_type:"trace")` | `rails 'ai:tool[search_code]'` | Trace: definition + source + callers + test coverage. Also: definition, call, class filters |
+| `get_edit_context` | `rails_get_edit_context(file:"X", near:"Y")` | `rails 'ai:tool[edit_context]'` | Method-aware code extraction with class context |
+| **Understand** | | | |
+| `analyze_feature` | `rails_analyze_feature(feature:"X")` | `rails 'ai:tool[analyze_feature]'` | Full-stack: models + controllers + routes + services + jobs + views + tests |
+| `get_context` | `rails_get_context(model:"X")` | `rails 'ai:tool[context]'` | Composite: schema + model + controller + routes + views in one call |
+| **Schema & Models** | | | |
+| `get_schema` | `rails_get_schema(table:"X")` | `rails 'ai:tool[schema]'` | Columns with indexed/unique/encrypted/default hints |
+| `get_model_details` | `rails_get_model_details(model:"X")` | `rails 'ai:tool[model_details]'` | Associations, validations, scopes, enums, macros, delegations |
+| `get_callbacks` | `rails_get_callbacks(model:"X")` | `rails 'ai:tool[callbacks]'` | Callbacks in Rails execution order with source |
+| `get_concern` | `rails_get_concern(name:"X")` | `rails 'ai:tool[concern]'` | Concern methods + source + which models include it |
+| **Controllers & Routes** | | | |
+| `get_controllers` | `rails_get_controllers(controller:"X")` | `rails 'ai:tool[controllers]'` | Actions + inherited filters + render map + strong params |
+| `get_routes` | `rails_get_routes(controller:"X")` | `rails 'ai:tool[routes]'` | Code-ready helpers (`cook_path(@record)`) + required params |
+| **Views & Frontend** | | | |
+| `get_view` | `rails_get_view(controller:"X")` | `rails 'ai:tool[view]'` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals |
+| `get_stimulus` | `rails_get_stimulus(controller:"X")` | `rails 'ai:tool[stimulus]'` | HTML data-attributes (dashes!) + targets + values + actions |
+| `get_design_system` | `rails_get_design_system` | `rails 'ai:tool[design_system]'` | Copy-paste HTML/ERB patterns for your actual components |
+| `get_partial_interface` | `rails_get_partial_interface(partial:"X")` | `rails 'ai:tool[partial_interface]'` | What locals to pass + what methods are called on them |
+| `get_turbo_map` | `rails_get_turbo_map` | `rails 'ai:tool[turbo_map]'` | Broadcast → subscription wiring + mismatch warnings |
+| **Testing** | | | |
+| `get_test_info` | `rails_get_test_info(model:"X")` | `rails 'ai:tool[test_info]'` | Fixtures + relationships + test template matching your patterns |
+| `validate` | `rails_validate(files:[...])` | `rails 'ai:tool[validate]'` | Syntax + semantic + Brakeman security in one call |
+| `security_scan` | `rails_security_scan` | `rails 'ai:tool[security_scan]'` | Brakeman static analysis — SQL injection, XSS, mass assignment |
+| **App Config** | | | |
+| `get_conventions` | `rails_get_conventions` | `rails 'ai:tool[conventions]'` | Auth checks, flash messages, create action template, test patterns |
+| `get_config` | `rails_get_config` | `rails 'ai:tool[config]'` | Database, auth framework, assets, cache, queue, Action Cable |
+| `get_gems` | `rails_get_gems` | `rails 'ai:tool[gems]'` | Notable gems with versions, categories, config file locations |
+| `get_env` | `rails_get_env` | `rails 'ai:tool[env]'` | Environment variables + credentials keys (not values) |
+| `get_helper_methods` | `rails_get_helper_methods` | `rails 'ai:tool[helper_methods]'` | App + framework helpers with view cross-references |
+| **Services & Jobs** | | | |
+| `get_service_pattern` | `rails_get_service_pattern` | `rails 'ai:tool[service_pattern]'` | Interface, dependencies, side effects, callers |
+| `get_job_pattern` | `rails_get_job_pattern` | `rails 'ai:tool[job_pattern]'` | Queue, retries, guard clauses, broadcasts, schedules |
+
+> **[Full parameter docs →](docs/GUIDE.md)**
 
 ---
 
@@ -138,25 +221,22 @@ Every tool is **read-only** and returns structured, token-efficient data. Start
 │  Your Rails App                                          │
 │  models + schema + routes + controllers + views + jobs   │
 └────────────────────────┬────────────────────────────────┘
-                         │ introspects
+                         │ introspects (29 introspectors)
                          ▼
 ┌─────────────────────────────────────────────────────────┐
-│  rails-ai-context (29 introspectors)                     │
+│  rails-ai-context                                        │
 │  Parses everything. Caches results. Zero config.         │
-└────────┬─────────────────────────────┬──────────────────┘
-         │                             │
-         ▼                             ▼
-┌────────────────────┐    ┌───────────────────────────────┐
-│  Static Files       │    │  Live MCP Server (25 tools)    │
-│  CLAUDE.md          │    │  Real-time queries on demand   │
-│  .cursor/rules/     │    │  Schema, models, routes, etc.  │
-│  .github/instr...   │    │  Trace, validate, analyze      │
-│  .windsurfrules     │    │  Auto-discovered via .mcp.json │
-└────────────────────┘    └───────────────────────────────┘
+└────────┬──────────────────┬──────────────┬──────────────┘
+         │                  │              │
+         ▼                  ▼              ▼
+┌──────────────────┐ ┌────────────┐ ┌────────────────────┐
+│  Static Files     │ │  MCP Server │ │  CLI Tools          │
+│  CLAUDE.md        │ │  25 tools   │ │  Same 25 tools      │
+│  .cursor/rules/   │ │  stdio/HTTP │ │  No server needed   │
+│  .github/instr... │ │  .mcp.json  │ │  rails 'ai:tool[X]' │
+└──────────────────┘ └────────────┘ └────────────────────┘
 ```
 
-The install generator asks which AI tools you use and only generates files for those.
-
 ---
 
 ## Install
@@ -165,14 +245,16 @@ The install generator asks which AI tools you use and only generates files for t
 # Add to Gemfile
 gem "rails-ai-context", group: :development
 
-# Install (picks your AI tools, generates context)
+# Install — picks your AI tools, asks MCP or CLI mode, generates context
 rails generate rails_ai_context:install
 
 # Or generate context directly
 rails ai:context
 ```
 
-Both commands ask which AI tools you use (Claude, Cursor, Copilot, Windsurf, OpenCode) and only generate what you need.
+The install generator asks:
+1. Which AI tools you use (Claude, Cursor, Copilot, OpenCode)
+2. Whether you want MCP server support or CLI-only mode
 
 MCP auto-discovery: `.mcp.json` is detected automatically by Claude Code and Cursor. No manual config.
 
@@ -180,21 +262,38 @@ MCP auto-discovery: `.mcp.json` is detected automatically by Claude Code and Cur
 
 ---
 
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `rails ai:context` | Generate context files for your AI tools |
+| `rails 'ai:tool[NAME]'` | Run any of the 25 tools from the CLI |
+| `rails ai:tool` | List all available tools with short names |
+| `rails ai:serve` | Start MCP server (stdio) |
+| `rails ai:doctor` | Diagnostics + AI readiness score |
+| `rails ai:watch` | Auto-regenerate on file changes |
+| `rails ai:inspect` | Print introspection summary |
+
+---
+
 ## Configuration
 
 ```ruby
 # config/initializers/rails_ai_context.rb
 RailsAiContext.configure do |config|
-  # Which AI tools to generate context for (selected during install)
+  # AI tools to generate context for (selected during install)
   # config.ai_tools = %i[claude cursor]
 
+  # Tool mode: :mcp (default, MCP + CLI fallback) or :cli (CLI only)
+  # config.tool_mode = :mcp
+
   # Presets: :full (28 introspectors, default) or :standard (13 core)
   # config.preset = :full
 
   # Exclude models from introspection
   # config.excluded_models += %w[AdminUser]
 
-  # Skip specific MCP tools
+  # Skip specific tools
   # config.skip_tools = %w[rails_security_scan]
 end
 ```
@@ -211,7 +310,8 @@ end
 | `context_mode` | `:compact` | `:compact` (≤150 lines) or `:full` (dump everything) |
 | `claude_max_lines` | `150` | Max lines for CLAUDE.md in compact mode |
 | `generate_root_files` | `true` | Generate root files (CLAUDE.md, etc.) — set `false` for split rules only |
-| `ai_tools` | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot windsurf opencode]` |
+| `ai_tools` | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot opencode]` |
+| `tool_mode` | `:mcp` | `:mcp` (MCP primary + CLI fallback) or `:cli` (CLI only, no MCP server) |
 | **MCP Server** | | |
 | `cache_ttl` | `60` | Cache TTL in seconds |
 | `max_tool_response_chars` | `200_000` | Safety cap for MCP tool responses |
@@ -228,18 +328,6 @@ end
 
 ---
 
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `rails ai:context` | Generate context files for your AI tools |
-| `rails ai:serve` | Start MCP server (stdio) |
-| `rails ai:doctor` | Diagnostics + AI readiness score |
-| `rails ai:watch` | Auto-regenerate on file changes |
-| `rails ai:inspect` | Print introspection summary |
-
----
-
 ## Requirements
 
 - Ruby >= 3.2, Rails >= 7.1
@@ -252,7 +340,7 @@ end
 ```bash
 git clone https://github.com/crisnahine/rails-ai-context.git
 cd rails-ai-context && bundle install
-bundle exec rspec       # 575 examples
+bundle exec rspec       # 653 examples
 bundle exec rubocop     # Lint
 ```
 

data/SECURITY.md

@@ -4,9 +4,9 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 3.0.x   | :white_check_mark: |
 | 2.0.x   | :white_check_mark: |
-| 1.4.x   | :white_check_mark: |
-| < 1.4   | :x:                |
+| < 2.0   | :x:                |
 
 ## Reporting a Vulnerability