rails-ai-context 2.0.3 → 2.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 582aebf4849cdb8617b33dff88f3822009b8960e1334bbd1aa2eb6a3f6a03350
-  data.tar.gz: 03c8eedbf4989f07a75f878fe86380b809dd4ae1e2afd0020836a848da99b5c3
+  metadata.gz: e17feb99495b6f8328eedaa95020ca097aa4ee7df658ed0a51a925cd6961cdee
+  data.tar.gz: 8b5dc406788cc2af104813e0711887bfc6a5ef0e97ddc79464291b0da74ad7df
 SHA512:
-  metadata.gz: 5a2abfe4dc7c9c123dacd427354789810197c478fab741ac88e9aa0d8c95fcccc5cac2b5005f01615cf678f7229362d3e4ea5838d7c76d2210b28a8531edd9da
-  data.tar.gz: 3f04bb928f49325badb6a956a54c1adb9dec73ac2f73b9d7f81831f5da5931ac0ef1f4494a5c71780cdabcfa159c38ff11a4bd6f7fbcbb7ac79272aaf5de4e3b
+  metadata.gz: a8b7ff36197da72c8b1d3ca1c7199da2333015fda502a37c83d819a95394732449b2d26f20084a14687b59c6fcde10445dda5fbf4705890793ae213bda2cba33
+  data.tar.gz: 22e5d0ae93d2af2c01f383197a10e454667f0d24af0bb463a191922913702d3c976f04fb918e7716833af874ee1913d86182d234e36c65bb568469a8ead8f116

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.5] - 2026-03-25
+
+### Changed
+
+- **Task-based MCP tool instructions** — all 6 serializers (Claude, Cursor, Copilot, Windsurf, OpenCode) rewritten from tool-first to task-first: "What are you trying to do?" → exact tool call. 7 task categories: understand a feature, trace a method, add a field, fix a controller, build a view, write tests, find code. Every AI agent now understands which tool to use for any task.
+- **Concern detail:"full" bug fix** — `\b` after `?`/`!` prevented 13 of 15 method bodies from being extracted. All methods now show source code.
+
+## [2.0.4] - 2026-03-25
+
+### Added
+
+- **Orphaned table detection** — `get_schema` standard mode flags tables with no ActiveRecord model: "⚠ Orphaned tables: content_calendars, cook_comments"
+- **Concern method source code** — `get_concern(name:"X", detail:"full")` shows method bodies inline, same pattern as callbacks tool.
+- **analyze_feature: inherited filters** — shows `authenticate_user! (from ApplicationController)` in controller section.
+- **analyze_feature: code-ready route helpers** — `cook_path(@record)`, `cooks_path` inline with routes.
+- **analyze_feature: service test gaps** — checks services for missing test files, not just models/controllers/jobs.
+- **All 6 serializers updated** — Claude, Cursor, Copilot, Windsurf, OpenCode all document trace mode, concern source, orphaned tables, inherited filters.
+
 ## [2.0.3] - 2026-03-25
 
 ### Added

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -297,130 +297,80 @@ module RailsAiContext
         lines = [
           "# Rails MCP Tools — MANDATORY, Use Before Read/Grep",
           "",
-          "CRITICAL: This project has live MCP tools. You MUST use them for gathering context.",
-          "MCP tools return parsed, up-to-date, token-efficient data with line numbers.",
-          "Read files ONLY when you are about to Edit them. Never read reference files directly.",
-          "",
-          "## Mandatory Workflow — Follow This Order",
-          "",
-          "### 1. Gathering context (BEFORE writing any code)",
-          "- Exploring a feature area → `rails_analyze_feature(feature:\"...\")` — NOT Explore agents, NOT Grep",
-          "- Understanding a model → `rails_get_model_details(model:\"...\")` — NOT reading the model file",
-          "- Checking database columns → `rails_get_schema(table:\"...\")` — NOT reading db/schema.rb",
-          "- Checking routes → `rails_get_routes(controller:\"...\")` — NOT reading config/routes.rb",
-          "- Understanding a controller → `rails_get_controllers(controller:\"...\", action:\"...\")` — NOT reading the file",
-          "- Finding code patterns → `rails_search_code(pattern:\"...\")` — NOT using Grep tool",
-          "- UI patterns → `rails_get_design_system` — NOT reading view files for patterns",
-          "- Full cross-layer context → `rails_get_context(model:\"...\")` — replaces multiple Read calls",
-          "",
-          "### 2. Reading files (ONLY files you will edit)",
-          "- Read a file ONLY when you are about to Edit it (Read is required before Edit)",
-          "- For everything else — schema, routes, models, tests, patterns — use MCP tools above",
-          "",
-          "### 3. After editing (EVERY time, no exceptions)",
-          "- `rails_validate(files:[\"path/to/file.rb\", \"path/to/view.erb\"])` — one call checks all",
-          "- Do NOT run `ruby -c`, `erb` checks, or `node -c` separately — use rails_validate instead",
-          "- Do NOT re-read files to verify edits. Trust your Edit and validate syntax only.",
-          "",
-          "## Do NOT Bypass — Anti-Patterns",
-          "| Instead of... | Use this MCP tool |",
-          "|---------------|-------------------|",
-          "| Reading db/schema.rb | `rails_get_schema(table:\"name\")` |",
-          "| Reading config/routes.rb for reference | `rails_get_routes(controller:\"name\")` |",
-          "| Reading model files for associations | `rails_get_model_details(model:\"Name\")` |",
-          "| Grep/Explore agent for code search | `rails_search_code(pattern:\"regex\")` |",
-          "| Reading test files for patterns | `rails_get_test_info(model:\"Name\")` |",
-          "| Reading controller files for context | `rails_get_controllers(controller:\"Name\")` |",
-          "| Reading JS files for Stimulus API | `rails_get_stimulus(controller:\"name\")` |",
-          "| Multiple reads to understand a feature | `rails_analyze_feature(feature:\"keyword\")` |",
-          "| ruby -c / erb / node -c after edits | `rails_validate(files:[...])` |",
-          "",
-          "## Reference-only files — NEVER read these, use MCP",
-          "- db/schema.rb → `rails_get_schema` (column types in rails-schema.md rules for quick checks)",
-          "- config/routes.rb → `rails_get_routes` (Read ONLY when adding routes)",
-          "- Model files → `rails_get_model_details` (Read ONLY when editing business logic)",
-          "- app/javascript/controllers/index.js → Stimulus auto-registers. Never read this.",
-          "- Test files → `rails_get_test_info`",
-          "",
-          "## Tools (25)",
-          "",
-          "**rails_get_schema** — database tables, columns, indexes, foreign keys",
-          "- `rails_get_schema(detail:\"summary\")` — all tables with column counts",
-          "- `rails_get_schema(table:\"users\")` — full detail for one table",
-          "",
-          "**rails_get_model_details** — associations, validations, scopes, enums, callbacks",
-          "- `rails_get_model_details(detail:\"summary\")` — list all model names",
-          "- `rails_get_model_details(model:\"User\")` — full detail for one model",
-          "",
-          "**rails_get_routes** — HTTP verbs, paths, controller actions",
-          "- `rails_get_routes(detail:\"summary\")` — route counts per controller",
-          "- `rails_get_routes(controller:\"users\")` — routes for one controller",
-          "",
-          "**rails_get_controllers** — actions, filters, strong params, action source code",
-          "- `rails_get_controllers(detail:\"summary\")` — names + action counts",
-          "- `rails_get_controllers(controller:\"CooksController\", action:\"index\")` — action source code + filters",
-          "",
-          "**rails_get_view** — view templates, partials, Stimulus references",
-          "- `rails_get_view(controller:\"cooks\")` — list all views for a controller",
-          "- `rails_get_view(path:\"cooks/index.html.erb\")` — full template content",
-          "",
-          "**rails_get_stimulus** — Stimulus controllers with targets, values, actions",
-          "- `rails_get_stimulus(detail:\"summary\")` — all controllers with counts",
-          "- `rails_get_stimulus(controller:\"filter-form\")` — full detail for one controller",
-          "",
-          "**rails_get_test_info** — test framework, fixtures, factories, helpers",
-          "- `rails_get_test_info(detail:\"full\")` — fixture names, factory names, helper setup",
-          "- `rails_get_test_info(model:\"Cook\")` — full test source for a model",
-          "- `rails_get_test_info(model:\"Cook\", detail:\"summary\")` — test names only (saves tokens)",
-          "- `rails_get_test_info(controller:\"Cooks\")` — existing controller tests",
-          "",
-          "**rails_get_edit_context** — surgical edit helper with line numbers",
-          "- `rails_get_edit_context(file:\"app/models/cook.rb\", near:\"scope\")` — returns code around match with line numbers",
-          "",
-          "**rails_validate** — syntax checker for edited files",
-          "- `rails_validate(files:[\"app/models/cook.rb\"])` — checks Ruby, ERB, JS syntax in one call",
-          "",
-          "**rails_analyze_feature** — combined schema + models + controllers + routes for a feature area",
-          "- `rails_analyze_feature(feature:\"authentication\")` — one call gets everything related to a feature",
-          "",
-          "**rails_get_design_system** — color palette, component patterns, canonical page examples",
-          "- `rails_get_design_system(detail:\"standard\")` — colors + components + real HTML examples + design rules",
-          "- `rails_get_design_system(detail:\"full\")` — + typography, responsive, dark mode, layout, spacing",
-          "",
-          "**rails_get_config** — cache store, session, timezone, middleware, initializers",
-          "**rails_get_gems** — notable gems categorized by function",
-          "**rails_get_conventions** — architecture patterns, directory structure",
-          "**rails_search_code** — regex search: `rails_search_code(pattern:\"regex\", file_type:\"rb\")`",
-          "",
-          "**rails_security_scan** — Brakeman security analysis",
-          "- `rails_security_scan` — run security scan, returns warnings by confidence",
-          "",
-          "**rails_get_concern** — concern methods and includers",
-          "- `rails_get_concern(name:\"Searchable\")` — methods, included modules, includers",
-          "",
-          "**rails_get_callbacks** — model callbacks in execution order",
-          "- `rails_get_callbacks(model:\"User\")` — before/after/around callbacks by type",
-          "",
-          "**rails_get_helper_methods** — app + framework helpers",
-          "- `rails_get_helper_methods` — all helper methods across app and framework",
-          "",
-          "**rails_get_service_pattern** — service object patterns and interfaces",
-          "- `rails_get_service_pattern` — service objects with call signatures and dependencies",
-          "",
-          "**rails_get_job_pattern** — background job patterns and schedules",
-          "- `rails_get_job_pattern` — job classes, queues, retry policies, schedules",
-          "",
-          "**rails_get_env** — environment variables and credentials keys",
-          "- `rails_get_env` — ENV vars referenced in code + credentials structure",
-          "",
-          "**rails_get_partial_interface** — partial locals contract",
-          "- `rails_get_partial_interface(path:\"shared/_form\")` — required/optional locals for a partial",
-          "",
-          "**rails_get_turbo_map** — Turbo Streams/Frames wiring",
-          "- `rails_get_turbo_map` — Turbo Frame IDs, Stream channels, broadcast sources",
-          "",
-          "**rails_get_context** — composite cross-layer context",
-          "- `rails_get_context(model:\"User\")` — schema + model + controllers + views in one call"
+          "This project has 25 live MCP tools. You MUST use them instead of reading files.",
+          "Read files ONLY when you are about to Edit them.",
+          "",
+          "## What Are You Trying to Do?",
+          "",
+          "**Understand a feature or area:**",
+          "→ `rails_analyze_feature(feature:\"cook\")` — models + controllers + routes + services + jobs + views + tests in one call",
+          "→ `rails_get_context(model:\"Cook\")` — schema + model + controller + views assembled together",
+          "",
+          "**Understand a method (who calls it, what it calls):**",
+          "→ `rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")` — definition + source + siblings + all callers + test coverage",
+          "",
+          "**Add a field or modify a model:**",
+          "→ `rails_get_schema(table:\"cooks\")` — columns, types, indexes, defaults, encrypted hints",
+          "→ `rails_get_model_details(model:\"Cook\")` — associations, validations, scopes, enums, callbacks, macros",
+          "",
+          "**Fix a controller bug:**",
+          "→ `rails_get_controllers(controller:\"CooksController\", action:\"create\")` — source + inherited filters + render map + side effects + private methods",
+          "",
+          "**Build or modify a view:**",
+          "→ `rails_get_design_system(detail:\"standard\")` — canonical HTML/ERB patterns to copy",
+          "→ `rails_get_view(controller:\"cooks\")` — templates with ivars, Turbo wiring, Stimulus refs",
+          "→ `rails_get_partial_interface(partial:\"shared/status_badge\")` — what locals to pass",
+          "",
+          "**Write tests:**",
+          "→ `rails_get_test_info(detail:\"standard\")` — framework + fixtures + test template to copy",
+          "→ `rails_get_test_info(model:\"Cook\")` — existing tests for a model",
+          "",
+          "**Find code:**",
+          "→ `rails_search_code(pattern:\"has_many\")` — regex search with 2 lines of context",
+          "→ `rails_search_code(pattern:\"create\", match_type:\"definition\")` — only `def` lines",
+          "→ `rails_search_code(pattern:\"can_cook\", match_type:\"call\")` — only call sites",
+          "",
+          "**After editing (EVERY time):**",
+          "→ `rails_validate(files:[\"app/models/cook.rb\", \"app/views/cooks/new.html.erb\"], level:\"rails\")` — syntax + semantics + security",
+          "",
+          "## Rules",
+          "",
+          "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the MCP tools above",
+          "2. NEVER use Grep or Explore agents for code search — use `rails_search_code`",
+          "3. NEVER run `ruby -c`, `erb`, or `node -c` — use `rails_validate`",
+          "4. Read files ONLY when you are about to Edit them",
+          "5. Start with `detail:\"summary\"` to orient, then drill into specifics",
+          "",
+          "## All 25 Tools",
+          "",
+          "| Tool | What it does |",
+          "|------|-------------|",
+          "| `rails_analyze_feature(feature:\"X\")` | Full-stack: models + controllers (inherited filters) + routes (helpers) + services + jobs + views + tests + gaps |",
+          "| `rails_get_context(model:\"X\")` | Composite: schema + model + controller + routes + views in one call |",
+          "| `rails_search_code(pattern:\"X\", match_type:\"trace\")` | Trace: definition + class context + source + siblings + callers + test coverage |",
+          "| `rails_get_controllers(controller:\"X\", action:\"Y\")` | Action source + inherited filters + render map + side effects + private methods |",
+          "| `rails_validate(files:[...], level:\"rails\")` | Syntax + semantic validation + Brakeman security (if installed) |",
+          "| `rails_get_schema(table:\"X\")` | Columns with [indexed]/[unique]/[encrypted]/[default] + orphaned table warnings |",
+          "| `rails_get_model_details(model:\"X\")` | Associations, validations, scopes (with body), enums (with backing type), macros, delegations |",
+          "| `rails_get_routes(controller:\"X\")` | Routes with code-ready helpers (`cook_path(@record)`) and controller filters inline |",
+          "| `rails_get_view(controller:\"X\")` | Templates with ivars, Turbo Frame/Stream IDs, Stimulus refs, partial locals |",
+          "| `rails_get_design_system` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals |",
+          "| `rails_get_stimulus(controller:\"X\")` | Targets, values, actions + copy-paste HTML data-attributes + reverse view lookup |",
+          "| `rails_get_test_info(model:\"X\")` | Existing tests + fixture contents with relationships + test template |",
+          "| `rails_get_concern(name:\"X\", detail:\"full\")` | Concern methods with full source code + which models include it |",
+          "| `rails_get_callbacks(model:\"X\")` | Callbacks in Rails execution order with source |",
+          "| `rails_get_edit_context(file:\"X\", near:\"Y\")` | Code around a match with class/method context + line numbers |",
+          "| `rails_search_code(pattern:\"X\")` | Regex search with smart limiting + `exclude_tests` + `group_by_file` + pagination |",
+          "| `rails_get_service_pattern` | Service objects: interface, dependencies, side effects, callers |",
+          "| `rails_get_job_pattern` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
+          "| `rails_get_env` | Environment variables + credentials keys (not values) + external services |",
+          "| `rails_get_partial_interface(partial:\"X\")` | Partial locals contract: what to pass + usage examples |",
+          "| `rails_get_turbo_map` | Turbo Stream/Frame wiring: broadcasts → subscriptions + mismatch warnings |",
+          "| `rails_get_helper_methods` | App + framework helper methods with view cross-references |",
+          "| `rails_get_config` | Database adapter, auth framework, assets stack, cache, queue, Action Cable |",
+          "| `rails_get_gems` | Notable gems with versions, categories, config file locations |",
+          "| `rails_get_conventions` | App patterns: auth checks, flash messages, create action template, test patterns |",
+          "| `rails_security_scan` | Brakeman static analysis: SQL injection, XSS, mass assignment |"
         ]
 
         lines.join("\n")

data/lib/rails_ai_context/serializers/claude_serializer.rb

@@ -196,42 +196,84 @@ module RailsAiContext
         render_design_system(context, max_lines: 30)
       end
 
-      def render_mcp_guide # rubocop:disable Metrics/MethodLength
+      def render_mcp_guide # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         [
-          "## MCP Tools (25) — ALWAYS Use These First",
+          "## MCP Tools (25) — MANDATORY, Use Before Read/Grep",
           "",
-          "This project has live MCP tools. You MUST use them instead of reading reference files.",
-          "Start with `detail:\"summary\"`, then drill into specifics.",
+          "This project has 25 live MCP tools. You MUST use them instead of reading files.",
+          "Read files ONLY when you are about to Edit them.",
           "",
-          "### Mandatory Workflow",
-          "1. **Before exploring a feature**: `rails_analyze_feature(feature:\"...\")` — NOT Explore agents or Grep",
-          "2. **Before writing migrations**: `rails_get_schema(table:\"...\")` — NOT reading db/schema.rb",
-          "3. **Before modifying a model**: `rails_get_model_details(model:\"...\")` — NOT reading the model file",
-          "4. **Before adding routes**: `rails_get_routes(controller:\"...\")` — Read routes.rb only when you will edit it",
-          "5. **Before creating views**: `rails_get_design_system` — match existing patterns",
-          "6. **After editing ANY file**: `rails_validate(files:[...])` — no exceptions, no ruby -c / erb / node -c",
+          "### What Are You Trying to Do?",
           "",
-          "### Quick Reference",
-          "| Need | Use this MCP tool | Do NOT use |",
-          "|------|-------------------|------------|",
-          "| Column types | `rails_get_schema(table:\"x\")` | Read db/schema.rb |",
-          "| Model associations | `rails_get_model_details(model:\"X\")` | Read app/models/x.rb |",
-          "| Route paths | `rails_get_routes(controller:\"x\")` | Read config/routes.rb |",
-          "| Feature overview | `rails_analyze_feature(feature:\"x\")` | Explore agent / Grep |",
-          "| Find code | `rails_search_code(pattern:\"x\")` | Grep tool |",
-          "| Validate edits | `rails_validate(files:[...])` | ruby -c / erb / node |",
-          "| Controller logic | `rails_get_controllers(controller:\"X\", action:\"y\")` | Read controller file |",
-          "| UI patterns | `rails_get_design_system` | Read view files |",
-          "| Stimulus API | `rails_get_stimulus(controller:\"x\")` | Read JS files |",
-          "| Test patterns | `rails_get_test_info(model:\"X\")` | Read test files |",
-          "| Full context | `rails_get_context(model:\"X\")` | Multiple Read calls |",
+          "**Understand a feature or area:**",
+          "→ `rails_analyze_feature(feature:\"cook\")` — models + controllers + routes + services + jobs + views + tests in one call",
+          "→ `rails_get_context(model:\"Cook\")` — schema + model + controller + views assembled together",
           "",
-          "### More Tools",
-          "- `rails_get_view(controller:\"x\")` | `rails_get_concern(name:\"X\")` | `rails_get_callbacks(model:\"X\")`",
-          "- `rails_get_helper_methods` | `rails_get_service_pattern` | `rails_get_job_pattern`",
-          "- `rails_get_env` | `rails_get_partial_interface(path:\"shared/_form\")` | `rails_get_turbo_map`",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_security_scan`",
-          "- `rails_get_edit_context(file:\"path\", near:\"keyword\")` — surgical edit helper with line numbers",
+          "**Understand a method (who calls it, what it calls):**",
+          "→ `rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")` — definition + source + siblings + all callers + test coverage",
+          "",
+          "**Add a field or modify a model:**",
+          "→ `rails_get_schema(table:\"cooks\")` — columns, types, indexes, defaults, encrypted hints",
+          "→ `rails_get_model_details(model:\"Cook\")` — associations, validations, scopes, enums, callbacks, macros",
+          "",
+          "**Fix a controller bug:**",
+          "→ `rails_get_controllers(controller:\"CooksController\", action:\"create\")` — source + inherited filters + render map + side effects + private methods",
+          "",
+          "**Build or modify a view:**",
+          "→ `rails_get_design_system(detail:\"standard\")` — canonical HTML/ERB patterns to copy",
+          "→ `rails_get_view(controller:\"cooks\")` — templates with ivars, Turbo wiring, Stimulus refs",
+          "→ `rails_get_partial_interface(partial:\"shared/status_badge\")` — what locals to pass",
+          "",
+          "**Write tests:**",
+          "→ `rails_get_test_info(detail:\"standard\")` — framework + fixtures + test template to copy",
+          "→ `rails_get_test_info(model:\"Cook\")` — existing tests for a model",
+          "",
+          "**Find code:**",
+          "→ `rails_search_code(pattern:\"has_many\")` — regex search with 2 lines of context",
+          "→ `rails_search_code(pattern:\"create\", match_type:\"definition\")` — only `def` lines",
+          "→ `rails_search_code(pattern:\"can_cook\", match_type:\"call\")` — only call sites",
+          "",
+          "**After editing (EVERY time):**",
+          "→ `rails_validate(files:[\"app/models/cook.rb\", \"app/views/cooks/new.html.erb\"], level:\"rails\")` — syntax + semantics + security",
+          "",
+          "### Rules",
+          "",
+          "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the MCP tools above",
+          "2. NEVER use Grep or Explore agents for code search — use `rails_search_code`",
+          "3. NEVER run `ruby -c`, `erb`, or `node -c` — use `rails_validate`",
+          "4. Read files ONLY when you are about to Edit them",
+          "5. Start with `detail:\"summary\"` to orient, then drill into specifics",
+          "",
+          "### All 25 Tools",
+          "",
+          "| Tool | What it does |",
+          "|------|-------------|",
+          "| `rails_analyze_feature(feature:\"X\")` | Full-stack: models + controllers (inherited filters) + routes (helpers) + services + jobs + views + tests + gaps |",
+          "| `rails_get_context(model:\"X\")` | Composite: schema + model + controller + routes + views in one call |",
+          "| `rails_search_code(pattern:\"X\", match_type:\"trace\")` | Trace: definition + class context + source + siblings + callers + test coverage |",
+          "| `rails_get_controllers(controller:\"X\", action:\"Y\")` | Action source + inherited filters + render map + side effects + private methods |",
+          "| `rails_validate(files:[...], level:\"rails\")` | Syntax + semantic validation + Brakeman security (if installed) |",
+          "| `rails_get_schema(table:\"X\")` | Columns with [indexed]/[unique]/[encrypted]/[default] + orphaned table warnings |",
+          "| `rails_get_model_details(model:\"X\")` | Associations, validations, scopes (with body), enums (with backing type), macros, delegations |",
+          "| `rails_get_routes(controller:\"X\")` | Routes with code-ready helpers (`cook_path(@record)`) and controller filters inline |",
+          "| `rails_get_view(controller:\"X\")` | Templates with ivars, Turbo Frame/Stream IDs, Stimulus refs, partial locals |",
+          "| `rails_get_design_system` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals |",
+          "| `rails_get_stimulus(controller:\"X\")` | Targets, values, actions + copy-paste HTML data-attributes + reverse view lookup |",
+          "| `rails_get_test_info(model:\"X\")` | Existing tests + fixture contents with relationships + test template |",
+          "| `rails_get_concern(name:\"X\", detail:\"full\")` | Concern methods with full source code + which models include it |",
+          "| `rails_get_callbacks(model:\"X\")` | Callbacks in Rails execution order with source |",
+          "| `rails_get_edit_context(file:\"X\", near:\"Y\")` | Code around a match with class/method context + line numbers |",
+          "| `rails_search_code(pattern:\"X\")` | Regex search with smart limiting + `exclude_tests` + `group_by_file` + pagination |",
+          "| `rails_get_service_pattern` | Service objects: interface, dependencies, side effects, callers |",
+          "| `rails_get_job_pattern` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
+          "| `rails_get_env` | Environment variables + credentials keys (not values) + external services |",
+          "| `rails_get_partial_interface(partial:\"X\")` | Partial locals contract: what to pass + usage examples |",
+          "| `rails_get_turbo_map` | Turbo Stream/Frame wiring: broadcasts → subscriptions + mismatch warnings |",
+          "| `rails_get_helper_methods` | App + framework helper methods with view cross-references |",
+          "| `rails_get_config` | Database adapter, auth framework, assets stack, cache, queue, Action Cable |",
+          "| `rails_get_gems` | Notable gems with versions, categories, config file locations |",
+          "| `rails_get_conventions` | App patterns: auth checks, flash messages, create action template, test patterns |",
+          "| `rails_security_scan` | Brakeman static analysis: SQL injection, XSS, mass assignment |",
           ""
         ]
       end
@@ -266,18 +308,8 @@ module RailsAiContext
           "- Follow existing patterns and conventions",
           "- Match existing code style",
           "- Run tests after changes",
-          "- After editing, ALWAYS use `rails_validate(files:[...])` — do NOT use separate ruby -c / erb / node -c calls",
           "- Do NOT re-read files to verify edits — trust your Edit, validate syntax only",
           "- Stimulus controllers auto-register — no manual import in controllers/index.js needed",
-          "",
-          "## MCP-First Rule — Do NOT Bypass",
-          "- Do NOT read db/schema.rb — use `rails_get_schema`",
-          "- Do NOT read config/routes.rb for reference — use `rails_get_routes`",
-          "- Do NOT read model files for associations/scopes — use `rails_get_model_details`",
-          "- Do NOT use Grep to search code — use `rails_search_code`",
-          "- Do NOT launch Explore agents for context — use `rails_analyze_feature`",
-          "- Do NOT read test files for patterns — use `rails_get_test_info`",
-          "- Read files ONLY when you are about to Edit them",
           ""
         ]
       end

data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb

@@ -213,44 +213,88 @@ module RailsAiContext
         lines.join("\n")
       end
 
-      def render_mcp_tools_instructions # rubocop:disable Metrics/MethodLength
+      def render_mcp_tools_instructions # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         lines = [
           "---",
           "applyTo: \"**/*\"",
           "---",
           "",
-          "# Rails MCP Tools (25) — MANDATORY, Use Before Read",
+          "# Rails MCP Tools — MANDATORY, Use Before Read/Grep",
           "",
-          "CRITICAL: This project has live MCP tools. You MUST use them for gathering context.",
-          "Read files ONLY when you are about to edit them. Never read reference files directly.",
-          "Start with `detail:\"summary\"`, then drill into specifics.",
+          "This project has 25 live MCP tools. You MUST use them instead of reading files.",
+          "Read files ONLY when you are about to Edit them.",
           "",
-          "## Mandatory Workflow",
-          "1. Gathering context → use MCP tools (NOT file reads, NOT grep)",
-          "2. Reading files → ONLY files you will edit",
-          "3. After editing → `rails_validate(files:[...])` every time, no exceptions",
+          "## What Are You Trying to Do?",
           "",
-          "## Do NOT Bypass",
-          "| Instead of... | Use this MCP tool |",
-          "|---------------|-------------------|",
-          "| Reading db/schema.rb | `rails_get_schema(table:\"name\")` |",
-          "| Reading config/routes.rb | `rails_get_routes(controller:\"name\")` |",
-          "| Reading model files for context | `rails_get_model_details(model:\"Name\")` |",
-          "| Grep for code patterns | `rails_search_code(pattern:\"regex\")` |",
-          "| Reading test files | `rails_get_test_info(model:\"Name\")` |",
-          "| Reading controller for context | `rails_get_controllers(controller:\"Name\", action:\"x\")` |",
-          "| Reading JS for Stimulus API | `rails_get_stimulus(controller:\"name\")` |",
-          "| Multiple reads for a feature | `rails_analyze_feature(feature:\"keyword\")` |",
-          "| ruby -c / erb / node -c | `rails_validate(files:[...])` |",
+          "**Understand a feature or area:**",
+          "→ `rails_analyze_feature(feature:\"cook\")` — models + controllers + routes + services + jobs + views + tests in one call",
+          "→ `rails_get_context(model:\"Cook\")` — schema + model + controller + views assembled together",
+          "",
+          "**Understand a method (who calls it, what it calls):**",
+          "→ `rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")` — definition + source + siblings + all callers + test coverage",
+          "",
+          "**Add a field or modify a model:**",
+          "→ `rails_get_schema(table:\"cooks\")` — columns, types, indexes, defaults, encrypted hints",
+          "→ `rails_get_model_details(model:\"Cook\")` — associations, validations, scopes, enums, callbacks, macros",
+          "",
+          "**Fix a controller bug:**",
+          "→ `rails_get_controllers(controller:\"CooksController\", action:\"create\")` — source + inherited filters + render map + side effects + private methods",
+          "",
+          "**Build or modify a view:**",
+          "→ `rails_get_design_system(detail:\"standard\")` — canonical HTML/ERB patterns to copy",
+          "→ `rails_get_view(controller:\"cooks\")` — templates with ivars, Turbo wiring, Stimulus refs",
+          "→ `rails_get_partial_interface(partial:\"shared/status_badge\")` — what locals to pass",
+          "",
+          "**Write tests:**",
+          "→ `rails_get_test_info(detail:\"standard\")` — framework + fixtures + test template to copy",
+          "→ `rails_get_test_info(model:\"Cook\")` — existing tests for a model",
+          "",
+          "**Find code:**",
+          "→ `rails_search_code(pattern:\"has_many\")` — regex search with 2 lines of context",
+          "→ `rails_search_code(pattern:\"create\", match_type:\"definition\")` — only `def` lines",
+          "→ `rails_search_code(pattern:\"can_cook\", match_type:\"call\")` — only call sites",
+          "",
+          "**After editing (EVERY time):**",
+          "→ `rails_validate(files:[\"app/models/cook.rb\", \"app/views/cooks/new.html.erb\"], level:\"rails\")` — syntax + semantics + security",
+          "",
+          "## Rules",
+          "",
+          "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the MCP tools above",
+          "2. NEVER use Grep or Explore agents for code search — use `rails_search_code`",
+          "3. NEVER run `ruby -c`, `erb`, or `node -c` — use `rails_validate`",
+          "4. Read files ONLY when you are about to Edit them",
+          "5. Start with `detail:\"summary\"` to orient, then drill into specifics",
           "",
           "## All 25 Tools",
-          "- `rails_get_schema` | `rails_get_model_details` | `rails_get_routes` | `rails_get_controllers`",
-          "- `rails_get_view` | `rails_get_stimulus` | `rails_get_test_info` | `rails_analyze_feature`",
-          "- `rails_get_design_system` | `rails_get_edit_context` | `rails_validate` | `rails_search_code`",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_security_scan`",
-          "- `rails_get_concern` | `rails_get_callbacks` | `rails_get_helper_methods` | `rails_get_service_pattern`",
-          "- `rails_get_job_pattern` | `rails_get_env` | `rails_get_partial_interface` | `rails_get_turbo_map`",
-          "- `rails_get_context(model:\"X\")` — composite cross-layer context in one call"
+          "",
+          "| Tool | What it does |",
+          "|------|-------------|",
+          "| `rails_analyze_feature(feature:\"X\")` | Full-stack: models + controllers (inherited filters) + routes (helpers) + services + jobs + views + tests + gaps |",
+          "| `rails_get_context(model:\"X\")` | Composite: schema + model + controller + routes + views in one call |",
+          "| `rails_search_code(pattern:\"X\", match_type:\"trace\")` | Trace: definition + class context + source + siblings + callers + test coverage |",
+          "| `rails_get_controllers(controller:\"X\", action:\"Y\")` | Action source + inherited filters + render map + side effects + private methods |",
+          "| `rails_validate(files:[...], level:\"rails\")` | Syntax + semantic validation + Brakeman security (if installed) |",
+          "| `rails_get_schema(table:\"X\")` | Columns with [indexed]/[unique]/[encrypted]/[default] + orphaned table warnings |",
+          "| `rails_get_model_details(model:\"X\")` | Associations, validations, scopes (with body), enums (with backing type), macros, delegations |",
+          "| `rails_get_routes(controller:\"X\")` | Routes with code-ready helpers (`cook_path(@record)`) and controller filters inline |",
+          "| `rails_get_view(controller:\"X\")` | Templates with ivars, Turbo Frame/Stream IDs, Stimulus refs, partial locals |",
+          "| `rails_get_design_system` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals |",
+          "| `rails_get_stimulus(controller:\"X\")` | Targets, values, actions + copy-paste HTML data-attributes + reverse view lookup |",
+          "| `rails_get_test_info(model:\"X\")` | Existing tests + fixture contents with relationships + test template |",
+          "| `rails_get_concern(name:\"X\", detail:\"full\")` | Concern methods with full source code + which models include it |",
+          "| `rails_get_callbacks(model:\"X\")` | Callbacks in Rails execution order with source |",
+          "| `rails_get_edit_context(file:\"X\", near:\"Y\")` | Code around a match with class/method context + line numbers |",
+          "| `rails_search_code(pattern:\"X\")` | Regex search with smart limiting + `exclude_tests` + `group_by_file` + pagination |",
+          "| `rails_get_service_pattern` | Service objects: interface, dependencies, side effects, callers |",
+          "| `rails_get_job_pattern` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
+          "| `rails_get_env` | Environment variables + credentials keys (not values) + external services |",
+          "| `rails_get_partial_interface(partial:\"X\")` | Partial locals contract: what to pass + usage examples |",
+          "| `rails_get_turbo_map` | Turbo Stream/Frame wiring: broadcasts → subscriptions + mismatch warnings |",
+          "| `rails_get_helper_methods` | App + framework helper methods with view cross-references |",
+          "| `rails_get_config` | Database adapter, auth framework, assets stack, cache, queue, Action Cable |",
+          "| `rails_get_gems` | Notable gems with versions, categories, config file locations |",
+          "| `rails_get_conventions` | App patterns: auth checks, flash messages, create action template, test patterns |",
+          "| `rails_security_scan` | Brakeman static analysis: SQL injection, XSS, mass assignment |"
         ]
 
         lines.join("\n")

data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb

@@ -253,44 +253,89 @@ module RailsAiContext
       end
 
       # Always-on MCP tool reference — strongest enforcement point for Cursor
-      def render_mcp_tools_rule # rubocop:disable Metrics/MethodLength
+      def render_mcp_tools_rule # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         lines = [
           "---",
           "description: \"Rails MCP tools (25) — MANDATORY, use before reading any reference files\"",
           "alwaysApply: true",
           "---",
           "",
-          "# Rails MCP Tools (25) — MANDATORY, Use Before Read",
+          "# Rails MCP Tools — MANDATORY, Use Before Read/Grep",
           "",
-          "CRITICAL: This project has live MCP tools. You MUST use them for gathering context.",
-          "Read files ONLY when you are about to edit them. Never read reference files directly.",
+          "This project has 25 live MCP tools. You MUST use them instead of reading files.",
+          "Read files ONLY when you are about to Edit them.",
           "",
-          "## Mandatory Workflow",
-          "1. Gathering context → use MCP tools (NOT file reads, NOT grep)",
-          "2. Reading files → ONLY files you will edit (Read is required before Edit)",
-          "3. After editing → `rails_validate(files:[...])` every time, no exceptions",
+          "## What Are You Trying to Do?",
           "",
-          "## Do NOT Bypass — Anti-Patterns",
-          "| Instead of... | Use this MCP tool |",
-          "|---------------|-------------------|",
-          "| Reading db/schema.rb | `rails_get_schema(table:\"name\")` |",
-          "| Reading config/routes.rb | `rails_get_routes(controller:\"name\")` |",
-          "| Reading model files for context | `rails_get_model_details(model:\"Name\")` |",
-          "| Grep for code patterns | `rails_search_code(pattern:\"regex\")` |",
-          "| Reading test files for patterns | `rails_get_test_info(model:\"Name\")` |",
-          "| Reading controller for context | `rails_get_controllers(controller:\"Name\", action:\"x\")` |",
-          "| Reading JS for Stimulus API | `rails_get_stimulus(controller:\"name\")` |",
-          "| Multiple reads for a feature | `rails_analyze_feature(feature:\"keyword\")` |",
-          "| ruby -c / erb / node -c | `rails_validate(files:[...])` |",
+          "**Understand a feature or area:**",
+          "→ `rails_analyze_feature(feature:\"cook\")` — models + controllers + routes + services + jobs + views + tests in one call",
+          "→ `rails_get_context(model:\"Cook\")` — schema + model + controller + views assembled together",
+          "",
+          "**Understand a method (who calls it, what it calls):**",
+          "→ `rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")` — definition + source + siblings + all callers + test coverage",
+          "",
+          "**Add a field or modify a model:**",
+          "→ `rails_get_schema(table:\"cooks\")` — columns, types, indexes, defaults, encrypted hints",
+          "→ `rails_get_model_details(model:\"Cook\")` — associations, validations, scopes, enums, callbacks, macros",
+          "",
+          "**Fix a controller bug:**",
+          "→ `rails_get_controllers(controller:\"CooksController\", action:\"create\")` — source + inherited filters + render map + side effects + private methods",
+          "",
+          "**Build or modify a view:**",
+          "→ `rails_get_design_system(detail:\"standard\")` — canonical HTML/ERB patterns to copy",
+          "→ `rails_get_view(controller:\"cooks\")` — templates with ivars, Turbo wiring, Stimulus refs",
+          "→ `rails_get_partial_interface(partial:\"shared/status_badge\")` — what locals to pass",
+          "",
+          "**Write tests:**",
+          "→ `rails_get_test_info(detail:\"standard\")` — framework + fixtures + test template to copy",
+          "→ `rails_get_test_info(model:\"Cook\")` — existing tests for a model",
+          "",
+          "**Find code:**",
+          "→ `rails_search_code(pattern:\"has_many\")` — regex search with 2 lines of context",
+          "→ `rails_search_code(pattern:\"create\", match_type:\"definition\")` — only `def` lines",
+          "→ `rails_search_code(pattern:\"can_cook\", match_type:\"call\")` — only call sites",
+          "",
+          "**After editing (EVERY time):**",
+          "→ `rails_validate(files:[\"app/models/cook.rb\", \"app/views/cooks/new.html.erb\"], level:\"rails\")` — syntax + semantics + security",
+          "",
+          "## Rules",
+          "",
+          "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the MCP tools above",
+          "2. NEVER use Grep or Explore agents for code search — use `rails_search_code`",
+          "3. NEVER run `ruby -c`, `erb`, or `node -c` — use `rails_validate`",
+          "4. Read files ONLY when you are about to Edit them",
+          "5. Start with `detail:\"summary\"` to orient, then drill into specifics",
           "",
           "## All 25 Tools",
-          "- `rails_get_schema` | `rails_get_model_details` | `rails_get_routes` | `rails_get_controllers`",
-          "- `rails_get_view` | `rails_get_stimulus` | `rails_get_test_info` | `rails_analyze_feature`",
-          "- `rails_get_design_system` | `rails_get_edit_context` | `rails_validate` | `rails_search_code`",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_security_scan`",
-          "- `rails_get_concern` | `rails_get_callbacks` | `rails_get_helper_methods` | `rails_get_service_pattern`",
-          "- `rails_get_job_pattern` | `rails_get_env` | `rails_get_partial_interface` | `rails_get_turbo_map`",
-          "- `rails_get_context(model:\"X\")` — composite cross-layer context in one call"
+          "",
+          "| Tool | What it does |",
+          "|------|-------------|",
+          "| `rails_analyze_feature(feature:\"X\")` | Full-stack: models + controllers (inherited filters) + routes (helpers) + services + jobs + views + tests + gaps |",
+          "| `rails_get_context(model:\"X\")` | Composite: schema + model + controller + routes + views in one call |",
+          "| `rails_search_code(pattern:\"X\", match_type:\"trace\")` | Trace: definition + class context + source + siblings + callers + test coverage |",
+          "| `rails_get_controllers(controller:\"X\", action:\"Y\")` | Action source + inherited filters + render map + side effects + private methods |",
+          "| `rails_validate(files:[...], level:\"rails\")` | Syntax + semantic validation + Brakeman security (if installed) |",
+          "| `rails_get_schema(table:\"X\")` | Columns with [indexed]/[unique]/[encrypted]/[default] + orphaned table warnings |",
+          "| `rails_get_model_details(model:\"X\")` | Associations, validations, scopes (with body), enums (with backing type), macros, delegations |",
+          "| `rails_get_routes(controller:\"X\")` | Routes with code-ready helpers (`cook_path(@record)`) and controller filters inline |",
+          "| `rails_get_view(controller:\"X\")` | Templates with ivars, Turbo Frame/Stream IDs, Stimulus refs, partial locals |",
+          "| `rails_get_design_system` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals |",
+          "| `rails_get_stimulus(controller:\"X\")` | Targets, values, actions + copy-paste HTML data-attributes + reverse view lookup |",
+          "| `rails_get_test_info(model:\"X\")` | Existing tests + fixture contents with relationships + test template |",
+          "| `rails_get_concern(name:\"X\", detail:\"full\")` | Concern methods with full source code + which models include it |",
+          "| `rails_get_callbacks(model:\"X\")` | Callbacks in Rails execution order with source |",
+          "| `rails_get_edit_context(file:\"X\", near:\"Y\")` | Code around a match with class/method context + line numbers |",
+          "| `rails_search_code(pattern:\"X\")` | Regex search with smart limiting + `exclude_tests` + `group_by_file` + pagination |",
+          "| `rails_get_service_pattern` | Service objects: interface, dependencies, side effects, callers |",
+          "| `rails_get_job_pattern` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
+          "| `rails_get_env` | Environment variables + credentials keys (not values) + external services |",
+          "| `rails_get_partial_interface(partial:\"X\")` | Partial locals contract: what to pass + usage examples |",
+          "| `rails_get_turbo_map` | Turbo Stream/Frame wiring: broadcasts → subscriptions + mismatch warnings |",
+          "| `rails_get_helper_methods` | App + framework helper methods with view cross-references |",
+          "| `rails_get_config` | Database adapter, auth framework, assets stack, cache, queue, Action Cable |",
+          "| `rails_get_gems` | Notable gems with versions, categories, config file locations |",
+          "| `rails_get_conventions` | App patterns: auth checks, flash messages, create action template, test patterns |",
+          "| `rails_security_scan` | Brakeman static analysis: SQL injection, XSS, mass assignment |"
         ]
 
         lines.join("\n")

data/lib/rails_ai_context/serializers/opencode_serializer.rb

@@ -163,41 +163,84 @@ module RailsAiContext
         render_design_system(context, max_lines: 30)
       end
 
-      def render_mcp_guide # rubocop:disable Metrics/MethodLength
+      def render_mcp_guide # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         [
-          "## MCP Tools (25) — MANDATORY, Use Before Read",
+          "## MCP Tools (25) — MANDATORY, Use Before Read/Grep",
           "",
-          "CRITICAL: This project has live MCP tools. You MUST use them for gathering context.",
-          "Read files ONLY when you are about to edit them. Never read reference files directly.",
-          "Start with `detail:\"summary\"`, then drill into specifics.",
+          "This project has 25 live MCP tools. You MUST use them instead of reading files.",
+          "Read files ONLY when you are about to Edit them.",
           "",
-          "### Mandatory Workflow",
-          "1. **Before exploring a feature**: `rails_analyze_feature(feature:\"...\")` — NOT file reads or grep",
-          "2. **Before writing migrations**: `rails_get_schema(table:\"...\")` — NOT reading db/schema.rb",
-          "3. **Before modifying a model**: `rails_get_model_details(model:\"...\")` — NOT reading the model file",
-          "4. **Before adding routes**: `rails_get_routes(controller:\"...\")` — Read only when you will edit",
-          "5. **Before creating views**: `rails_get_design_system` — match existing patterns",
-          "6. **After editing ANY file**: `rails_validate(files:[...])` — no exceptions",
+          "### What Are You Trying to Do?",
           "",
-          "### Do NOT Bypass",
-          "| Instead of... | Use this MCP tool |",
-          "|---------------|-------------------|",
-          "| Reading db/schema.rb | `rails_get_schema(table:\"x\")` |",
-          "| Reading model files | `rails_get_model_details(model:\"X\")` |",
-          "| Reading routes.rb | `rails_get_routes(controller:\"x\")` |",
-          "| Grep for code | `rails_search_code(pattern:\"x\")` |",
-          "| Reading test files | `rails_get_test_info(model:\"X\")` |",
-          "| Reading controller | `rails_get_controllers(controller:\"X\", action:\"y\")` |",
-          "| ruby -c / erb / node | `rails_validate(files:[...])` |",
+          "**Understand a feature or area:**",
+          "→ `rails_analyze_feature(feature:\"cook\")` — models + controllers + routes + services + jobs + views + tests in one call",
+          "→ `rails_get_context(model:\"Cook\")` — schema + model + controller + views assembled together",
+          "",
+          "**Understand a method (who calls it, what it calls):**",
+          "→ `rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")` — definition + source + siblings + all callers + test coverage",
+          "",
+          "**Add a field or modify a model:**",
+          "→ `rails_get_schema(table:\"cooks\")` — columns, types, indexes, defaults, encrypted hints",
+          "→ `rails_get_model_details(model:\"Cook\")` — associations, validations, scopes, enums, callbacks, macros",
+          "",
+          "**Fix a controller bug:**",
+          "→ `rails_get_controllers(controller:\"CooksController\", action:\"create\")` — source + inherited filters + render map + side effects + private methods",
+          "",
+          "**Build or modify a view:**",
+          "→ `rails_get_design_system(detail:\"standard\")` — canonical HTML/ERB patterns to copy",
+          "→ `rails_get_view(controller:\"cooks\")` — templates with ivars, Turbo wiring, Stimulus refs",
+          "→ `rails_get_partial_interface(partial:\"shared/status_badge\")` — what locals to pass",
+          "",
+          "**Write tests:**",
+          "→ `rails_get_test_info(detail:\"standard\")` — framework + fixtures + test template to copy",
+          "→ `rails_get_test_info(model:\"Cook\")` — existing tests for a model",
+          "",
+          "**Find code:**",
+          "→ `rails_search_code(pattern:\"has_many\")` — regex search with 2 lines of context",
+          "→ `rails_search_code(pattern:\"create\", match_type:\"definition\")` — only `def` lines",
+          "→ `rails_search_code(pattern:\"can_cook\", match_type:\"call\")` — only call sites",
+          "",
+          "**After editing (EVERY time):**",
+          "→ `rails_validate(files:[\"app/models/cook.rb\", \"app/views/cooks/new.html.erb\"], level:\"rails\")` — syntax + semantics + security",
+          "",
+          "### Rules",
+          "",
+          "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the MCP tools above",
+          "2. NEVER use Grep or Explore agents for code search — use `rails_search_code`",
+          "3. NEVER run `ruby -c`, `erb`, or `node -c` — use `rails_validate`",
+          "4. Read files ONLY when you are about to Edit them",
+          "5. Start with `detail:\"summary\"` to orient, then drill into specifics",
           "",
           "### All 25 Tools",
-          "- `rails_get_schema` | `rails_get_model_details` | `rails_get_routes` | `rails_get_controllers`",
-          "- `rails_get_view` | `rails_get_stimulus` | `rails_get_test_info` | `rails_analyze_feature`",
-          "- `rails_get_design_system` | `rails_get_edit_context` | `rails_validate` | `rails_search_code`",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_security_scan`",
-          "- `rails_get_concern` | `rails_get_callbacks` | `rails_get_helper_methods` | `rails_get_service_pattern`",
-          "- `rails_get_job_pattern` | `rails_get_env` | `rails_get_partial_interface` | `rails_get_turbo_map`",
-          "- `rails_get_context(model:\"X\")` — composite cross-layer context in one call",
+          "",
+          "| Tool | What it does |",
+          "|------|-------------|",
+          "| `rails_analyze_feature(feature:\"X\")` | Full-stack: models + controllers (inherited filters) + routes (helpers) + services + jobs + views + tests + gaps |",
+          "| `rails_get_context(model:\"X\")` | Composite: schema + model + controller + routes + views in one call |",
+          "| `rails_search_code(pattern:\"X\", match_type:\"trace\")` | Trace: definition + class context + source + siblings + callers + test coverage |",
+          "| `rails_get_controllers(controller:\"X\", action:\"Y\")` | Action source + inherited filters + render map + side effects + private methods |",
+          "| `rails_validate(files:[...], level:\"rails\")` | Syntax + semantic validation + Brakeman security (if installed) |",
+          "| `rails_get_schema(table:\"X\")` | Columns with [indexed]/[unique]/[encrypted]/[default] + orphaned table warnings |",
+          "| `rails_get_model_details(model:\"X\")` | Associations, validations, scopes (with body), enums (with backing type), macros, delegations |",
+          "| `rails_get_routes(controller:\"X\")` | Routes with code-ready helpers (`cook_path(@record)`) and controller filters inline |",
+          "| `rails_get_view(controller:\"X\")` | Templates with ivars, Turbo Frame/Stream IDs, Stimulus refs, partial locals |",
+          "| `rails_get_design_system` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals |",
+          "| `rails_get_stimulus(controller:\"X\")` | Targets, values, actions + copy-paste HTML data-attributes + reverse view lookup |",
+          "| `rails_get_test_info(model:\"X\")` | Existing tests + fixture contents with relationships + test template |",
+          "| `rails_get_concern(name:\"X\", detail:\"full\")` | Concern methods with full source code + which models include it |",
+          "| `rails_get_callbacks(model:\"X\")` | Callbacks in Rails execution order with source |",
+          "| `rails_get_edit_context(file:\"X\", near:\"Y\")` | Code around a match with class/method context + line numbers |",
+          "| `rails_search_code(pattern:\"X\")` | Regex search with smart limiting + `exclude_tests` + `group_by_file` + pagination |",
+          "| `rails_get_service_pattern` | Service objects: interface, dependencies, side effects, callers |",
+          "| `rails_get_job_pattern` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
+          "| `rails_get_env` | Environment variables + credentials keys (not values) + external services |",
+          "| `rails_get_partial_interface(partial:\"X\")` | Partial locals contract: what to pass + usage examples |",
+          "| `rails_get_turbo_map` | Turbo Stream/Frame wiring: broadcasts → subscriptions + mismatch warnings |",
+          "| `rails_get_helper_methods` | App + framework helper methods with view cross-references |",
+          "| `rails_get_config` | Database adapter, auth framework, assets stack, cache, queue, Action Cable |",
+          "| `rails_get_gems` | Notable gems with versions, categories, config file locations |",
+          "| `rails_get_conventions` | App patterns: auth checks, flash messages, create action template, test patterns |",
+          "| `rails_security_scan` | Brakeman static analysis: SQL injection, XSS, mass assignment |",
           ""
         ]
       end

data/lib/rails_ai_context/serializers/windsurf_rules_serializer.rb

@@ -65,37 +65,80 @@ module RailsAiContext
         lines.join("\n")
       end
 
-      def render_mcp_tools_rule # rubocop:disable Metrics/MethodLength
+      def render_mcp_tools_rule # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         lines = [
-          "# Rails MCP Tools (25) — MANDATORY, Use Before Read",
+          "# Rails MCP Tools — MANDATORY, Use Before Read/Grep",
           "",
-          "CRITICAL: This project has live MCP tools. Use them for ALL context gathering.",
-          "Read files ONLY when you are about to edit them.",
+          "This project has 25 live MCP tools. You MUST use them instead of reading files.",
+          "Read files ONLY when you are about to Edit them.",
           "",
-          "Mandatory Workflow:",
-          "1. Gathering context → use MCP tools (NOT file reads)",
-          "2. Reading files → ONLY files you will edit",
-          "3. After editing → rails_validate(files:[...]) every time",
+          "What Are You Trying to Do?",
           "",
-          "Do NOT Bypass:",
-          "- Reading db/schema.rb → rails_get_schema(table:\"name\")",
-          "- Reading config/routes.rb → rails_get_routes(controller:\"name\")",
-          "- Reading model files → rails_get_model_details(model:\"Name\")",
-          "- Grep for code → rails_search_code(pattern:\"regex\")",
-          "- Reading test files → rails_get_test_info(model:\"Name\")",
-          "- Reading controller → rails_get_controllers(controller:\"Name\", action:\"x\")",
-          "- Reading JS for Stimulus → rails_get_stimulus(controller:\"name\")",
-          "- Multiple reads for feature → rails_analyze_feature(feature:\"keyword\")",
-          "- ruby -c / erb / node -c → rails_validate(files:[...])",
+          "Understand a feature or area:",
+          "  rails_analyze_feature(feature:\"cook\") — models + controllers + routes + services + jobs + views + tests in one call",
+          "  rails_get_context(model:\"Cook\") — schema + model + controller + views assembled together",
+          "",
+          "Understand a method (who calls it, what it calls):",
+          "  rails_search_code(pattern:\"can_cook?\", match_type:\"trace\") — definition + source + siblings + all callers + test coverage",
+          "",
+          "Add a field or modify a model:",
+          "  rails_get_schema(table:\"cooks\") — columns, types, indexes, defaults, encrypted hints",
+          "  rails_get_model_details(model:\"Cook\") — associations, validations, scopes, enums, callbacks, macros",
+          "",
+          "Fix a controller bug:",
+          "  rails_get_controllers(controller:\"CooksController\", action:\"create\") — source + inherited filters + render map + side effects + private methods",
+          "",
+          "Build or modify a view:",
+          "  rails_get_design_system(detail:\"standard\") — canonical HTML/ERB patterns to copy",
+          "  rails_get_view(controller:\"cooks\") — templates with ivars, Turbo wiring, Stimulus refs",
+          "  rails_get_partial_interface(partial:\"shared/status_badge\") — what locals to pass",
+          "",
+          "Write tests:",
+          "  rails_get_test_info(detail:\"standard\") — framework + fixtures + test template to copy",
+          "  rails_get_test_info(model:\"Cook\") — existing tests for a model",
+          "",
+          "Find code:",
+          "  rails_search_code(pattern:\"has_many\") — regex search with 2 lines of context",
+          "  rails_search_code(pattern:\"create\", match_type:\"definition\") — only def lines",
+          "  rails_search_code(pattern:\"can_cook\", match_type:\"call\") — only call sites",
+          "",
+          "After editing (EVERY time):",
+          "  rails_validate(files:[\"app/models/cook.rb\", \"app/views/cooks/new.html.erb\"], level:\"rails\") — syntax + semantics + security",
+          "",
+          "Rules:",
+          "1. NEVER read db/schema.rb, config/routes.rb, model files, or test files for reference — use the MCP tools above",
+          "2. NEVER use Grep for code search — use rails_search_code",
+          "3. NEVER run ruby -c, erb, or node -c — use rails_validate",
+          "4. Read files ONLY when you are about to Edit them",
+          "5. Start with detail:\"summary\" to orient, then drill into specifics",
           "",
           "All 25 Tools:",
-          "- rails_get_schema | rails_get_model_details | rails_get_routes | rails_get_controllers",
-          "- rails_get_view | rails_get_stimulus | rails_get_test_info | rails_analyze_feature",
-          "- rails_get_design_system | rails_get_edit_context | rails_validate | rails_search_code",
-          "- rails_get_config | rails_get_gems | rails_get_conventions | rails_security_scan",
-          "- rails_get_concern | rails_get_callbacks | rails_get_helper_methods | rails_get_service_pattern",
-          "- rails_get_job_pattern | rails_get_env | rails_get_partial_interface | rails_get_turbo_map",
-          "- rails_get_context(model:\"X\") — composite cross-layer context in one call"
+          "rails_analyze_feature(feature:\"X\") — Full-stack: models + controllers + routes + services + jobs + views + tests + gaps",
+          "rails_get_context(model:\"X\") — Composite: schema + model + controller + routes + views in one call",
+          "rails_search_code(pattern:\"X\", match_type:\"trace\") — Trace: definition + source + siblings + callers + test coverage",
+          "rails_get_controllers(controller:\"X\", action:\"Y\") — Action source + inherited filters + render map + side effects",
+          "rails_validate(files:[...], level:\"rails\") — Syntax + semantic validation + Brakeman security",
+          "rails_get_schema(table:\"X\") — Columns with indexed/unique/encrypted/default + orphaned table warnings",
+          "rails_get_model_details(model:\"X\") — Associations, validations, scopes, enums, macros, delegations",
+          "rails_get_routes(controller:\"X\") — Routes with code-ready helpers and controller filters inline",
+          "rails_get_view(controller:\"X\") — Templates with ivars, Turbo Frame/Stream IDs, Stimulus refs, partial locals",
+          "rails_get_design_system — Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards, modals",
+          "rails_get_stimulus(controller:\"X\") — Targets, values, actions + copy-paste HTML data-attributes",
+          "rails_get_test_info(model:\"X\") — Existing tests + fixture contents + test template",
+          "rails_get_concern(name:\"X\", detail:\"full\") — Concern methods with full source code + includers",
+          "rails_get_callbacks(model:\"X\") — Callbacks in Rails execution order with source",
+          "rails_get_edit_context(file:\"X\", near:\"Y\") — Code around a match with class/method context + line numbers",
+          "rails_search_code(pattern:\"X\") — Regex search with smart limiting + exclude_tests + group_by_file",
+          "rails_get_service_pattern — Service objects: interface, dependencies, side effects, callers",
+          "rails_get_job_pattern — Jobs: queue, retries, guard clauses, broadcasts, schedules",
+          "rails_get_env — Environment variables + credentials keys (not values) + external services",
+          "rails_get_partial_interface(partial:\"X\") — Partial locals contract: what to pass + usage examples",
+          "rails_get_turbo_map — Turbo Stream/Frame wiring: broadcasts to subscriptions + mismatch warnings",
+          "rails_get_helper_methods — App + framework helper methods with view cross-references",
+          "rails_get_config — Database adapter, auth framework, assets stack, cache, queue, Action Cable",
+          "rails_get_gems — Notable gems with versions, categories, config file locations",
+          "rails_get_conventions — App patterns: auth checks, flash messages, create action template, test patterns",
+          "rails_security_scan — Brakeman static analysis: SQL injection, XSS, mass assignment"
         ]
 
         lines.join("\n")

data/lib/rails_ai_context/tools/analyze_feature.rb

@@ -114,11 +114,17 @@ module RailsAiContext
               actions = info[:actions]&.join(", ") || "none"
               lines << "" << "### #{name}"
               lines << "- **Actions:** #{actions}"
+
+              # Inherited filters from parent controller
+              parent_filters = detect_parent_filters_for_analyze(info[:parent_class], controllers)
+              if parent_filters.any?
+                lines << "- **Inherited filters:** #{parent_filters.map { |f| "#{f[:name]} _(from #{info[:parent_class]})_" }.join(', ')}"
+              end
+
               filters = (info[:filters] || []).select { |f| f.is_a?(Hash) }.map do |f|
                 label = "#{f[:kind]} #{f[:name]}"
                 label += " only: #{Array(f[:only]).join(', ')}" if f[:only]&.any?
                 label += " except: #{Array(f[:except]).join(', ')}" if f[:except]&.any?
-                label += " unless: #{f[:unless]}" if f[:unless]
                 label
               end
               lines << "- **Filters:** #{filters.join('; ')}" if filters.any?
@@ -139,8 +145,14 @@ module RailsAiContext
             lines << "## Routes (#{route_count})"
             matched.sort.each do |ctrl, actions|
               actions.each do |r|
-                name_part = r[:name] ? " `#{r[:name]}`" : ""
-                lines << "- `#{r[:verb]}` `#{r[:path]}` → #{ctrl}##{r[:action]}#{name_part}"
+                params = r[:path].scan(/:(\w+)/).flatten
+                helper = if r[:name]
+                  args = params.any? ? "(#{params.map { |p| p == "id" ? "@record" : ":#{p}" }.join(', ')})" : ""
+                  " `#{r[:name]}_path#{args}`"
+                else
+                  ""
+                end
+                lines << "- `#{r[:verb]}` `#{r[:path]}` → #{ctrl}##{r[:action]}#{helper}"
               end
             end
           else
@@ -321,6 +333,18 @@ module RailsAiContext
             end
           end
 
+          # Check services
+          service_dir = File.join(root, "app", "services")
+          if Dir.exist?(service_dir)
+            Dir.glob(File.join(service_dir, "**", "*.rb")).each do |path|
+              next unless File.basename(path, ".rb").include?(pattern)
+              snake = File.basename(path, ".rb")
+              unless test_basenames.any? { |t| t.include?(snake) }
+                gaps << "Service `#{snake}` — no test file found"
+              end
+            end
+          end
+
           return if gaps.empty?
 
           lines << "## Test Coverage Gaps"
@@ -330,6 +354,28 @@ module RailsAiContext
           nil
         end
 
+        # Detect inherited filters from parent controller
+        def detect_parent_filters_for_analyze(parent_class, all_controllers)
+          return [] unless parent_class
+          parent_data = all_controllers[parent_class]
+          if parent_data
+            return (parent_data[:filters] || []).select { |f| f.is_a?(Hash) && f[:kind] == "before" && !f[:only]&.any? }
+          end
+
+          # Fallback: read source file
+          path = Rails.root.join("app", "controllers", "#{parent_class.underscore}.rb")
+          return [] unless File.exist?(path)
+          source = File.read(path, encoding: "UTF-8") rescue nil
+          return [] unless source
+
+          source.each_line.filter_map do |line|
+            next if line.include?("only:") || line.include?("except:")
+            { name: $1 } if line.match(/\A\s*before_action\s+:(\w+)/)
+          end
+        rescue
+          []
+        end
+
         # --- AF6: Related Models via Associations ---
         def discover_related_models(ctx, matched_models, lines)
           return if matched_models.empty?

data/lib/rails_ai_context/tools/get_concern.rb

@@ -18,13 +18,18 @@ module RailsAiContext
             type: "string",
             enum: %w[model controller all],
             description: "Filter by concern type. model: app/models/concerns/. controller: app/controllers/concerns/. all: both (default)."
+          },
+          detail: {
+            type: "string",
+            enum: %w[summary standard full],
+            description: "Detail level. summary: concern names only. standard: names + method signatures (default). full: method signatures with source code."
           }
         }
       )
 
       annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
 
-      def self.call(name: nil, type: "all", server_context: nil)
+      def self.call(name: nil, type: "all", detail: "standard", server_context: nil)
         root = rails_app.root.to_s
         max_size = RailsAiContext.configuration.max_file_size
 
@@ -36,7 +41,7 @@ module RailsAiContext
 
         # Specific concern — full detail
         if name
-          return show_concern(name, concern_dirs, root, max_size)
+          return show_concern(name, concern_dirs, root, max_size, detail)
         end
 
         # List all concerns
@@ -67,7 +72,7 @@ module RailsAiContext
         end
       end
 
-      private_class_method def self.show_concern(name, concern_dirs, root, max_size)
+      private_class_method def self.show_concern(name, concern_dirs, root, max_size, detail = "standard")
         # Find the concern file — try underscore variants and nested paths
         underscore = name.underscore
         file_path = nil
@@ -121,14 +126,47 @@ module RailsAiContext
         public_methods = parse_public_methods(source)
         if public_methods.any?
           lines << "" << "## Public Methods"
-          public_methods.each { |m| lines << "- `#{m}`" }
+          if detail == "full"
+            public_methods.each do |m|
+              method_name = m.to_s.split("(").first
+              method_source = extract_method_source(source, method_name)
+              if method_source
+                lines << "### #{m}"
+                lines << "```ruby"
+                lines << method_source
+                lines << "```"
+                lines << ""
+              else
+                lines << "- `#{m}`"
+              end
+            end
+          else
+            public_methods.each { |m| lines << "- `#{m}`" }
+          end
         end
 
         # Parse class methods (inside class_methods block or def self.)
         class_methods = parse_class_methods(source)
         if class_methods.any?
           lines << "" << "## Class Methods"
-          class_methods.each { |m| lines << "- `#{m}`" }
+          if detail == "full"
+            class_methods.each do |m|
+              method_name = m.to_s.split("(").first
+              # Try both `def method_name` and `def self.method_name`
+              method_source = extract_method_source(source, method_name) || extract_method_source(source, "self.#{method_name}")
+              if method_source
+                lines << "### #{m}"
+                lines << "```ruby"
+                lines << method_source
+                lines << "```"
+                lines << ""
+              else
+                lines << "- `#{m}`"
+              end
+            end
+          else
+            class_methods.each { |m| lines << "- `#{m}`" }
+          end
         end
 
         # Parse callbacks defined in the concern
@@ -345,6 +383,32 @@ module RailsAiContext
         []
       end
 
+      # Extract method source from raw source string using indentation-based matching
+      private_class_method def self.extract_method_source(source, method_name)
+        source_lines = source.lines
+        escaped = Regexp.escape(method_name.to_s)
+        # Don't use \b after ? or ! — they ARE word boundaries
+        pattern = if method_name.to_s.end_with?("?") || method_name.to_s.end_with?("!")
+          /\A\s*def\s+#{escaped}/
+        else
+          /\A\s*def\s+#{escaped}\b/
+        end
+        start_idx = source_lines.index { |l| l.match?(pattern) }
+        return nil unless start_idx
+
+        def_indent = source_lines[start_idx][/\A\s*/].length
+        result = []
+
+        source_lines[start_idx..].each_with_index do |line, i|
+          result << line.rstrip
+          break if i > 0 && line.match?(/\A\s{#{def_indent}}end\b/)
+        end
+
+        result.join("\n")
+      rescue
+        nil
+      end
+
       private_class_method def self.find_includers(concern_name, root, concern_type)
         includers = []
         search_dirs = []

data/lib/rails_ai_context/tools/get_schema.rb

@@ -160,6 +160,14 @@ module RailsAiContext
             lines << cols
             lines << ""
           end
+
+          # Detect orphaned tables (no ActiveRecord model maps to them)
+          orphaned = paginated.select { |name| models_for_table(name).empty? }
+          if orphaned.any?
+            lines << "\u26A0 **Orphaned tables** (no ActiveRecord model): #{orphaned.join(', ')}"
+            lines << ""
+          end
+
           lines << "_Use `detail:\"summary\"` for all #{total} tables, `detail:\"full\"` for indexes/FKs, or `table:\"name\"` for one table._" if total > limit
           text_response(lines.join("\n"))
 

data/lib/rails_ai_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  VERSION = "2.0.3"
+  VERSION = "2.0.5"
 end

data/server.json

@@ -7,11 +7,11 @@
     "url": "https://github.com/crisnahine/rails-ai-context",
     "source": "github"
   },
-  "version": "2.0.3",
+  "version": "2.0.5",
   "packages": [
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v2.0.3/rails-ai-context-mcp.mcpb",
+      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v2.0.5/rails-ai-context-mcp.mcpb",
       "fileSha256": "dd711a0ad6c4de943ae4da94eaf59a6dc9494b9d57f726e24649ed4e2f156990",
       "transport": {
         "type": "stdio"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.0.5
 platform: ruby
 authors:
 - crisnahine