rails-ai-context 4.5.2 → 4.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d53c26bdd73eac84be7e9a49ea08c2a50dd0230f969cb29ae240cf2d08b9e4c3
-  data.tar.gz: a65a518fab277ff246401cffb32701fb36048f65034b068e20f4b3fe76ddc4eb
+  metadata.gz: c780366dc085c17be730aded4bbe8548b0e5e71c5c810caed96104a9379363fa
+  data.tar.gz: f5c46207b643df1a7dc1c5563c1d9e932f772ce5e27eb1839d9f14ddde116bd0
 SHA512:
-  metadata.gz: 0504e0e68f018d325189ccdfd153b7097d1204c906241a9a0dfea41586272b0c2ae296f81704c4e6c4ac9bb414aaab83c5de35e226b7aabff52b984d1bec451e
-  data.tar.gz: f2c8a762bd3520edd09e719337043be0a9b7158d0099076118226012cea980ca1877c48459d78810c8e9a1c9d91bf526aad4a2c334521e19c5ac7b715bc44b1e
+  metadata.gz: 934c4d703203801494a8addde164c71e56119e5701dd454574b0362d2a6d68523b6f0830654ff81eaa1d36fac7eca457374960e4e9fe54731f32431fe23ea8a4
+  data.tar.gz: ca2bf9e27db44fb35b8d9bd984748b7fce1108a013ef7ea6ec5a01757c48187b6ce6985c529ee8bf4df7cc9abd59085da8c356b3c73052e5196b07cc9a9a3790

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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
+- **Integration test suite** — 3 purpose-built Rails 8 apps exercising every gem feature end-to-end:
+  - `full_app` — comprehensive app (38 gems, 14 models, 15 controllers, 26 views, 5 jobs, 3 mailers, multi-database, ViewComponent, Stimulus, STI, polymorphic, AASM, PaperTrail, FriendlyId, encrypted attributes, CurrentAttributes, Flipper feature flags, Sentry monitoring, Pundit auth, Ransack search, Dry-rb, acts_as_tenant, Docker, Kamal, GitHub Actions CI, RSpec + FactoryBot)
+  - `api_app` — API-only app (Products/Orders/OrderItems, namespaced API v1 routes, CLI tool_mode)
+  - `minimal_app` — bare minimum app (single model, graceful degradation testing)
+- **Master test runner** (`test_apps/run_all_tests.sh`) — validates Doctor, context generation, all 33 introspectors, all 39 MCP tools, Rake tasks, MCP server startup, and app-specific pattern detection across all 3 apps (222 tests)
+- All 3 test apps achieve **100/100 AI Readiness Score**
+
+### Fixed
+- **Standalone CLI `full_gem_path` crash** — `Gem.loaded_specs.delete_if { |_, spec| !spec.default_gem? }` in the exe file cleared gem specs needed by MCP SDK at runtime (`json-schema` gem's `full_gem_path` returned nil). Added `!ENV["BUNDLE_BIN_PATH"]` guard so cleanup only runs in true standalone mode, not under `bundle exec`. This bug affected ALL `rails-ai-context tool` commands in standalone mode.
+
+### Changed
+- Test count: 1621 RSpec examples + 222 integration tests across 3 apps
+
 ## [4.5.2] — 2026-04-04
 
 ### Added
@@ -30,8 +54,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CLI error messages** — Clean error messages for all CLI error paths
 - **Rake/init parity** — `rake ai:context` and `init` command now match generator output
 
+### Refactored
+- **SLOP audit: ~640 lines removed** — comprehensive audit eliminating superfluous abstractions, dead code, and duplicated patterns
+- **CompactSerializerHelper** — extracted shared logic from ClaudeSerializer and OpencodeSerializer, eliminating ~75% duplication
+- **StackOverviewHelper consolidation** — moved `project_root`, `detect_service_files`, `detect_job_files`, `detect_before_actions`, `scope_names`, `notable_gems_list`, `arch_labels_hash`, `pattern_labels_hash`, `write_rule_files` into shared module, replacing 30+ duplicate copies across 6 serializers
+- **Atomic file writes** — `write_rule_files` uses temp file + rename for crash-safe context file generation
+- **ConventionDetector → ConventionIntrospector** — renamed for naming consistency with all 33 other introspectors
+- **MarkdownEscape inlined** — single-use module inlined into MarkdownSerializer as private method
+- **RulesSerializer deleted** — dead code never called by ContextFileSerializer
+- **BaseTool cleanup** — removed dead `auto_compress`, `app_size`, `session_queried?` methods
+- **IntrospectionError deleted** — exception class never raised anywhere
+- **mobile_paths config removed** — config option never read by any introspector, tool, or serializer
+- **server_version** — changed from attr_accessor to method delegating to `VERSION` constant
+- **Configuration constants** — extracted `DEFAULT_EXCLUDED_FILTERS`, `DEFAULT_EXCLUDED_MIDDLEWARE`, `DEFAULT_EXCLUDED_CONCERNS` as frozen constants
+- **Detail spec consolidation** — merged 5 detail spec files into their base spec counterparts
+- **Orphaned spec cleanup** — removed `gem_introspector_spec.rb` duplicate (canonical spec already exists under introspectors/)
+
 ### Changed
-- Test count: 1658 examples (76 new tests for Phase 2 features)
+- Test count: 1621 examples (consolidated from 1658 — no coverage lost, only duplicate/orphaned specs removed)
 
 ## [4.4.0] — 2026-04-03
 

data/CLAUDE.md

@@ -11,12 +11,11 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/introspectors/` — 33 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, view_templates, design_tokens, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database, components, accessibility, performance, frontend_frameworks)
 - `lib/rails_ai_context/tools/` — 39 MCP tools using the official mcp SDK
 - `lib/rails_ai_context/cli/` — CLI tool runner (`tool_runner.rb`) — executes MCP tools from rake/Thor
-- `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, copilot, copilot_instructions, rules, markdown, JSON, context_file_serializer, test_command_detection, tool_guide_helper, design_system_helper, stack_overview_helper)
+- `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, copilot, copilot_instructions, markdown, JSON, context_file_serializer, compact_serializer_helper, test_command_detection, tool_guide_helper, design_system_helper, stack_overview_helper)
 - `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
 - `lib/rails_ai_context/server.rb` — MCP server configuration (stdio + HTTP transports)
 - `lib/rails_ai_context/middleware.rb` — Rack middleware for auto-mounting MCP HTTP endpoint
 - `lib/rails_ai_context/safe_file.rb` — Safe file reading with size limits and error handling
-- `lib/rails_ai_context/markdown_escape.rb` — Escapes markdown special characters in dynamic content
 - `lib/rails_ai_context/fingerprinter.rb` — SHA256 file fingerprinting for cache invalidation
 - `lib/rails_ai_context/doctor.rb` — Diagnostic checks and AI readiness scoring
 - `lib/rails_ai_context/live_reload.rb` — MCP live reload: watches files, invalidates caches, notifies AI clients
@@ -64,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 (1658 examples)
+bundle exec rspec           # Run specs (1627 examples)
 bundle exec rubocop         # Lint
 ```
 

data/README.md

@@ -19,7 +19,7 @@
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green)](https://registry.modelcontextprotocol.io)
 [![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3%20%7C%203.4-CC342D)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.1%20%7C%207.2%20%7C%208.0-CC0000)](https://github.com/crisnahine/rails-ai-context)
-[![Tests](https://img.shields.io/badge/Tests-1529%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
+[![Tests](https://img.shields.io/badge/Tests-1621%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 </div>
@@ -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` |
@@ -444,7 +471,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1529 tests. 39 tools. 33 introspectors. Standalone or in-Gemfile.<br>
+1621 tests. 39 tools. 33 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/SECURITY.md

@@ -4,6 +4,9 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 4.6.x   | :white_check_mark: |
+| 4.5.x   | :white_check_mark: |
+| 4.4.x   | :white_check_mark: |
 | 4.3.x   | :white_check_mark: |
 | 4.2.x   | :white_check_mark: (4.2.1 includes security hardening) |
 | 4.1.x   | :white_check_mark: |

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/exe/rails-ai-context

@@ -6,7 +6,11 @@
 # may need different versions of those deps (e.g., bigdecimal 4.1.0 activated here
 # but Gemfile.lock wants 4.0.1). Clear non-default gem activations so Bundler can
 # resolve cleanly. The $LOAD_PATH entries remain (Bundler.setup replaces them anyway).
-if defined?(Gem) && Gem.respond_to?(:loaded_specs)
+#
+# Skip this when running under `bundle exec` — Bundler has already resolved gems
+# correctly, and clearing specs breaks gems that look up their own path at runtime
+# (e.g., MCP SDK reads Gem.loaded_specs["json-schema"].full_gem_path).
+if defined?(Gem) && Gem.respond_to?(:loaded_specs) && !ENV["BUNDLE_BIN_PATH"]
   Gem.loaded_specs.delete_if { |_, spec| !spec.default_gem? }
 end
 

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 ────────────────────────────────────────────
@@ -257,7 +262,6 @@ module RailsAiContext
             # ── Frontend Framework Detection ─────────────────────────────────
             # Auto-detected from package.json, config/vite.json, etc. Override only if needed.
             # config.frontend_paths = ["app/frontend", "../web-client"]
-            # config.mobile_paths = ["../mobile-app"]
         SECTION
       }.freeze
 

data/lib/rails_ai_context/configuration.rb

@@ -13,11 +13,12 @@ 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
-      server_name server_version cache_ttl max_tool_response_chars
+      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
       excluded_route_prefixes excluded_filters excluded_middleware excluded_paths
-      sensitive_patterns search_extensions concern_paths frontend_paths mobile_paths
+      sensitive_patterns search_extensions concern_paths frontend_paths
       max_file_size max_test_file_size max_schema_file_size max_view_total_size
       max_view_file_size max_search_results max_validate_files
       query_timeout query_row_limit query_redacted_columns allow_query_in_production
@@ -79,7 +80,11 @@ module RailsAiContext
     }.freeze
 
     # MCP server settings
-    attr_accessor :server_name, :server_version
+    attr_accessor :server_name
+
+    def server_version
+      RailsAiContext::VERSION
+    end
 
     # Which introspectors to run
     attr_accessor :introspectors
@@ -129,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)
@@ -151,6 +161,33 @@ module RailsAiContext
     # Tool invocation mode: :mcp (MCP primary + CLI fallback) or :cli (CLI only)
     attr_accessor :tool_mode
 
+    DEFAULT_EXCLUDED_FILTERS = %w[
+      verify_authenticity_token verify_same_origin_request
+      turbo_tracking_request_id handle_unverified_request
+      mark_for_same_origin_verification
+    ].freeze
+
+    DEFAULT_EXCLUDED_MIDDLEWARE = %w[
+      Rack::Sendfile ActionDispatch::Static ActionDispatch::Executor
+      ActionDispatch::ServerTiming Rack::Runtime
+      ActionDispatch::RequestId ActionDispatch::RemoteIp
+      Rails::Rack::Logger ActionDispatch::ShowExceptions
+      ActionDispatch::DebugExceptions ActionDispatch::Callbacks
+      ActionDispatch::Cookies ActionDispatch::Session::CookieStore
+      ActionDispatch::Flash ActionDispatch::ContentSecurityPolicy::Middleware
+      ActionDispatch::PermissionsPolicy::Middleware ActionDispatch::ActionableExceptions
+      Rack::Head Rack::ConditionalGet Rack::ETag Rack::TempfileReaper
+      ActiveRecord::Migration::CheckPending ActionDispatch::HostAuthorization
+      Rack::MethodOverride ActionDispatch::Session::AbstractSecureStore
+    ].freeze
+
+    DEFAULT_EXCLUDED_CONCERNS = [
+      /::Generated/,
+      /\A(ActiveRecord|ActiveModel|ActiveSupport|ActionText|ActionMailbox|ActiveStorage)/,
+      /\A(ActionDispatch|ActionController|ActionView|AbstractController)/,
+      /\A(Devise::Models|Devise::Orm|Bullet::|Turbo::|GlobalID::|Rolify::)/
+    ].freeze
+
     # 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/)
@@ -164,7 +201,6 @@ module RailsAiContext
 
     # Frontend framework detection (optional overrides — auto-detected if nil)
     attr_accessor :frontend_paths         # User-declared frontend dirs (e.g. ["app/frontend", "../web-client"])
-    attr_accessor :mobile_paths           # User-declared mobile dirs (e.g. ["../mobile-app"])
 
     # Database query tool settings (rails_query)
     attr_accessor :query_timeout              # Statement timeout in seconds (default: 5)
@@ -177,7 +213,6 @@ module RailsAiContext
 
     def initialize
       @server_name         = "rails-ai-context"
-      @server_version      = RailsAiContext::VERSION
       @introspectors       = PRESETS[:full].dup
       @excluded_paths      = %w[node_modules tmp log vendor .git doc docs]
       @sensitive_patterns  = %w[
@@ -202,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
@@ -211,30 +247,9 @@ module RailsAiContext
       @max_validate_files       = 50
       @excluded_controllers     = %w[DeviseController Devise::OmniauthCallbacksController]
       @excluded_route_prefixes  = %w[action_mailbox/ active_storage/ rails/ conductor/ devise/ turbo/]
-      @excluded_concerns        = [
-        /::Generated/,
-        /\A(ActiveRecord|ActiveModel|ActiveSupport|ActionText|ActionMailbox|ActiveStorage)/,
-        /\A(ActionDispatch|ActionController|ActionView|AbstractController)/,
-        /\A(Devise::Models|Devise::Orm|Bullet::|Turbo::|GlobalID::|Rolify::)/
-      ]
-      @excluded_filters         = %w[
-        verify_authenticity_token verify_same_origin_request
-        turbo_tracking_request_id handle_unverified_request
-        mark_for_same_origin_verification
-      ]
-      @excluded_middleware      = %w[
-        Rack::Sendfile ActionDispatch::Static ActionDispatch::Executor
-        ActionDispatch::ServerTiming Rack::Runtime
-        ActionDispatch::RequestId ActionDispatch::RemoteIp
-        Rails::Rack::Logger ActionDispatch::ShowExceptions
-        ActionDispatch::DebugExceptions ActionDispatch::Callbacks
-        ActionDispatch::Cookies ActionDispatch::Session::CookieStore
-        ActionDispatch::Flash ActionDispatch::ContentSecurityPolicy::Middleware
-        ActionDispatch::PermissionsPolicy::Middleware ActionDispatch::ActionableExceptions
-        Rack::Head Rack::ConditionalGet Rack::ETag Rack::TempfileReaper
-        ActiveRecord::Migration::CheckPending ActionDispatch::HostAuthorization
-        Rack::MethodOverride ActionDispatch::Session::AbstractSecureStore
-      ]
+      @excluded_concerns        = DEFAULT_EXCLUDED_CONCERNS.dup
+      @excluded_filters         = DEFAULT_EXCLUDED_FILTERS.dup
+      @excluded_middleware      = DEFAULT_EXCLUDED_MIDDLEWARE.dup
       @custom_tools             = []
       @skip_tools               = []
       @ai_tools                 = nil
@@ -242,7 +257,6 @@ module RailsAiContext
       @search_extensions        = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
       @concern_paths            = %w[app/models/concerns app/controllers/concerns]
       @frontend_paths           = nil
-      @mobile_paths             = nil
       @query_timeout            = 5
       @query_row_limit          = 100
       @query_redacted_columns   = %w[

data/lib/rails_ai_context/introspector.rb

@@ -63,7 +63,7 @@ module RailsAiContext
       when :routes      then Introspectors::RouteIntrospector.new(app)
       when :jobs        then Introspectors::JobIntrospector.new(app)
       when :gems        then Introspectors::GemIntrospector.new(app)
-      when :conventions then Introspectors::ConventionDetector.new(app)
+      when :conventions then Introspectors::ConventionIntrospector.new(app)
       when :stimulus       then Introspectors::StimulusIntrospector.new(app)
       when :database_stats then Introspectors::DatabaseStatsIntrospector.new(app)
       when :controllers    then Introspectors::ControllerIntrospector.new(app)

data/lib/rails_ai_context/introspectors/{convention_detector.rb → convention_introspector.rb}

@@ -4,7 +4,7 @@ module RailsAiContext
   module Introspectors
     # Detects high-level Rails conventions and patterns in use,
     # giving AI assistants critical context about the app's architecture.
-    class ConventionDetector
+    class ConventionIntrospector
       attr_reader :app
 
       def initialize(app)

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -19,34 +19,18 @@ module RailsAiContext
       # @return [Hash] { written: [paths], skipped: [paths] }
       def call(output_dir)
         rules_dir = File.join(output_dir, ".claude", "rules")
-        FileUtils.mkdir_p(rules_dir)
-
-        written = []
-        skipped = []
 
         files = {
-          "rails-context.md" => render_context_overview,
-          "rails-schema.md" => render_schema_reference,
-          "rails-models.md" => render_models_reference,
-          "rails-ui-patterns.md" => render_ui_patterns_reference,
-          "rails-mcp-tools.md" => render_mcp_tools_reference,
-          "rails-components.md" => render_components_reference,
-          "rails-accessibility.md" => render_accessibility_reference
+          File.join(rules_dir, "rails-context.md") => render_context_overview,
+          File.join(rules_dir, "rails-schema.md") => render_schema_reference,
+          File.join(rules_dir, "rails-models.md") => render_models_reference,
+          File.join(rules_dir, "rails-ui-patterns.md") => render_ui_patterns_reference,
+          File.join(rules_dir, "rails-mcp-tools.md") => render_mcp_tools_reference,
+          File.join(rules_dir, "rails-components.md") => render_components_reference,
+          File.join(rules_dir, "rails-accessibility.md") => render_accessibility_reference
         }
 
-        files.each do |filename, content|
-          next unless content
-
-          filepath = File.join(rules_dir, filename)
-          if File.exist?(filepath) && File.read(filepath) == content
-            skipped << filepath
-          else
-            File.write(filepath, content)
-            written << filepath
-          end
-        end
-
-        { written: written, skipped: skipped }
+        write_rule_files(files)
       end
 
       private
@@ -74,17 +58,8 @@ module RailsAiContext
         lines.concat(full_preset_stack_lines)
 
         # ApplicationController before_actions — apply to all controllers
-        begin
-          root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
-          app_ctrl_file = File.join(root, "app", "controllers", "application_controller.rb")
-          if File.exist?(app_ctrl_file)
-            source = File.read(app_ctrl_file)
-            before_actions = source.scan(/before_action\s+:([\w!?]+)/).flatten
-            if before_actions.any?
-              lines << "" << "**Global before_actions:** #{before_actions.join(', ')}"
-            end
-          end
-        rescue => e; $stderr.puts "[rails-ai-context] Serializer section skipped: #{e.message}"; end
+        before_actions = detect_before_actions
+        lines << "" << "**Global before_actions:** #{before_actions.join(', ')}" if before_actions.any?
 
         lines << ""
         lines << "ALWAYS use MCP tools for context — do NOT read reference files directly."
@@ -206,7 +181,7 @@ module RailsAiContext
 
           # Include scopes so agents know available query methods
           scopes = data[:scopes] || []
-          scope_names = scopes.map { |s| s.is_a?(Hash) ? s[:name] : s }
+          scope_names = scope_names(scopes)
           lines << "  scopes: #{scope_names.join(', ')}" if scopes.any?
 
           # Instance methods — filter Devise/framework internals that add noise
@@ -248,8 +223,7 @@ module RailsAiContext
 
         # Shared partials — so agents reuse them instead of recreating
         begin
-          root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
-          shared_dir = File.join(root, "app", "views", "shared")
+          shared_dir = File.join(project_root, "app", "views", "shared")
           if Dir.exist?(shared_dir)
             partials = Dir.glob(File.join(shared_dir, "_*.html.erb"))
               .map { |f| File.basename(f) }
@@ -263,8 +237,7 @@ module RailsAiContext
 
         # Helpers — so agents use existing helpers instead of creating new ones
         begin
-          root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
-          helper_file = File.join(root, "app", "helpers", "application_helper.rb")
+          helper_file = File.join(project_root, "app", "helpers", "application_helper.rb")
           if File.exist?(helper_file)
             helper_methods = File.read(helper_file).scan(/def\s+(\w+)/).flatten
             if helper_methods.any?