rails-ai-context 2.0.4 → 2.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70a0eb825c34329a1f0bc9d387a4a2bfd2a42b56717305dcaa5df4c0712264f7
-  data.tar.gz: 5a2e229f4bbcaf39d9eebe3e3851444ceed0860b79ad4bcccf11fdba9487ac0a
+  metadata.gz: e17feb99495b6f8328eedaa95020ca097aa4ee7df658ed0a51a925cd6961cdee
+  data.tar.gz: 8b5dc406788cc2af104813e0711887bfc6a5ef0e97ddc79464291b0da74ad7df
 SHA512:
-  metadata.gz: eca131443eb443b24a7681233f5e5adcef9a2c2fb3f4ee6d4e665c795470bed1e0bfdfa92f4f4861136f3e7c2b34210972273b2d0b976f3ffb7fa88834ed31b7
-  data.tar.gz: b2e96f95e25b8e9cf9fb140446969fc7a027ff22e210321c3ade42da59aa7c6ed702ceabc0c8be62e8a56c2fa25230dcb460bfd3182716c3a1ef1cc300b836bb
+  metadata.gz: a8b7ff36197da72c8b1d3ca1c7199da2333015fda502a37c83d819a95394732449b2d26f20084a14687b59c6fcde10445dda5fbf4705890793ae213bda2cba33
+  data.tar.gz: 22e5d0ae93d2af2c01f383197a10e454667f0d24af0bb463a191922913702d3c976f04fb918e7716833af874ee1913d86182d234e36c65bb568469a8ead8f116

data/CHANGELOG.md

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

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -297,134 +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, orphaned table detection",
-          "- `rails_get_schema(detail:\"summary\")` — all tables with column counts + orphaned tables (tables with no ActiveRecord model)",
-          "- `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, including inherited filters from parent controllers and code-ready route helpers",
-          "",
-          "**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 with trace mode for deep call-chain analysis",
-          "- `rails_search_code(pattern:\"regex\", file_type:\"rb\")` — basic regex search across files",
-          "- `rails_search_code(pattern:\"can_cook?\", match_type:\"trace\")` — trace mode: definition + class context + source + siblings + callers with route chain + test coverage",
-          "- `rails_search_code(pattern:\"cook\", exclude_tests: true)` — search app code only, skip test files",
-          "",
-          "**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_concern(name:\"Searchable\", detail:\"full\")` — + method source code",
-          "",
-          "**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,43 +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\")` — includes orphaned table warnings | 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\")` — models + controllers (inherited filters) + routes (code-ready helpers) + services + jobs + views + tests + gaps | Explore agent / Grep |",
-          "| Find code | `rails_search_code(pattern:\"x\", match_type:\"trace\")` | 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\", detail:\"full\")` — concern methods with source code | `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_search_code(pattern:\"method\", match_type:\"trace\")` — **trace mode**: definition + class context + source + siblings + callers + test coverage in one call",
-          "- `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
@@ -267,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,50 +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",
           "",
-          "## Power Features",
-          "- `rails_search_code(pattern:\"method\", match_type:\"trace\")` — trace: definition + source + siblings + callers + tests",
-          "- `rails_get_concern(name:\"X\", detail:\"full\")` — concern methods with source code",
-          "- `rails_analyze_feature` — full-stack with inherited filters, route helpers, test gaps",
-          "- `rails_get_schema` — columns, indexes, defaults, encrypted hints, orphaned table warnings"
+          "| 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,50 +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",
           "",
-          "## Power Features",
-          "- `rails_search_code(pattern:\"method\", match_type:\"trace\")` — trace: definition + source + siblings + callers + tests",
-          "- `rails_get_concern(name:\"X\", detail:\"full\")` — concern methods with source code",
-          "- `rails_analyze_feature` — full-stack with inherited filters, route helpers, test gaps",
-          "- `rails_get_schema` — columns, indexes, defaults, encrypted hints, orphaned table warnings"
+          "| 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,42 +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:\"...\")` — models + controllers (inherited filters) + routes (code-ready helpers) + services + jobs + views + tests + gaps",
-          "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\")` — includes orphaned table warnings |",
-          "| 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\", match_type:\"trace\")` |",
-          "| 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(name:\"X\", detail:\"full\")` — concern methods with source code | `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_search_code(pattern:\"method\", match_type:\"trace\")` — **trace mode**: definition + class context + source + siblings + callers + test coverage in one call",
-          "- `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,43 +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",
           "",
-          "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",
+          "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",
           "",
-          "Power Features:",
-          "- rails_search_code(pattern:\"method\", match_type:\"trace\") — trace: definition + source + siblings + callers + tests",
-          "- rails_get_concern(name:\"X\", detail:\"full\") — concern methods with source code",
-          "- rails_analyze_feature — full-stack with inherited filters, route helpers, test gaps",
-          "- rails_get_schema — columns, indexes, defaults, encrypted hints, orphaned table warnings"
+          "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_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/get_concern.rb

@@ -386,7 +386,14 @@ module RailsAiContext
       # 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
-        start_idx = source_lines.index { |l| l.match?(/\A\s*def\s+#{Regexp.escape(method_name.to_s)}\b/) }
+        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

data/lib/rails_ai_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  VERSION = "2.0.4"
+  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.4",
+  "version": "2.0.5",
   "packages": [
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v2.0.4/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.4
+  version: 2.0.5
 platform: ruby
 authors:
 - crisnahine