rails-ai-context 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34ef5e454a22f9719cf4439c70867a4e2f9dc900d34e1cca0f4ecd723e3a3308
-  data.tar.gz: d7545c9afd73831f0f32e0808f82856e1cf48c3763308049f5ba54d453f3f452
+  metadata.gz: 28fe01be28232f19cf9fab8cb6b696630e21d663e47b426a206e771b0096bfcb
+  data.tar.gz: 488fdca01c018f6f9f468e7f03c78c2e6456e93dde0c7a89d17a5c554160b305
 SHA512:
-  metadata.gz: f29724289bcf91b5aeb776cfac4eec673a8bb8b02016108bab7a52f9f6f52b4fe5f3045cee43053a4b6e660619800dc8ea6f0141ed5bdd812d00898d00f9d7ef
-  data.tar.gz: 3178d4a6347de30aaf92e13b5db4d976fe6d2c0888de60b451bc187e9ae71518186c204c97f74e37d159431c2ea149d9fc19db00ab338bce44ffda6c33ef6da3
+  metadata.gz: bd0017a556c8a728b58ac5b18dc52682a825602e295be6a54f8bde15baf552d62247d57441af936d8762d00763aec076e46dc52d745274bf74362df5105bb0ec
+  data.tar.gz: e16d3d1306ad9d4aa617a72e0311cbf1ffb8f2f5e80074913e3c1be62ceca2f8325642e3cf1515c6c14a930349b2f5a78a98f913d7c53f011bf3e1b6d7450eaa

data/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.2] - 2026-03-25
+
+### Added
+
+- **`match_type:"trace"` in search_code** — full method picture in one call: definition + source code + all callers grouped by type (Controller/Model/View/Job/Service/Test) + internal calls. The game changer for code navigation.
+- **`match_type:"call"`** — find call sites only, excluding definitions.
+- **Smart result limiting** — <10 shows all, 10-100 shows half, >100 caps at 100. Pagination via `offset:` param.
+- **`exclude_tests:true`** — skip test/spec/features directories in search results.
+- **`group_by_file:true`** — group search results by file with match counts.
+- **Inline cross-references** — schema shows model name + association count per table, routes show controller filters inline, views use pipe-separated metadata.
+- **Test template generation** — `get_test_info(detail:"standard")` includes a copy-paste test template matching the app's patterns (Minitest/RSpec, Devise sign_in, fixtures).
+- **Interactive AI tool selection** — install generator and `rails ai:context` prompt users to select which AI tools they use (Claude, Cursor, Copilot, Windsurf, OpenCode). Selection saved to `config.ai_tools`.
+- **Brakeman in validate** — `rails_validate(level:"rails")` now runs Brakeman security checks inline alongside syntax and semantic checks.
+
+### Fixed
+
+- **Documentation audit** — fixed max_tool_response_chars reference (120K→200K), added missing search_code params to GUIDE, added config.ai_tools to config reference.
+
+## [2.0.1] - 2026-03-25
+
+### Fixed
+
+- **MCP-first mandatory workflow in all serializers** — all 6 serializer outputs (Claude, Cursor, Copilot, Windsurf, OpenCode) now use "MANDATORY, Use Before Read" language with structured workflow, anti-patterns table, and "Do NOT Bypass" rules. AI agents are explicitly instructed to never read reference files directly.
+- **27 type-safety bugs in serializers** — fixed `.keys` called on Array values (same pattern as #14) across `design_system_helper.rb`, `get_design_system.rb`, `markdown_serializer.rb`, and `stack_overview_helper.rb`.
+- **Strong params JSONB check** — no longer skips the entire check when JSONB columns exist. Plain-word params allowed (could be JSON keys), `_id` params still validated.
+- **Strong params test skip on Ruby < 3.3** — test now skips gracefully when Prism is unavailable, matching the tool's own degradation.
+- **Issue #14** — `multi_db[:databases].keys` crash on Array fixed.
+- **Search code NON_CODE_GLOBS** — excludes lock files, docs, CI configs, generated context from all searches.
+
 ## [2.0.0] - 2026-03-24
 
 ### Added

data/README.md

@@ -111,7 +111,7 @@ The gem exposes **25 read-only tools** via MCP that AI clients call on-demand:
 | `rails_get_test_info` | Test framework, factory attributes/traits, fixtures, CI config, coverage |
 | `rails_get_gems` | Notable gems categorized by function with config location hints |
 | `rails_get_conventions` | Architecture patterns, frontend stack, directory structure |
-| `rails_search_code` | Ripgrep search with 2-line context default, `match_type:"definition"` for method defs only |
+| `rails_search_code` | Ripgrep search with `match_type:"trace"` (definition + callers + internal calls in one shot), `"definition"`, `"call"`, `"class"` filters, smart result limiting, pagination |
 | `rails_get_view` | View templates, partials with render locals, Stimulus references |
 | `rails_get_stimulus` | Stimulus controllers — targets, values, actions, outlets, lifecycle methods |
 | `rails_get_edit_context` | Surgical edit helper — returns code with class/method context and line numbers |
@@ -146,7 +146,7 @@ rails_get_routes(controller: "users")         # → routes for one controller
 rails_get_model_details(model: "User")        # → associations, validations, scopes
 ```
 
-A safety net (`max_tool_response_chars`, default 120K) truncates oversized responses with hints to use filters.
+A safety net (`max_tool_response_chars`, default 200K) truncates oversized responses with hints to use filters.
 
 ---
 
@@ -351,6 +351,7 @@ end
 | **Extensibility** | | |
 | `custom_tools` | `[]` | Additional MCP tool classes to register alongside built-in tools |
 | `skip_tools` | `[]` | Built-in tool names to exclude (e.g. `%w[rails_security_scan]`) |
+| `ai_tools` | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot windsurf opencode]` |
 </details>
 
 ---

data/docs/GUIDE.md

@@ -561,31 +561,38 @@ Ripgrep-powered regex search across the codebase.
 
 | Param | Type | Description |
 |-------|------|-------------|
-| `pattern` | string | **Required.** Regex pattern to search for. |
+| `pattern` | string | **Required.** Regex pattern or method name to search for. |
 | `path` | string | Subdirectory to search in (e.g. `app/models`, `config`). Default: entire app. |
-| `file_type` | string | Filter by file type (e.g. `rb`, `erb`, `js`). Alphanumeric only. |
-| `match_type` | string | Filter matches: `any` (default), `definition` (only `def` lines), `class` (only `class`/`module` lines). |
+| `file_type` | string | Filter by file extension (e.g. `rb`, `erb`, `js`). Alphanumeric only. |
+| `match_type` | string | `any` (default), `definition` (def lines), `class` (class/module lines), `call` (call sites only), `trace` (**full picture** — definition + source + callers + internal calls). |
 | `exact_match` | boolean | Match whole words only (wraps pattern in `\b` boundaries). Default: false. |
-| `max_results` | integer | Max results to return. Default: 30, max: 100. |
+| `exclude_tests` | boolean | Exclude test/spec/features directories. Default: false. |
+| `group_by_file` | boolean | Group results by file with match counts. Default: false. |
+| `offset` | integer | Skip this many results for pagination. Default: 0. |
 | `context_lines` | integer | Lines of context before and after each match (like grep -C). Default: 2, max: 5. |
 
+Smart result limiting: <10 results shows all, 10-100 shows half, >100 caps at 100. Use `offset` for pagination.
+
 **Examples:**
 
 ```
-rails_search_code(pattern: "has_secure_password")
-  → All files containing has_secure_password
+rails_search_code(pattern: "can_cook?", match_type: "trace")
+  → FULL PICTURE: definition + source code + all callers grouped by type + internal calls
+
+rails_search_code(pattern: "create", match_type: "definition")
+  → Only `def create` / `def self.create` lines
 
-rails_search_code(pattern: "class.*Controller", file_type: "rb")
-  → All Ruby files with controller class definitions
+rails_search_code(pattern: "can_cook", match_type: "call")
+  → Only call sites (excludes the definition)
 
-rails_search_code(pattern: "def create", file_type: "rb", max_results: 50)
-  → First 50 create methods across the codebase
+rails_search_code(pattern: "Controller", match_type: "class")
+  → All class/module definitions matching *Controller
 
-rails_search_code(pattern: "current_user", path: "app/controllers")
-  → Search only in app/controllers/
+rails_search_code(pattern: "has_many", group_by_file: true)
+  → Results grouped by file with match counts
 
-rails_search_code(pattern: "validates", context_lines: 3)
-  → Matches with 3 lines of context before and after (default is 2)
+rails_search_code(pattern: "cook", exclude_tests: true)
+  → Skip test/spec directories
 
 rails_search_code(pattern: "activate", match_type: "definition")
   → Only `def activate` / `def self.activate` lines (skips method calls)
@@ -1175,6 +1182,7 @@ end
 | `cache_ttl` | Integer | `60` | Cache TTL in seconds for introspection results |
 | `custom_tools` | Array | `[]` | Additional MCP tool classes to register alongside built-in tools |
 | `skip_tools` | Array | `[]` | Built-in tool names to exclude (e.g. `%w[rails_security_scan]`) |
+| `ai_tools` | Array | `nil` (all) | AI tools to generate context for: `%i[claude cursor copilot windsurf opencode]`. Selected during install. |
 | `excluded_models` | Array | internal Rails models | Models to skip |
 | `excluded_paths` | Array | `node_modules tmp log vendor .git` | Paths excluded from code search |
 | `sensitive_patterns` | Array | `.env`, `.key`, `.pem`, credentials | File patterns blocked from search and read tools |

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

@@ -9,6 +9,43 @@ module RailsAiContext
 
       desc "Install rails-ai-context: creates initializer, MCP config, and generates initial context files."
 
+      AI_TOOLS = {
+        "1" => { key: :claude,   name: "Claude Code",     files: "CLAUDE.md + .claude/rules/",                        format: :claude },
+        "2" => { key: :cursor,   name: "Cursor",          files: ".cursor/rules/",                                     format: :cursor },
+        "3" => { key: :copilot,  name: "GitHub Copilot",  files: ".github/copilot-instructions.md + .github/instructions/", format: :copilot },
+        "4" => { key: :windsurf, name: "Windsurf",        files: ".windsurfrules + .windsurf/rules/",                  format: :windsurf },
+        "5" => { key: :opencode, name: "OpenCode",        files: "AGENTS.md",                                          format: :opencode }
+      }.freeze
+
+      def select_ai_tools
+        say ""
+        say "Which AI tools do you use? (select all that apply)", :yellow
+        say ""
+        AI_TOOLS.each do |num, info|
+          say "  #{num}. #{info[:name].ljust(16)} → #{info[:files]}"
+        end
+        say "  a. All of the above"
+        say ""
+
+        input = ask("Enter numbers separated by commas (e.g. 1,2) or 'a' for all:").strip.downcase
+
+        @selected_formats = if input == "a" || input == "all"
+          AI_TOOLS.values.map { |t| t[:format] }
+        else
+          nums = input.split(/[\s,]+/)
+          nums.filter_map { |n| AI_TOOLS[n]&.dig(:format) }
+        end
+
+        if @selected_formats.empty?
+          say "No tools selected — defaulting to all.", :yellow
+          @selected_formats = AI_TOOLS.values.map { |t| t[:format] }
+        end
+
+        selected_names = AI_TOOLS.values.select { |t| @selected_formats.include?(t[:format]) }.map { |t| t[:name] }
+        say ""
+        say "Selected: #{selected_names.join(', ')}", :green
+      end
+
       def create_mcp_config
         mcp_path = Rails.root.join(".mcp.json")
         server_entry = {
@@ -36,46 +73,33 @@ module RailsAiContext
       end
 
       def create_initializer
+        tools_line = if @selected_formats.size == AI_TOOLS.size
+          "  # config.ai_tools = %i[claude cursor copilot windsurf opencode]  # default: all"
+        else
+          "  config.ai_tools = %i[#{@selected_formats.join(' ')}]"
+        end
+
         create_file "config/initializers/rails_ai_context.rb", <<~RUBY
           # frozen_string_literal: true
 
           RailsAiContext.configure do |config|
+            # AI tools to generate context files for (selected during install)
+            # Run `rails generate rails_ai_context:install` to change selection
+          #{tools_line}
+
             # Introspector preset:
-            #   :full     — all 28 introspectors (default — schema, models, routes, views, turbo, auth, API, assets, devops, etc.)
-            #   :standard — 13 core introspectors (schema, models, routes, jobs, gems, conventions, controllers, tests, migrations, stimulus, view_templates, design_tokens, config)
+            #   :full     — all 28 introspectors (default)
+            #   :standard — 13 core introspectors
             # config.preset = :full
 
-            # Or cherry-pick individual introspectors:
-            # config.introspectors += %i[views turbo auth api]
-
             # Models to exclude from introspection
             # config.excluded_models += %w[AdminUser InternalThing]
 
-            # Paths to exclude from code search
-            # config.excluded_paths += %w[vendor/bundle]
-
-            # Context mode for generated files (CLAUDE.md, .cursor/rules/, etc.)
-            # :compact — smart, ≤150 lines, references MCP tools for details (default)
-            # :full    — dumps everything into context files (good for small apps <30 models)
+            # Context mode: :compact (default, ≤150 lines) or :full (dumps everything)
             # config.context_mode = :compact
 
-            # Max lines for CLAUDE.md in compact mode
-            # config.claude_max_lines = 150
-
-            # Max response size for MCP tool results (chars). Safety net for large apps.
-            # config.max_tool_response_chars = 120_000
-
             # Live reload: auto-invalidate MCP tool caches on file changes
-            # :auto (default) — enable if `listen` gem is available
-            # true  — enable, raise if `listen` is missing
-            # false — disable entirely
             # config.live_reload = :auto
-            # config.live_reload_debounce = 1.5  # seconds
-
-            # Auto-mount HTTP MCP endpoint at /mcp
-            # config.auto_mount = false
-            # config.http_path  = "/mcp"
-            # config.http_port  = 6029
           end
         RUBY
 
@@ -104,13 +128,21 @@ module RailsAiContext
         say ""
         say "Generating AI context files...", :yellow
 
-        if Rails.application
-          require "rails_ai_context"
-          context = RailsAiContext.introspect
-          files = RailsAiContext.generate_context(format: :all)
-          files.each { |f| say "  Created #{f}", :green }
-        else
+        unless Rails.application
           say "  Skipped (Rails app not fully loaded). Run `rails ai:context` after install.", :yellow
+          return
+        end
+
+        require "rails_ai_context"
+
+        @selected_formats.each do |fmt|
+          begin
+            result = RailsAiContext.generate_context(format: fmt)
+            (result[:written] || []).each { |f| say "  ✅ #{f}", :green }
+            (result[:skipped] || []).each { |f| say "  ⏭️  #{f} (unchanged)", :yellow }
+          rescue => e
+            say "  ❌ #{fmt}: #{e.message}", :red
+          end
         end
       end
 
@@ -120,27 +152,26 @@ module RailsAiContext
         say " rails-ai-context installed!", :cyan
         say "=" * 50, :cyan
         say ""
-        say "Quick start:", :yellow
-        say "  rails ai:context         # Generate all context files"
-        say "  rails ai:context:claude   # Generate CLAUDE.md only"
-        say "  rails ai:context:cursor   # Generate .cursor/rules/ only"
-        say "  rails ai:serve           # Start MCP server (stdio)"
-        say "  rails ai:inspect         # Print introspection summary"
+        say "Your setup:", :yellow
+        AI_TOOLS.each_value do |info|
+          next unless @selected_formats.include?(info[:format])
+          say "  ✅ #{info[:name].ljust(16)} → #{info[:files]}"
+        end
         say ""
-        say "Generated files per AI tool:", :yellow
-        say "  Claude Code    → CLAUDE.md + .claude/rules/*.md"
-        say "  OpenCode       → AGENTS.md"
-        say "  Cursor         → .cursor/rules/*.mdc"
-        say "  Windsurf       → .windsurfrules + .windsurf/rules/*.md"
-        say "  GitHub Copilot → .github/copilot-instructions.md + .github/instructions/*.instructions.md"
+        say "Commands:", :yellow
+        say "  rails ai:context         # Regenerate context files"
+        say "  rails ai:serve           # Start MCP server (25 live tools)"
+        say "  rails ai:doctor          # Check AI readiness"
+        say "  rails ai:inspect         # Print introspection summary"
         say ""
         say "MCP auto-discovery:", :yellow
         say "  .mcp.json is auto-detected by Claude Code and Cursor."
-        say "  No manual MCP config needed — just open your project."
+        say "  No manual config needed — just open your project."
         say ""
-        say "Context modes:", :yellow
-        say "  rails ai:context         # compact mode (default, smart for any app size)"
-        say "  rails ai:context:full    # full dump (good for small apps)"
+        say "To add more AI tools later:", :yellow
+        say "  rails ai:context:cursor   # Generate for Cursor"
+        say "  rails ai:context:copilot  # Generate for Copilot"
+        say "  rails generate rails_ai_context:install  # Re-run to pick tools"
         say ""
         say "Commit context files and .mcp.json so your team benefits!", :green
       end

data/lib/rails_ai_context/configuration.rb

@@ -75,6 +75,10 @@ module RailsAiContext
     # Built-in tool names to skip (e.g. %w[rails_security_scan rails_get_design_system])
     attr_accessor :skip_tools
 
+    # Which AI tools to generate context for (selected during install)
+    # nil = all formats, or %i[claude cursor copilot windsurf opencode]
+    attr_accessor :ai_tools
+
     # Filtering — customize what's hidden from AI output
     attr_accessor :excluded_controllers   # Controller classes hidden from listings (e.g. DeviseController)
     attr_accessor :excluded_route_prefixes # Route controller prefixes hidden with app_only (e.g. action_mailbox/)
@@ -148,6 +152,7 @@ module RailsAiContext
       ]
       @custom_tools             = []
       @skip_tools               = []
+      @ai_tools                 = nil
       @search_extensions        = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
       @concern_paths            = %w[app/models/concerns app/controllers/concerns]
     end

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -96,7 +96,8 @@ module RailsAiContext
         rescue; end
 
         lines << ""
-        lines << "Use MCP tools for detailed data. Start with `detail:\"summary\"`."
+        lines << "ALWAYS use MCP tools for context — do NOT read reference files directly."
+        lines << "Start with `detail:\"summary\"`. Read files ONLY when you will Edit them."
 
         lines.join("\n")
       end
@@ -294,31 +295,52 @@ module RailsAiContext
 
       def render_mcp_tools_reference # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         lines = [
-          "# Rails MCP Tools — ALWAYS Use These First",
-          "",
-          "IMPORTANT: This project has live MCP tools that return parsed, up-to-date data.",
-          "Use these tools for reference-only files (schema, routes, tests). For files you will edit, Read them directly.",
-          "The tools return structured, token-efficient summaries with line numbers.",
-          "",
-          "## When to use MCP tools vs Read",
-          "- Use MCP for files you WON'T edit (schema, routes, understanding context)",
-          "- For files you WILL edit, just Read them directly — you need Read before Edit anyway",
-          "- Use MCP for orientation (summary calls) on large codebases",
-          "- Skip MCP when CLAUDE.md + rules already have the info you need",
-          "- Do NOT call rails_get_model_details if CLAUDE.md already shows the model's associations and column types",
-          "- Do NOT call rails_get_stimulus just to check if Stimulus exists — CLAUDE.md confirms it",
-          "",
-          "## After editing — ALWAYS use rails_validate (not Bash)",
-          "- `rails_validate(files:[\"app/models/cook.rb\", \"app/controllers/cooks_controller.rb\", \"app/views/cooks/index.html.erb\"])` — one call checks all",
+          "# 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.",
           "",
-          "## Reference-only files — check rules first, then MCP or Read if needed",
-          "- db/schema.rb — column names and types are in rails-schema.md rules. Read only if you need constraints/defaults.",
-          "- config/routes.rb — use `rails_get_routes` for reference. Read directly if you'll add routes.",
-          "- Model files — scopes, constants, enums are in rails-models.md rules. Read for business logic/methods.",
-          "- app/javascript/controllers/index.js — Stimulus auto-registers controllers. No need to read.",
-          "- Test files — use `rails_get_test_info(detail:\"full\")` for patterns.",
+          "## 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)",
           "",

data/lib/rails_ai_context/serializers/claude_serializer.rb

@@ -200,30 +200,38 @@ module RailsAiContext
         [
           "## MCP Tools (25) — ALWAYS Use These First",
           "",
-          "Use MCP for reference files (schema, routes, tests). Read directly if you'll edit.",
-          "MCP tools return line numbers. Start with `detail:\"summary\"`.",
+          "This project has live MCP tools. You MUST use them instead of reading reference files.",
+          "Start with `detail:\"summary\"`, then drill into specifics.",
           "",
-          "- `rails_get_schema(detail:\"summary\")` → `rails_get_schema(table:\"name\")`",
-          "- `rails_get_model_details(detail:\"summary\")` → `rails_get_model_details(model:\"Name\")`",
-          "- `rails_get_routes(detail:\"summary\")` → `rails_get_routes(controller:\"name\")`",
-          "- `rails_get_controllers(controller:\"Name\", action:\"index\")` — one action's source code",
-          "- `rails_get_view(controller:\"cooks\")` — view list; `(path:\"cooks/index.html.erb\")` — content",
-          "- `rails_get_stimulus(detail:\"summary\")` → `(controller:\"name\")` — targets, actions, values",
-          "- `rails_get_test_info(detail:\"full\")` — fixtures, factories, helpers; `(model:\"Cook\")` — tests",
-          "- `rails_analyze_feature(feature:\"auth\")` — schema + models + controllers + routes for a feature",
-          "- `rails_get_design_system` — color palette, component patterns, canonical page examples",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_search_code`",
-          "- `rails_validate(files:[\"path/to/file.rb\"])` — validate Ruby, ERB, JS syntax in one call",
-          "- `rails_security_scan` — Brakeman security analysis",
-          "- `rails_get_concern(name:\"Searchable\")` — concern methods and includers",
-          "- `rails_get_callbacks(model:\"User\")` — model callbacks in execution order",
-          "- `rails_get_helper_methods` — app + framework helpers",
-          "- `rails_get_service_pattern` — service object patterns and interfaces",
-          "- `rails_get_job_pattern` — background job patterns and schedules",
-          "- `rails_get_env` — environment variables and credentials keys",
-          "- `rails_get_partial_interface(path:\"shared/_form\")` — partial locals contract",
-          "- `rails_get_turbo_map` — Turbo Streams/Frames wiring",
-          "- `rails_get_context(model:\"User\")` — composite cross-layer context",
+          "### 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",
+          "",
+          "### 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 |",
+          "",
+          "### 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",
           ""
         ]
       end
@@ -256,12 +264,20 @@ module RailsAiContext
         [
           "## Rules",
           "- Follow existing patterns and conventions",
-          "- Use the MCP tools to check schema before writing migrations",
           "- 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

@@ -219,36 +219,38 @@ module RailsAiContext
           "applyTo: \"**/*\"",
           "---",
           "",
-          "# Rails MCP Tools (25) — Use These First",
+          "# Rails MCP Tools (25) — MANDATORY, Use Before Read",
           "",
-          "Use MCP for reference files (schema, routes, tests). Read directly if you'll edit.",
-          "MCP tools return line numbers for surgical edits.",
-          "**Start with `detail:\"summary\"`, then drill into specifics.**",
+          "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.",
           "",
-          "- `rails_get_schema(detail:\"summary\")` → `rails_get_schema(table:\"name\")`",
-          "- `rails_get_model_details(detail:\"summary\")` → `rails_get_model_details(model:\"Name\")`",
-          "- `rails_get_routes(detail:\"summary\")` → `rails_get_routes(controller:\"name\")`",
-          "- `rails_get_controllers(controller:\"Name\", action:\"index\")` — one action's source code",
-          "- `rails_get_view(controller:\"cooks\")` — view list; `(path:\"cooks/index.html.erb\")` — content",
-          "- `rails_get_stimulus(detail:\"summary\")` → `(controller:\"name\")` — targets, actions, values",
-          "- `rails_get_test_info(detail:\"full\")` — fixtures, factories, helpers; `(model:\"Cook\")` — existing tests",
-          "- `rails_analyze_feature(feature:\"auth\")` — schema + models + controllers + routes for a feature",
-          "- `rails_get_design_system` — color palette, components, canonical page examples",
-          "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_search_code`",
-          "- `rails_get_edit_context(file:\"path\", near:\"keyword\")` — surgical edit context with line numbers",
-          "- `rails_validate(files:[\"path\"])` — validate Ruby, ERB, JS syntax in one call",
-          "- `rails_security_scan` — Brakeman security analysis",
-          "- `rails_get_concern(name:\"Searchable\")` — concern methods and includers",
-          "- `rails_get_callbacks(model:\"User\")` — model callbacks in execution order",
-          "- `rails_get_helper_methods` — app + framework helpers",
-          "- `rails_get_service_pattern` — service object patterns and interfaces",
-          "- `rails_get_job_pattern` — background job patterns and schedules",
-          "- `rails_get_env` — environment variables and credentials keys",
-          "- `rails_get_partial_interface(path:\"shared/_form\")` — partial locals contract",
-          "- `rails_get_turbo_map` — Turbo Streams/Frames wiring",
-          "- `rails_get_context(model:\"User\")` — composite cross-layer context",
+          "## 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",
           "",
-          "After editing: use rails_validate to check syntax. Do NOT re-read files to verify."
+          "## 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:[...])` |",
+          "",
+          "## 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"
         ]
 
         lines.join("\n")