rails-ai-context 4.6.0 → 4.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a6993d2929f87b6f9c29dffd5f16124a1d3ccb15ac3f8ba8f100364bf0feb06
-  data.tar.gz: '08c5fe8f51d126c1f7cc52ca9cc8ca0dc2edf5d1dba5f569b8ec5afaeecbb0b4'
+  metadata.gz: c780366dc085c17be730aded4bbe8548b0e5e71c5c810caed96104a9379363fa
+  data.tar.gz: f5c46207b643df1a7dc1c5563c1d9e932f772ce5e27eb1839d9f14ddde116bd0
 SHA512:
-  metadata.gz: 94ec45e9fd089ba075c1b1c2457bfbf6fc9f2fc9c6da31b2ccafc7e51e64ca9579a390e25b56816a0c1bf4023f3ecbf092124082d53681029dcea3a5446065f5
-  data.tar.gz: fbab834f047ab3ae3392501964b6e0de1c090af063872473df3e3b074a161536c306cf4afd51daf8e44df8f127ddbb94fd885b15f21610f0884e27159ae118e3
+  metadata.gz: 934c4d703203801494a8addde164c71e56119e5701dd454574b0362d2a6d68523b6f0830654ff81eaa1d36fac7eca457374960e4e9fe54731f32431fe23ea8a4
+  data.tar.gz: ca2bf9e27db44fb35b8d9bd984748b7fce1108a013ef7ea6ec5a01757c48187b6ce6985c529ee8bf4df7cc9abd59085da8c356b3c73052e5196b07cc9a9a3790

data/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [4.7.0] — 2026-04-05
+
+### Added
+- **Anti-Hallucination Protocol** — 6-rule verification section embedded in every generated context file (CLAUDE.md, AGENTS.md, .claude/rules/, .cursor/rules/, .github/instructions/, copilot-instructions.md). Targets specific AI failure modes: statistical priors overriding observed facts, pattern completion beating verification, inheritance blindness, empty-output-as-permission, stale-context-lies. Rules force AI to verify column/association/route/method/gem names before writing, mark assumptions with `[ASSUMPTION]` prefix, check inheritance chains, and re-query after writes. Enabled by default via new `config.anti_hallucination_rules` option (boolean, default: `true`). Set `false` to skip.
+
+### Changed
+- **Repositioning: ground truth, not token savings** — the gem's mission is now explicit about what it actually does: stop AI from guessing your Rails app. Token savings are a side-effect, not the product. Updated README headline, "What stops being wrong" section (replaces "Measured token savings"), gemspec summary/description, server.json MCP registry description, docs/GUIDE.md intro, and the tools guide embedded in every generated CLAUDE.md/AGENTS.md/.cursor/rules. The core pitch: AI queries your running app for real schema, real associations, real filters — and writes correct code on the first try instead of iterating through corrections.
+
 ## [4.6.0] — 2026-04-04
 
 ### Added

data/CLAUDE.md

@@ -63,11 +63,12 @@ structure to AI assistants via the Model Context Protocol (MCP).
 35. **YAML config** — `.rails-ai-context.yml` as alternative to initializer. Supports all config options except `custom_tools` (Ruby classes) and `excluded_concerns` (regex). Precedence: initializer > YAML > defaults.
 36. **Config auto-loading** — `Configuration.auto_load!` checks `configured_via_block?` flag. If initializer ran, YAML is skipped. Corrupted YAML degrades gracefully with a warning.
 37. **Three install paths** — In-Gemfile (`rails generate rails_ai_context:install`), Standalone (`rails-ai-context init`), Zero config (just run `rails-ai-context serve` with defaults). Users can switch between paths freely; `.mcp.json` command is updated on re-init/re-install.
+38. **Anti-Hallucination Protocol** — 6-rule verification section embedded in every generated context file (CLAUDE.md, AGENTS.md, .claude/rules/, .cursor/rules/, .github/instructions/). Targets AI failure modes: statistical priors overriding facts, pattern completion beating verification, stale context. Toggleable via `config.anti_hallucination_rules` (default: true). Rendered by `tools_anti_hallucination_section` in `tool_guide_helper.rb`, placed between intro and detail_guidance in both full and compact render methods.
 
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (1621 examples)
+bundle exec rspec           # Run specs (1627 examples)
 bundle exec rubocop         # Lint
 ```
 

data/README.md

@@ -35,12 +35,12 @@ You've seen it. Your AI:
 - **Uses the wrong association name** — `user.posts` when it's `user.articles`
 - **Generates tests that don't match your patterns** — factories when you use fixtures, or the reverse
 - **Adds a gem you already have** — or calls an API from one you don't
-- **Reads 2,000 lines of schema.rb** to answer a question about one table
 - **Misses `before_action` filters from parent controllers** — then wonders why auth fails
+- **Invents a method** that isn't in your codebase — then you spend 10 minutes finding out
 
 You catch it. You fix it. You re-prompt. It breaks something else.
 
-**That loop is the actual cost of AI coding — not the tokens, the corrections.**
+**The real cost of AI coding isn't the tokens — it's the correction loop.** Every guess is a round-trip: you catch it, you fix it, you re-prompt, and something adjacent breaks. This gem kills the guessing at its source.
 
 <br>
 
@@ -82,37 +82,41 @@ One call returns: definition + source code + every caller grouped by type + test
 
 <br>
 
-## Measured token savings
+## What stops being wrong
 
-Real numbers from a production Rails app:
+Real scenarios where AI goes sideways — and what it does instead with ground truth:
 
-| Task | Without | With | Saved |
-|:-----|--------:|-----:|------:|
-| Get one table's columns | 1,492 tokens | 335 tokens | **77%** |
-| Trace a method across codebase | 10,556 tokens | 256 tokens | **97%** |
-| Understand a model | 1,754 tokens | 588 tokens | **66%** |
-| Map Stimulus controllers | 9,886 tokens | 620 tokens | **94%** |
-| Routes for one controller | 373 tokens | 121 tokens | **68%** |
+| You ask AI to... | Without — AI guesses | With — AI verifies first |
+|:-----|:-----|:-----|
+| Add a `subscription_tier` column to users | Writes the migration, duplicates an existing column | Reads live schema, spots `subscription_status` already exists, asks before migrating |
+| Call `user.posts` in a controller | Uses the guess; runtime `NoMethodError` | Resolves the actual association (`user.articles`) from the model |
+| Write tests for a new model | Scaffolds with FactoryBot | Detects your fixture-based suite and matches it |
+| Fix a failing create action | Misses inherited `before_action :authenticate_user!` | Returns parent-controller filters inline with the action source |
+| Build a dashboard page | Invents Tailwind classes from memory | Returns your actual button/card/alert patterns, copy-paste ready |
+| Trace where `can_cook?` is used | Reads 6 files sequentially, still misses callers | Single call: definition + source + every caller + tests |
 
 <details>
-<summary><strong>How to reproduce these numbers yourself</strong></summary>
+<summary><strong>Verify it on your own app</strong></summary>
 
 <br>
 
+Run these before and after installing to see what changes in *your* codebase:
+
 ```bash
-# Schema: full file vs one table
-wc -c db/schema.rb
-rails 'ai:tool[schema]' table=users | wc -c
+# Schema: does AI know what columns exist?
+rails 'ai:tool[schema]' table=users
 
-# Trace: all files AI reads vs one call
-rails 'ai:tool[search_code]' pattern=your_method match_type=trace | wc -c
+# Trace: find every caller of a method across the codebase
+rails 'ai:tool[search_code]' pattern=your_method match_type=trace
+
+# Model: associations, scopes, callbacks, concerns — all resolved
+rails 'ai:tool[model_details]' model=User
 
-# Model: raw file + schema vs structured output
-wc -c app/models/user.rb db/schema.rb
-rails 'ai:tool[model_details]' model=User | wc -c
+# Controllers: action source + inherited filters + strong params in one shot
+rails 'ai:tool[controllers]' controller=UsersController action=create
 ```
 
-Divide bytes by 4 for rough token count. Bigger apps save more — tool output stays focused while raw files grow.
+Compare what AI outputs with and without these tools wired in. The difference is measured in *corrections avoided*, not bytes saved.
 
 </details>
 
@@ -230,7 +234,7 @@ rails 'ai:tool[stimulus]' controller=chart
 
 ## 39 Tools
 
-Every tool is **read-only** and returns structured, token-efficient context.
+Every tool is **read-only** and returns data verified against your actual app — not guesses, not training data.
 
 <details>
 <summary><strong>Search & Trace</strong></summary>
@@ -339,6 +343,28 @@ Every tool is **read-only** and returns structured, token-efficient context.
 
 <br>
 
+## Anti-Hallucination Protocol
+
+Every generated context file ships with **6 rules that force AI verification** before writing code. The protocol targets the exact cognitive failures that produce confident-wrong code: statistical priors overriding observed facts, pattern completion beating verification, stale context lies.
+
+<details>
+<summary><strong>The 6 rules (shown to AI in every CLAUDE.md / .cursor/rules / .github/instructions)</strong></summary>
+
+<br>
+
+1. **Verify before you write.** Never reference a column, association, route, helper, method, class, partial, or gem not verified in THIS project via a tool call in THIS turn. Never invent names that "sound right."
+2. **Mark every assumption.** If proceeding without verification, prefix with `[ASSUMPTION]`. Silent assumptions forbidden. "I'd need to check X first" is a preferred answer.
+3. **Training data describes average Rails. This app isn't average.** When something feels "obviously" standard Rails, query anyway. Check `rails_get_conventions` + `rails_get_gems` BEFORE scaffolding.
+4. **Check the inheritance chain before every edit.** Inherited `before_action` filters, concerns, includes, STI parents. Inheritance is never flat.
+5. **Empty tool output is information, not permission.** "0 callers found" signals investigation, not license to proceed on guesses.
+6. **Stale context lies. Re-query after writes.** Earlier tool output may be wrong after edits.
+
+Enabled by default. Disable with `config.anti_hallucination_rules = false` if you prefer your own rules.
+
+</details>
+
+<br>
+
 ## How it works
 
 ```
@@ -419,6 +445,7 @@ end
 | `preset` | `:full` | `:full` (33 introspectors) or `:standard` (19) |
 | `context_mode` | `:compact` | `:compact` (150 lines) or `:full` |
 | `generate_root_files` | `true` | Set `false` for split rules only |
+| `anti_hallucination_rules` | `true` | Embed 6-rule verification protocol in generated context files |
 | `cache_ttl` | `60` | Cache TTL in seconds |
 | `max_tool_response_chars` | `200_000` | Safety cap for tool responses |
 | `live_reload` | `:auto` | `:auto`, `true`, or `false` |

data/docs/GUIDE.md

@@ -2,6 +2,12 @@
 
 > Full documentation for [rails-ai-context](https://github.com/crisnahine/rails-ai-context).
 > For a quick overview, see the [README](../README.md).
+>
+> **Why this gem exists:** AI coding assistants guess your Rails app. They invent columns,
+> use wrong association names, miss inherited filters, and scaffold tests that don't match
+> your patterns. This gem turns your running app into the source of truth — so agents query
+> real schema, real associations, and real conventions on demand, and write correct code
+> on the first try.
 
 ---
 
@@ -1290,6 +1296,7 @@ end
 | `server_name` | String | `"rails-ai-context"` | MCP server name |
 | `server_version` | String | gem version | MCP server version |
 | `generate_root_files` | Boolean | `true` | Generate root files (CLAUDE.md, etc.) — set `false` for split rules only |
+| `anti_hallucination_rules` | Boolean | `true` | Embed 6-rule Anti-Hallucination Protocol in generated context files — set `false` to skip |
 | `max_file_size` | Integer | `5_000_000` | Per-file read limit for tools (5MB) |
 | `max_test_file_size` | Integer | `1_000_000` | Test file read limit (1MB) |
 | `max_schema_file_size` | Integer | `10_000_000` | schema.rb / structure.sql parse limit (10MB) |

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

@@ -187,6 +187,11 @@ module RailsAiContext
             # Whether to generate root files (CLAUDE.md, AGENTS.md, etc.)
             # Set false to only generate split rules (.claude/rules/, .cursor/rules/, etc.)
             # config.generate_root_files = true
+
+            # Anti-Hallucination Protocol: 6-rule verification section embedded in every
+            # generated context file. Forces AI to verify facts before writing code.
+            # Default: true. Set false to skip the protocol entirely.
+            # config.anti_hallucination_rules = true
         SECTION
         "Models & Filtering" => <<~SECTION,
             # ── Models & Filtering ────────────────────────────────────────────

data/lib/rails_ai_context/configuration.rb

@@ -13,6 +13,7 @@ module RailsAiContext
     # All YAML-supported keys (explicit allowlist for safety)
     YAML_KEYS = %i[
       ai_tools tool_mode preset context_mode generate_root_files claude_max_lines
+      anti_hallucination_rules
       server_name cache_ttl max_tool_response_chars
       live_reload live_reload_debounce auto_mount http_path http_bind http_port
       output_dir skip_tools excluded_models excluded_controllers
@@ -133,6 +134,11 @@ module RailsAiContext
     # When false, only generates split rule files (.claude/rules/, .cursor/rules/, etc.)
     attr_accessor :generate_root_files
 
+    # Whether to embed the Anti-Hallucination Protocol section in generated context files.
+    # Default: true. Set false to skip the 6-rule verification protocol in CLAUDE.md,
+    # AGENTS.md, .claude/rules/, .cursor/rules/, .github/instructions/.
+    attr_accessor :anti_hallucination_rules
+
     # File size limits (bytes) — increase for larger projects
     attr_accessor :max_file_size          # Per-file read limit for tools (default: 2MB)
     attr_accessor :max_test_file_size     # Test file read limit (default: 500KB)
@@ -231,6 +237,7 @@ module RailsAiContext
       @live_reload              = :auto
       @live_reload_debounce     = 1.5
       @generate_root_files      = true
+      @anti_hallucination_rules = true
       @max_file_size            = 5_000_000
       @max_test_file_size       = 1_000_000
       @max_schema_file_size     = 10_000_000

data/lib/rails_ai_context/serializers/compact_serializer_helper.rb

@@ -77,15 +77,8 @@ module RailsAiContext
           line += " (#{assoc_count}a, #{val_count}v)" if assoc_count > 0 || val_count > 0
           line += " — #{top_assocs}" if top_assocs && !top_assocs.empty?
           lines << line
-          scopes = (data[:scopes] || [])
-          constants = (data[:constants] || [])
-          if scopes.any? || constants.any?
-            extras = []
-            scope_names = scope_names(scopes)
-            extras << "scopes: #{scope_names.join(', ')}" if scopes.any?
-            constants.each { |c| extras << "#{c[:name]}: #{c[:values].join(', ')}" }
-            lines << "  #{extras.join(' | ')}"
-          end
+          extras = model_extras_line(data)
+          lines << extras if extras
         end
         lines << "- _...#{models.size - max_show} more (use `rails_get_model_details` tool)_" if models.size > max_show
         lines << ""
@@ -108,19 +101,6 @@ module RailsAiContext
         lines
       end
 
-      def render_conventions
-        conv = context[:conventions]
-        return [] unless conv.is_a?(Hash) && !conv[:error]
-
-        config_files = conv[:config_files] || []
-        return [] if config_files.empty?
-
-        lines = [ "## Key config files" ]
-        config_files.first(5).each { |f| lines << "- `#{f}`" }
-        lines << ""
-        lines
-      end
-
       def render_commands
         test_cmd = detect_test_command
         [

data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb

@@ -107,15 +107,8 @@ module RailsAiContext
           data = models[name]
           assocs = (data[:associations] || []).size
           lines << "- #{name} (#{assocs} associations)"
-          scopes = (data[:scopes] || [])
-          constants = (data[:constants] || [])
-          if scopes.any? || constants.any?
-            extras = []
-            scope_names = scope_names(scopes)
-            extras << "scopes: #{scope_names.join(', ')}" if scopes.any?
-            constants.each { |c| extras << "#{c[:name]}: #{c[:values].join(', ')}" }
-            lines << "  #{extras.join(' | ')}"
-          end
+          extras = model_extras_line(data)
+          lines << extras if extras
         end
 
         lines << "- ...#{models.size - 30} more" if models.size > 30
@@ -139,11 +132,7 @@ module RailsAiContext
           ""
         ]
 
-        controllers.keys.sort.first(25).each do |name|
-          info = controllers[name]
-          actions = info[:actions]&.size || 0
-          lines << "- #{name} (#{actions} actions)"
-        end
+        lines.concat(render_compact_controllers_list(controllers))
 
         lines.join("\n")
       end
@@ -163,16 +152,7 @@ module RailsAiContext
 
         lines.concat(render_design_system_full(context))
 
-        # Stimulus controllers
-        stim = context[:stimulus]
-        if stim.is_a?(Hash) && !stim[:error]
-          controllers = stim[:controllers] || []
-          if controllers.any?
-            names = controllers.map { |c| c[:name] || c[:file]&.gsub("_controller.js", "") }.compact.sort
-            lines << "" << "## Stimulus controllers"
-            lines << names.join(", ")
-          end
-        end
+        lines.concat(render_stimulus_section(context))
 
         lines.join("\n")
       end

data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb

@@ -120,15 +120,8 @@ module RailsAiContext
           data = models[name]
           assocs = (data[:associations] || []).size
           lines << "- #{name} (#{assocs} associations, table: #{data[:table_name] || '?'})"
-          scopes = (data[:scopes] || [])
-          constants = (data[:constants] || [])
-          if scopes.any? || constants.any?
-            extras = []
-            scope_names = scope_names(scopes)
-            extras << "scopes: #{scope_names.join(', ')}" if scopes.any?
-            constants.each { |c| extras << "#{c[:name]}: #{c[:values].join(', ')}" }
-            lines << "  #{extras.join(' | ')}"
-          end
+          extras = model_extras_line(data)
+          lines << extras if extras
         end
 
         lines << "- ...#{models.size - 30} more" if models.size > 30
@@ -156,13 +149,8 @@ module RailsAiContext
           ""
         ]
 
-        controllers.keys.sort.first(25).each do |name|
-          info = controllers[name]
-          action_count = info[:actions]&.size || 0
-          lines << "- #{name} (#{action_count} actions)"
-        end
+        lines.concat(render_compact_controllers_list(controllers))
 
-        lines << "- ...#{controllers.size - 25} more" if controllers.size > 25
         lines << ""
         lines << "Use `rails_get_controllers` MCP tool with controller:\"Name\" for full detail."
 
@@ -198,16 +186,7 @@ module RailsAiContext
           end
         rescue => e; $stderr.puts "[rails-ai-context] Serializer section skipped: #{e.message}"; end
 
-        # Stimulus controllers
-        stim = context[:stimulus]
-        if stim.is_a?(Hash) && !stim[:error]
-          controllers = stim[:controllers] || []
-          if controllers.any?
-            names = controllers.map { |c| c[:name] || c[:file]&.gsub("_controller.js", "") }.compact.sort
-            lines << "" << "## Stimulus controllers"
-            lines << names.join(", ")
-          end
-        end
+        lines.concat(render_stimulus_section(context))
 
         lines.join("\n")
       end

data/lib/rails_ai_context/serializers/opencode_rules_serializer.rb

@@ -56,15 +56,8 @@ module RailsAiContext
           line += " — #{assocs}" unless assocs.empty?
           line += " [#{vals}v]" if vals > 0
           lines << line
-          scopes = (data[:scopes] || [])
-          constants = (data[:constants] || [])
-          if scopes.any? || constants.any?
-            extras = []
-            scope_names = scope_names(scopes)
-            extras << "scopes: #{scope_names.join(', ')}" if scopes.any?
-            constants.each { |c| extras << "#{c[:name]}: #{c[:values].join(', ')}" }
-            lines << "  #{extras.join(' | ')}"
-          end
+          extras = model_extras_line(data)
+          lines << extras if extras
         end
 
         lines << "- _...#{models.size - 30} more_" if models.size > 30

data/lib/rails_ai_context/serializers/stack_overview_helper.rb

@@ -113,6 +113,43 @@ module RailsAiContext
         scopes.map { |s| s.is_a?(Hash) ? s[:name] : s }
       end
 
+      # Render a compact controllers listing: "- Name (N actions)" + "...X more".
+      # Shared by cursor_rules and copilot_instructions serializers.
+      def render_compact_controllers_list(controllers_hash, limit: 25)
+        lines = []
+        controllers_hash.keys.sort.first(limit).each do |name|
+          info = controllers_hash[name]
+          action_count = info[:actions]&.size || 0
+          lines << "- #{name} (#{action_count} actions)"
+        end
+        lines << "- ...#{controllers_hash.size - limit} more" if controllers_hash.size > limit
+        lines
+      end
+
+      # Render a Stimulus controllers section from context[:stimulus].
+      # Returns lines or [] if no Stimulus controllers.
+      def render_stimulus_section(ctx = context)
+        stim = ctx[:stimulus]
+        return [] unless stim.is_a?(Hash) && !stim[:error]
+        controllers = stim[:controllers] || []
+        return [] if controllers.empty?
+        names = controllers.map { |c| c[:name] || c[:file]&.gsub("_controller.js", "") }.compact.sort
+        [ "", "## Stimulus controllers", names.join(", ") ]
+      end
+
+      # Render scopes and constants as a one-line extras summary for a model entry.
+      # Returns "  scopes: a, b | STATUS: draft, active" or nil if no extras exist.
+      # Shared by cursor_rules, opencode_rules, copilot_instructions, compact_serializer_helper.
+      def model_extras_line(data)
+        scopes = data[:scopes] || []
+        constants = data[:constants] || []
+        return nil unless scopes.any? || constants.any?
+        extras = []
+        extras << "scopes: #{scope_names(scopes).join(', ')}" if scopes.any?
+        constants.each { |c| extras << "#{c[:name]}: #{c[:values].join(', ')}" }
+        "  #{extras.join(' | ')}"
+      end
+
       # Extract notable gems with triple-fallback for varying introspector output shapes.
       def notable_gems_list(gems_data)
         return [] unless gems_data.is_a?(Hash) && !gems_data[:error]

data/lib/rails_ai_context/serializers/tool_guide_helper.rb

@@ -32,13 +32,15 @@ module RailsAiContext
         when :cli
           [
             "This project has 39 introspection tools. **MANDATORY — use these instead of reading files.**",
-            "They return only relevant, structured data and save tokens. Read files ONLY when you are about to Edit them.",
+            "They return ground truth from the running app: real schema, real associations, real filters — not guesses.",
+            "Read files ONLY when you are about to Edit them.",
             ""
           ]
         else
           [
             "This project has 39 MCP tools via `rails ai:serve` (configured in `.mcp.json`).",
-            "**MANDATORY — use these instead of reading files.** They return structured data and save tokens.",
+            "**MANDATORY — use these instead of reading files.** They return ground truth from the running app:",
+            "real schema, real associations, real filters — not guesses from file reads.",
             "Read files ONLY when you are about to Edit them.",
             "If MCP tools are not connected, use CLI fallback: `#{cli_cmd("TOOL_NAME", "param=value")}`",
             ""
@@ -46,6 +48,26 @@ module RailsAiContext
         end
       end
 
+      def tools_anti_hallucination_section
+        return [] unless RailsAiContext.configuration.anti_hallucination_rules
+
+        [
+          "### Anti-Hallucination Protocol — Verify Before You Write",
+          "",
+          "AI assistants produce confident-wrong code when statistical priors from training",
+          "data override observed facts in the current project. These 6 rules force",
+          "verification at the exact moments hallucination is most likely.",
+          "",
+          "1. **Verify before you write.** Never reference a column, association, route, helper, method, class, partial, or gem you have NOT verified in THIS project via a tool call in THIS turn. If it's not verified here, verify it now. Never invent names that \"sound right.\"",
+          "2. **Mark every assumption.** If you must proceed without verification, prefix the relevant output with `[ASSUMPTION]` and state what you're assuming and why. Silent assumptions are forbidden. \"I'd need to check X first\" is a valid and preferred answer.",
+          "3. **Training data describes average Rails. This app isn't average.** When something feels \"obviously\" like standard Rails, query anyway. Factories vs fixtures? Pundit vs CanCan? Devise vs has_secure_password? Check `rails_get_conventions` and `rails_get_gems` BEFORE scaffolding anything.",
+          "4. **Check the inheritance chain before every edit.** Before writing a controller action: inherited `before_action` filters and ancestor classes. Before writing a model method: concerns, includes, STI parents. Inheritance is never flat.",
+          "5. **Empty tool output is information, not permission.** \"0 callers found,\" \"no validations,\" or a missing model is a signal to investigate or confirm with the user — not a license to proceed on guesses. Follow `_Next:` hints.",
+          "6. **Stale context lies. Re-query after writes.** After any edit, tool output from earlier in this turn may be wrong. Re-query the affected tool before the next write.",
+          ""
+        ]
+      end
+
       def tools_detail_guidance
         detail_param = tool_mode == :cli ? "detail=summary" : "detail:\"summary\""
         [
@@ -131,7 +153,7 @@ module RailsAiContext
           "- **Don't call tools without a target** — `get_model_details()` without `model:` returns a paginated list, not an error. Always specify what you want.",
           "- **Don't skip validation** — run `#{validate_tool}` after EVERY edit. It catches syntax errors AND Rails-specific issues (missing partials, bad column refs).",
           "- **Don't ignore cross-references** — tool responses include `_Next:` hints suggesting the best follow-up call. Follow them.",
-          "- **Don't call `detail:\"full\"` first** — start with `summary` to find your target, then drill in. Full responses waste tokens.",
+          "- **Don't call `detail:\"full\"` first** — start with `summary` to find your target, then drill in. Full responses bury the signal.",
           ""
         ]
       end
@@ -166,108 +188,69 @@ module RailsAiContext
         end
       end
 
-      def tools_table # rubocop:disable Metrics/MethodLength
+      def tools_table
         lines = [ "### All 39 Tools", "" ]
-
-        if tool_mode == :cli
-          lines.concat(tools_table_cli)
-        else
-          lines.concat(tools_table_mcp_and_cli)
-        end
-
+        lines.concat(build_tools_table(include_mcp: tool_mode != :cli))
         lines
       end
 
-      def tools_table_mcp_and_cli # rubocop:disable Metrics/MethodLength
-        [
-          "| MCP | CLI | What it does |",
-          "|-----|-----|-------------|",
-          "| `rails_get_context(model:\"X\")` | `#{cli_cmd("context", "model=X")}` | **START HERE** — schema + model + controller + routes + views in one call |",
-          "| `rails_analyze_feature(feature:\"X\")` | `#{cli_cmd("analyze_feature", "feature=X")}` | Full-stack: models + controllers + routes + services + jobs + views + tests |",
-          "| `rails_search_code(pattern:\"X\", match_type:\"trace\")` | `#{cli_cmd("search_code", "pattern=X match_type=trace")}` | Search + trace: definition, source, callers, test coverage. Also: `match_type:\"any\"` for regex search |",
-          "| `rails_get_controllers(controller:\"X\", action:\"Y\")` | `#{cli_cmd("controllers", "controller=X action=Y")}` | Action source + inherited filters + render map + private methods |",
-          "| `rails_validate(files:[...], level:\"rails\")` | `#{cli_cmd("validate", "files=a.rb,b.rb level=rails")}` | Syntax + semantic validation (run after EVERY edit) |",
-          "| `rails_get_schema(table:\"X\")` | `#{cli_cmd("schema", "table=X")}` | Columns with [indexed]/[unique]/[encrypted]/[default] hints |",
-          "| `rails_get_model_details(model:\"X\")` | `#{cli_cmd("model_details", "model=X")}` | Associations, validations, scopes, enums, macros, delegations |",
-          "| `rails_get_routes(controller:\"X\")` | `#{cli_cmd("routes", "controller=X")}` | Routes with code-ready helpers and controller filters inline |",
-          "| `rails_get_view(controller:\"X\")` | `#{cli_cmd("view", "controller=X")}` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals |",
-          "| `rails_get_design_system` | `#{cli_cmd("design_system")}` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards |",
-          "| `rails_get_stimulus(controller:\"X\")` | `#{cli_cmd("stimulus", "controller=X")}` | Targets, values, actions + HTML data-attributes + view lookup |",
-          "| `rails_get_test_info(model:\"X\")` | `#{cli_cmd("test_info", "model=X")}` | Tests + fixture contents + test template |",
-          "| `rails_get_concern(name:\"X\", detail:\"full\")` | `#{cli_cmd("concern", "name=X detail=full")}` | Concern methods with source + which models include it |",
-          "| `rails_get_callbacks(model:\"X\")` | `#{cli_cmd("callbacks", "model=X")}` | Callbacks in Rails execution order with source |",
-          "| `rails_get_edit_context(file:\"X\", near:\"Y\")` | `#{cli_cmd("edit_context", "file=X near=Y")}` | Code around a match with class/method context |",
-          "| `rails_get_service_pattern` | `#{cli_cmd("service_pattern")}` | Service objects: interface, dependencies, side effects, callers |",
-          "| `rails_get_job_pattern` | `#{cli_cmd("job_pattern")}` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
-          "| `rails_get_env` | `#{cli_cmd("env")}` | Environment variables + credentials keys (not values) |",
-          "| `rails_get_partial_interface(partial:\"X\")` | `#{cli_cmd("partial_interface", "partial=X")}` | Partial locals contract: what to pass + usage examples |",
-          "| `rails_get_turbo_map` | `#{cli_cmd("turbo_map")}` | Turbo Stream/Frame wiring + mismatch warnings |",
-          "| `rails_get_helper_methods` | `#{cli_cmd("helper_methods")}` | App + framework helpers with view cross-references |",
-          "| `rails_get_config` | `#{cli_cmd("config")}` | Database adapter, auth, assets, cache, queue, Action Cable |",
-          "| `rails_get_gems` | `#{cli_cmd("gems")}` | Notable gems with versions, categories, config file locations |",
-          "| `rails_get_conventions` | `#{cli_cmd("conventions")}` | App patterns: auth checks, flash messages, test patterns |",
-          "| `rails_security_scan` | `#{cli_cmd("security_scan")}` | Brakeman static analysis: SQL injection, XSS, mass assignment |",
-          "| `rails_get_component_catalog(component:\"X\")` | `#{cli_cmd("component_catalog", "component=X")}` | ViewComponent/Phlex: props, slots, previews, usage |",
-          "| `rails_performance_check(model:\"X\")` | `#{cli_cmd("performance_check", "model=X")}` | N+1 risks, missing indexes, Model.all anti-patterns |",
-          "| `rails_dependency_graph(model:\"X\")` | `#{cli_cmd("dependency_graph", "model=X")}` | Model association graph as Mermaid diagram |",
-          "| `rails_migration_advisor(action:\"X\", table:\"Y\")` | `#{cli_cmd("migration_advisor", "action=X table=Y")}` | Generate migration code, flag irreversible ops |",
-          "| `rails_get_frontend_stack` | `#{cli_cmd("frontend_stack")}` | React/Vue/Svelte/Angular, Inertia, TypeScript, package manager |",
-          "| `rails_search_docs(query:\"X\")` | `#{cli_cmd("search_docs", "query=X")}` | Bundled topic index with weighted keyword search, on-demand GitHub fetch |",
-          "| `rails_query(sql:\"X\")` | `#{cli_cmd("query", "sql=X")}` | Safe read-only SQL queries with timeout, row limit, column redaction |",
-          "| `rails_read_logs(level:\"X\")` | `#{cli_cmd("read_logs", "level=X")}` | Reverse file tail with level filtering and sensitive data redaction |",
-          "| `rails_generate_test(model:\"X\")` | `#{cli_cmd("generate_test", "model=X")}` | Generate test scaffolding matching project patterns (framework, factories, style) |",
-          "| `rails_diagnose(error:\"X\")` | `#{cli_cmd("diagnose", "error=\"X\"")}` | One-call error diagnosis: context + git changes + logs + fix suggestions |",
-          "| `rails_review_changes(ref:\"main\")` | `#{cli_cmd("review_changes", "ref=main")}` | PR/commit review: file context + warnings (missing indexes, removed validations) |",
-          "| `rails_onboard(detail:\"standard\")` | `#{cli_cmd("onboard", "detail=standard")}` | Narrative app walkthrough for new developers or AI agents |",
-          "| `rails_runtime_info(detail:\"standard\")` | `#{cli_cmd("runtime_info", "detail=standard")}` | Live runtime: DB pool, table sizes, cache stats, job queues, pending migrations |",
-          "| `rails_session_context(action:\"status\")` | `#{cli_cmd("session_context", "action=status")}` | Track what you've already queried, avoid redundant calls |"
-        ]
-      end
+      # Single source of truth for the tools table.
+      # Each row is [mcp_call, cli_name, cli_args, description].
+      # Set include_mcp: false for CLI-only 2-column table.
+      TOOL_ROWS = [
+        [ 'rails_get_context(model:"X")', "context", "model=X", "**START HERE** — schema + model + controller + routes + views in one call" ],
+        [ 'rails_analyze_feature(feature:"X")', "analyze_feature", "feature=X", "Full-stack: models + controllers + routes + services + jobs + views + tests" ],
+        [ 'rails_search_code(pattern:"X", match_type:"trace")', "search_code", "pattern=X match_type=trace", 'Search + trace: definition, source, callers, test coverage. Also: `match_type:"any"` for regex search' ],
+        [ 'rails_get_controllers(controller:"X", action:"Y")', "controllers", "controller=X action=Y", "Action source + inherited filters + render map + private methods" ],
+        [ 'rails_validate(files:[...], level:"rails")', "validate", "files=a.rb,b.rb level=rails", "Syntax + semantic validation (run after EVERY edit)" ],
+        [ 'rails_get_schema(table:"X")', "schema", "table=X", "Columns with [indexed]/[unique]/[encrypted]/[default] hints" ],
+        [ 'rails_get_model_details(model:"X")', "model_details", "model=X", "Associations, validations, scopes, enums, macros, delegations" ],
+        [ 'rails_get_routes(controller:"X")', "routes", "controller=X", "Routes with code-ready helpers and controller filters inline" ],
+        [ 'rails_get_view(controller:"X")', "view", "controller=X", "Templates with ivars, Turbo wiring, Stimulus refs, partial locals" ],
+        [ "rails_get_design_system", "design_system", nil, "Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards" ],
+        [ 'rails_get_stimulus(controller:"X")', "stimulus", "controller=X", "Targets, values, actions + HTML data-attributes + view lookup" ],
+        [ 'rails_get_test_info(model:"X")', "test_info", "model=X", "Tests + fixture contents + test template" ],
+        [ 'rails_get_concern(name:"X", detail:"full")', "concern", "name=X detail=full", "Concern methods with source + which models include it" ],
+        [ 'rails_get_callbacks(model:"X")', "callbacks", "model=X", "Callbacks in Rails execution order with source" ],
+        [ 'rails_get_edit_context(file:"X", near:"Y")', "edit_context", "file=X near=Y", "Code around a match with class/method context" ],
+        [ "rails_get_service_pattern", "service_pattern", nil, "Service objects: interface, dependencies, side effects, callers" ],
+        [ "rails_get_job_pattern", "job_pattern", nil, "Jobs: queue, retries, guard clauses, broadcasts, schedules" ],
+        [ "rails_get_env", "env", nil, "Environment variables + credentials keys (not values)" ],
+        [ 'rails_get_partial_interface(partial:"X")', "partial_interface", "partial=X", "Partial locals contract: what to pass + usage examples" ],
+        [ "rails_get_turbo_map", "turbo_map", nil, "Turbo Stream/Frame wiring + mismatch warnings" ],
+        [ "rails_get_helper_methods", "helper_methods", nil, "App + framework helpers with view cross-references" ],
+        [ "rails_get_config", "config", nil, "Database adapter, auth, assets, cache, queue, Action Cable" ],
+        [ "rails_get_gems", "gems", nil, "Notable gems with versions, categories, config file locations" ],
+        [ "rails_get_conventions", "conventions", nil, "App patterns: auth checks, flash messages, test patterns" ],
+        [ "rails_security_scan", "security_scan", nil, "Brakeman static analysis: SQL injection, XSS, mass assignment" ],
+        [ 'rails_get_component_catalog(component:"X")', "component_catalog", "component=X", "ViewComponent/Phlex: props, slots, previews, usage" ],
+        [ 'rails_performance_check(model:"X")', "performance_check", "model=X", "N+1 risks, missing indexes, Model.all anti-patterns" ],
+        [ 'rails_dependency_graph(model:"X")', "dependency_graph", "model=X", "Model association graph as Mermaid diagram" ],
+        [ 'rails_migration_advisor(action:"X", table:"Y")', "migration_advisor", "action=X table=Y", "Generate migration code, flag irreversible ops" ],
+        [ "rails_get_frontend_stack", "frontend_stack", nil, "React/Vue/Svelte/Angular, Inertia, TypeScript, package manager" ],
+        [ 'rails_search_docs(query:"X")', "search_docs", "query=X", "Bundled topic index with weighted keyword search, on-demand GitHub fetch" ],
+        [ 'rails_query(sql:"X")', "query", "sql=X", "Safe read-only SQL queries with timeout, row limit, column redaction" ],
+        [ 'rails_read_logs(level:"X")', "read_logs", "level=X", "Reverse file tail with level filtering and sensitive data redaction" ],
+        [ 'rails_generate_test(model:"X")', "generate_test", "model=X", "Generate test scaffolding matching project patterns (framework, factories, style)" ],
+        [ 'rails_diagnose(error:"X")', "diagnose", 'error="X"', "One-call error diagnosis: context + git changes + logs + fix suggestions" ],
+        [ 'rails_review_changes(ref:"main")', "review_changes", "ref=main", "PR/commit review: file context + warnings (missing indexes, removed validations)" ],
+        [ 'rails_onboard(detail:"standard")', "onboard", "detail=standard", "Narrative app walkthrough for new developers or AI agents" ],
+        [ 'rails_runtime_info(detail:"standard")', "runtime_info", "detail=standard", "Live runtime: DB pool, table sizes, cache stats, job queues, pending migrations" ],
+        [ 'rails_session_context(action:"status")', "session_context", "action=status", "Track what you've already queried, avoid redundant calls" ]
+      ].freeze
 
-      def tools_table_cli # rubocop:disable Metrics/MethodLength
-        [
-          "| CLI | What it does |",
-          "|-----|-------------|",
-          "| `#{cli_cmd("context", "model=X")}` | **START HERE** — schema + model + controller + routes + views in one call |",
-          "| `#{cli_cmd("analyze_feature", "feature=X")}` | Full-stack: models + controllers + routes + services + jobs + views + tests |",
-          "| `#{cli_cmd("search_code", "pattern=X match_type=trace")}` | Search + trace: definition, source, callers, test coverage. Also: `match_type=any` for regex search |",
-          "| `#{cli_cmd("controllers", "controller=X action=Y")}` | Action source + inherited filters + render map + private methods |",
-          "| `#{cli_cmd("validate", "files=a.rb,b.rb level=rails")}` | Syntax + semantic validation (run after EVERY edit) |",
-          "| `#{cli_cmd("schema", "table=X")}` | Columns with [indexed]/[unique]/[encrypted]/[default] hints |",
-          "| `#{cli_cmd("model_details", "model=X")}` | Associations, validations, scopes, enums, macros, delegations |",
-          "| `#{cli_cmd("routes", "controller=X")}` | Routes with code-ready helpers and controller filters inline |",
-          "| `#{cli_cmd("view", "controller=X")}` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals |",
-          "| `#{cli_cmd("design_system")}` | Canonical HTML/ERB copy-paste patterns for buttons, inputs, cards |",
-          "| `#{cli_cmd("stimulus", "controller=X")}` | Targets, values, actions + HTML data-attributes + view lookup |",
-          "| `#{cli_cmd("test_info", "model=X")}` | Tests + fixture contents + test template |",
-          "| `#{cli_cmd("concern", "name=X detail=full")}` | Concern methods with source + which models include it |",
-          "| `#{cli_cmd("callbacks", "model=X")}` | Callbacks in Rails execution order with source |",
-          "| `#{cli_cmd("edit_context", "file=X near=Y")}` | Code around a match with class/method context |",
-          "| `#{cli_cmd("service_pattern")}` | Service objects: interface, dependencies, side effects, callers |",
-          "| `#{cli_cmd("job_pattern")}` | Jobs: queue, retries, guard clauses, broadcasts, schedules |",
-          "| `#{cli_cmd("env")}` | Environment variables + credentials keys (not values) |",
-          "| `#{cli_cmd("partial_interface", "partial=X")}` | Partial locals contract: what to pass + usage examples |",
-          "| `#{cli_cmd("turbo_map")}` | Turbo Stream/Frame wiring + mismatch warnings |",
-          "| `#{cli_cmd("helper_methods")}` | App + framework helpers with view cross-references |",
-          "| `#{cli_cmd("config")}` | Database adapter, auth, assets, cache, queue, Action Cable |",
-          "| `#{cli_cmd("gems")}` | Notable gems with versions, categories, config file locations |",
-          "| `#{cli_cmd("conventions")}` | App patterns: auth checks, flash messages, test patterns |",
-          "| `#{cli_cmd("security_scan")}` | Brakeman static analysis: SQL injection, XSS, mass assignment |",
-          "| `#{cli_cmd("component_catalog", "component=X")}` | ViewComponent/Phlex: props, slots, previews, usage |",
-          "| `#{cli_cmd("performance_check", "model=X")}` | N+1 risks, missing indexes, Model.all anti-patterns |",
-          "| `#{cli_cmd("dependency_graph", "model=X")}` | Model association graph as Mermaid diagram |",
-          "| `#{cli_cmd("migration_advisor", "action=X table=Y")}` | Generate migration code, flag irreversible ops |",
-          "| `#{cli_cmd("frontend_stack")}` | React/Vue/Svelte/Angular, Inertia, TypeScript, package manager |",
-          "| `#{cli_cmd("search_docs", "query=X")}` | Bundled topic index with weighted keyword search, on-demand GitHub fetch |",
-          "| `#{cli_cmd("query", "sql=X")}` | Safe read-only SQL queries with timeout, row limit, column redaction |",
-          "| `#{cli_cmd("read_logs", "level=X")}` | Reverse file tail with level filtering and sensitive data redaction |",
-          "| `#{cli_cmd("generate_test", "model=X")}` | Generate test scaffolding matching project patterns (framework, factories, style) |",
-          "| `#{cli_cmd("diagnose", "error=\"X\"")}` | One-call error diagnosis: context + git changes + logs + fix suggestions |",
-          "| `#{cli_cmd("review_changes", "ref=main")}` | PR/commit review: file context + warnings (missing indexes, removed validations) |",
-          "| `#{cli_cmd("onboard", "detail=standard")}` | Narrative app walkthrough for new developers or AI agents |",
-          "| `#{cli_cmd("runtime_info", "detail=standard")}` | Live runtime: DB pool, table sizes, cache stats, job queues, pending migrations |",
-          "| `#{cli_cmd("session_context", "action=status")}` | Track what you've already queried, avoid redundant calls |"
-        ]
+      def build_tools_table(include_mcp:)
+        # For CLI-only tables, `match_type=any` uses `=` (not `:`), so we tweak description.
+        rows = TOOL_ROWS.map do |mcp_call, cli_name, cli_args, desc|
+          cli = cli_cmd(cli_name, cli_args)
+          if include_mcp
+            "| `#{mcp_call}` | `#{cli}` | #{desc} |"
+          else
+            "| `#{cli}` | #{desc.gsub('match_type:"any"', "match_type=any")} |"
+          end
+        end
+        header = include_mcp ? [ "| MCP | CLI | What it does |", "|-----|-----|-------------|" ] : [ "| CLI | What it does |", "|-----|-------------|" ]
+        header + rows
       end
 
       # Full tool guide section — used by split rules files (.claude/rules/, .cursor/rules/, etc.)
@@ -276,6 +259,7 @@ module RailsAiContext
         lines << tools_header
         lines << ""
         lines.concat(tools_intro)
+        lines.concat(tools_anti_hallucination_section)
         lines.concat(tools_detail_guidance)
         lines.concat(tools_power_tool_section)
         lines.concat(tools_workflow_section)
@@ -292,6 +276,7 @@ module RailsAiContext
         lines << tools_header
         lines << ""
         lines.concat(tools_intro)
+        lines.concat(tools_anti_hallucination_section)
         lines.concat(tools_power_tool_section)
         lines.concat(tools_workflow_section)
         lines.concat(tools_antipatterns_section)

data/lib/rails_ai_context/tools/base_tool.rb

@@ -153,6 +153,60 @@ module RailsAiContext
           SHARED_CACHE[:fingerprint] || "none"
         end
 
+        # Case-insensitive fuzzy key lookup for hashes keyed by class/table names.
+        # Tries exact, underscore, singularize, and classify variants. Returns matching key or nil.
+        # Shared by get_model_details, get_callbacks, get_context, generate_test, dependency_graph.
+        def fuzzy_find_key(keys, query)
+          return nil if query.nil? || keys.nil? || keys.empty?
+          q = query.to_s.strip
+          return nil if q.empty?
+          q_down = q.downcase
+          q_under = q.underscore.downcase
+
+          keys.find { |k| k.to_s.downcase == q_down } ||
+            keys.find { |k| k.to_s.underscore.downcase == q_under } ||
+            keys.find { |k| k.to_s.downcase == q.singularize.downcase } ||
+            keys.find { |k| k.to_s.downcase == q.classify.downcase }
+        end
+
+        # Extract method source from a source string via indentation-based matching.
+        # Returns { code:, start_line:, end_line: } or nil. Shared by get_callbacks, get_concern.
+        def extract_method_source_from_string(source, method_name)
+          source_lines = source.lines
+          escaped = Regexp.escape(method_name.to_s)
+          # ? and ! ARE word boundaries, so skip \b after them
+          pattern = if method_name.to_s.end_with?("?", "!")
+            /\A\s*def\s+#{escaped}/
+          else
+            /\A\s*def\s+#{escaped}\b/
+          end
+          start_idx = source_lines.index { |l| l.match?(pattern) }
+          return nil unless start_idx
+
+          def_indent = source_lines[start_idx][/\A\s*/].length
+          result = []
+          end_idx = start_idx
+
+          source_lines[start_idx..].each_with_index do |line, i|
+            result << line.rstrip
+            end_idx = start_idx + i
+            break if i > 0 && line.match?(/\A\s{#{def_indent}}end\b/)
+          end
+
+          { code: result.join("\n"), start_line: start_idx + 1, end_line: end_idx + 1 }
+        rescue => e
+          $stderr.puts "[rails-ai-context] extract_method_source_from_string failed: #{e.message}" if ENV["DEBUG"]
+          nil
+        end
+
+        # Extract method source from a file path. Reads file safely. Returns hash or nil.
+        def extract_method_source_from_file(path, method_name)
+          return nil unless File.exist?(path)
+          return nil if File.size(path) > RailsAiContext.configuration.max_file_size
+          source = RailsAiContext::SafeFile.read(path) || ""
+          extract_method_source_from_string(source, method_name)
+        end
+
         # Store call params for the current tool invocation (thread-safe)
         def set_call_params(**params)
           Thread.current[:rails_ai_context_call_params] = params.reject { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }

data/lib/rails_ai_context/tools/dependency_graph.rb

@@ -148,8 +148,7 @@ module RailsAiContext
         end
 
         def find_model_key(query, keys)
-          keys.find { |k| k.downcase == query.downcase } ||
-            keys.find { |k| k.underscore.downcase == query.downcase }
+          fuzzy_find_key(keys, query)
         end
 
         def extract_subgraph(graph, center, depth)

data/lib/rails_ai_context/tools/generate_test.rb

@@ -99,8 +99,7 @@ module RailsAiContext
 
         def generate_model_test(model_name, framework, patterns, tests_data)
           models = cached_context[:models] || {}
-          key = models.keys.find { |k| k.downcase == model_name.downcase } ||
-                models.keys.find { |k| k.underscore == model_name.underscore }
+          key = fuzzy_find_key(models.keys, model_name)
           unless key
             return not_found_response("Model", model_name, models.keys.sort,
               recovery_tool: "Call rails_get_model_details(detail:\"summary\") to see all models")

data/lib/rails_ai_context/tools/get_callbacks.rb

@@ -57,7 +57,7 @@ module RailsAiContext
 
         # Specific model — show callbacks in execution order
         if model
-          key = models.keys.find { |k| k.downcase == model.downcase } || model
+          key = fuzzy_find_key(models.keys, model) || model
           data = models[key]
           unless data
             return not_found_response("Model", model, models.keys.sort,
@@ -122,7 +122,7 @@ module RailsAiContext
             concern_callbacks.each do |concern_name, info|
               lines << "### #{concern_name}"
               info[:callbacks].each do |cb|
-                source = extract_method_source(info[:path], cb[:method_name])
+                source = extract_method_source_from_file(info[:path], cb[:method_name])
                 lines << "- #{cb[:declaration]}"
                 if source
                   lines << "```ruby"
@@ -227,39 +227,7 @@ module RailsAiContext
 
       private_class_method def self.extract_callback_source(model_name, method_name)
         path = Rails.root.join("app", "models", "#{model_name.underscore}.rb")
-        extract_method_source(path, method_name)
-      end
-
-      private_class_method def self.extract_method_source(path, method_name)
-        return nil unless File.exist?(path)
-        return nil if File.size(path) > RailsAiContext.configuration.max_file_size
-
-        source_lines = (RailsAiContext::SafeFile.read(path) || "").lines
-        method_str = method_name.to_s
-
-        # Find method definition (could be public or private)
-        start_idx = source_lines.index { |l| l.match?(/\A\s*def\s+#{Regexp.escape(method_str)}\b/) }
-        return nil unless start_idx
-
-        # Use indentation-based matching
-        def_indent = source_lines[start_idx][/\A\s*/].length
-        result = []
-        end_idx = start_idx
-
-        source_lines[start_idx..].each_with_index do |line, i|
-          result << line.rstrip
-          end_idx = start_idx + i
-          break if i > 0 && line.match?(/\A\s{#{def_indent}}end\b/)
-        end
-
-        {
-          code: result.join("\n"),
-          start_line: start_idx + 1,
-          end_line: end_idx + 1
-        }
-      rescue => e
-        $stderr.puts "[rails-ai-context] extract_method_source failed: #{e.message}" if ENV["DEBUG"]
-        nil
+        extract_method_source_from_file(path, method_name)
       end
 
       private_class_method def self.find_concern_callbacks(model_name, data)

data/lib/rails_ai_context/tools/get_concern.rb

@@ -130,11 +130,11 @@ module RailsAiContext
           if detail == "full"
             public_methods.each do |m|
               method_name = m.to_s.split("(").first
-              method_source = extract_method_source(source, method_name)
+              method_source = extract_method_source_from_string(source, method_name)
               if method_source
                 lines << "### #{m}"
                 lines << "```ruby"
-                lines << method_source
+                lines << method_source[:code]
                 lines << "```"
                 lines << ""
               else
@@ -154,11 +154,11 @@ module RailsAiContext
             class_methods.each do |m|
               method_name = m.to_s.split("(").first
               # Try both `def method_name` and `def self.method_name`
-              method_source = extract_method_source(source, method_name) || extract_method_source(source, "self.#{method_name}")
+              method_source = extract_method_source_from_string(source, method_name) || extract_method_source_from_string(source, "self.#{method_name}")
               if method_source
                 lines << "### #{m}"
                 lines << "```ruby"
-                lines << method_source
+                lines << method_source[:code]
                 lines << "```"
                 lines << ""
               else
@@ -388,33 +388,6 @@ module RailsAiContext
         []
       end
 
-      # Extract method source from raw source string using indentation-based matching
-      private_class_method def self.extract_method_source(source, method_name)
-        source_lines = source.lines
-        escaped = Regexp.escape(method_name.to_s)
-        # Don't use \b after ? or ! — they ARE word boundaries
-        pattern = if method_name.to_s.end_with?("?") || method_name.to_s.end_with?("!")
-          /\A\s*def\s+#{escaped}/
-        else
-          /\A\s*def\s+#{escaped}\b/
-        end
-        start_idx = source_lines.index { |l| l.match?(pattern) }
-        return nil unless start_idx
-
-        def_indent = source_lines[start_idx][/\A\s*/].length
-        result = []
-
-        source_lines[start_idx..].each_with_index do |line, i|
-          result << line.rstrip
-          break if i > 0 && line.match?(/\A\s{#{def_indent}}end\b/)
-        end
-
-        result.join("\n")
-      rescue => e
-        $stderr.puts "[rails-ai-context] extract_method_source failed: #{e.message}" if ENV["DEBUG"]
-        nil
-      end
-
       private_class_method def self.find_includers(concern_name, root, concern_type)
         includers = []
         search_dirs = []

data/lib/rails_ai_context/tools/get_context.rb

@@ -214,9 +214,7 @@ module RailsAiContext
         # Normalize: try as-is, then singularized, then classified
         ctx = cached_context
         models = ctx[:models] || {}
-        key = models.keys.find { |k| k.downcase == model_name.downcase } ||
-              models.keys.find { |k| k.downcase == model_name.singularize.downcase } ||
-              models.keys.find { |k| k.downcase == model_name.classify.downcase }
+        key = fuzzy_find_key(models.keys, model_name)
 
         resolved_name = key || model_name
 

data/lib/rails_ai_context/tools/get_model_details.rb

@@ -41,8 +41,7 @@ module RailsAiContext
         # Specific model — always full detail (strip whitespace for fuzzy input)
         if model
           model = model.strip
-          model_under = model.underscore
-          key = models.keys.find { |k| k.downcase == model.downcase || k.underscore == model_under } || model
+          key = fuzzy_find_key(models.keys, model) || model
           data = models[key]
           unless data
             return not_found_response("Model", model, models.keys.sort,

data/lib/rails_ai_context/tools/get_view.rb

@@ -246,13 +246,13 @@ module RailsAiContext
         text_response("# #{path}\n\n```erb\n#{content}\n```")
       end
 
-      # Strip inline SVG blocks to save tokens — they're visual noise for code understanding.
+      # Strip inline SVG blocks — they're visual noise that buries the signal AI needs.
       # Replaces <svg ...>...</svg> with a compact placeholder.
       private_class_method def self.strip_svg(content)
         content.gsub(/<svg\b[^>]*>.*?<\/svg>/m, "<!-- svg icon -->")
       end
 
-      # Compress repeated long Tailwind class strings to save tokens.
+      # Compress repeated long Tailwind class strings so the meaningful markup stays readable.
       # Replaces duplicate class="..." with a CSS variable reference after first occurrence.
       private_class_method def self.compress_tailwind(content)
         class_counts = Hash.new(0)

data/lib/rails_ai_context/version.rb

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

data/server.json

@@ -2,16 +2,16 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.crisnahine/rails-ai-context",
   "title": "Rails AI Context",
-  "description": "Auto-expose Rails app structure to AI via MCP or CLI. 39 read-only tools. Standalone or in-Gemfile.",
+  "description": "Stop AI from guessing your Rails app. 39 read-only tools give coding agents ground truth — schema, models, routes, conventions — on demand. MCP or CLI. Standalone or in-Gemfile.",
   "repository": {
     "url": "https://github.com/crisnahine/rails-ai-context",
     "source": "github"
   },
-  "version": "4.6.0",
+  "version": "4.7.0",
   "packages": [
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v4.6.0/rails-ai-context-mcp.mcpb",
+      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v4.7.0/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: 4.6.0
+  version: 4.7.0
 platform: ruby
 authors:
 - crisnahine
@@ -154,11 +154,12 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.4'
 description: |
-  rails-ai-context gives AI coding agents a complete mental model of your Rails
-  app — not just files, but how schema, models, routes, controllers, views, and
-  conventions connect. 39 live tools (via MCP server or CLI) let agents query
-  structure on demand with semantic validation that catches cross-file errors
-  (wrong columns, missing partials, broken routes) before code runs.
+  rails-ai-context turns your running Rails app into the source of truth for AI
+  coding assistants. Instead of guessing from training data or stale file reads,
+  agents query 39 live tools (via MCP server or CLI) to get your actual schema,
+  associations, routes, inherited filters, conventions, and test patterns.
+  Semantic validation catches cross-file errors (wrong columns, missing partials,
+  broken routes) before code runs — so AI writes correct code on the first try.
   Auto-generates context files for Claude Code, Cursor, GitHub Copilot, and
   OpenCode. Works standalone or in-Gemfile.
 email:
@@ -332,6 +333,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Give AI agents a complete mental model of your Rails app — 39 tools via MCP
-  or CLI. Standalone or in-Gemfile.
+summary: Stop AI from guessing your Rails app. 39 tools give coding agents ground
+  truth — schema, models, routes, conventions — on demand. MCP or CLI.
 test_files: []