rails-ai-context 4.6.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a6993d2929f87b6f9c29dffd5f16124a1d3ccb15ac3f8ba8f100364bf0feb06
-  data.tar.gz: '08c5fe8f51d126c1f7cc52ca9cc8ca0dc2edf5d1dba5f569b8ec5afaeecbb0b4'
+  metadata.gz: 2fa1c4d8e9c153c1ad06c0be6824b5421638259b441f4fabc6318e2709315d4e
+  data.tar.gz: ecf8ae7d7cb2da0a649146940da643da4cc7c0d3b7ee955a22a0ab1964791ccf
 SHA512:
-  metadata.gz: 94ec45e9fd089ba075c1b1c2457bfbf6fc9f2fc9c6da31b2ccafc7e51e64ca9579a390e25b56816a0c1bf4023f3ecbf092124082d53681029dcea3a5446065f5
-  data.tar.gz: fbab834f047ab3ae3392501964b6e0de1c090af063872473df3e3b074a161536c306cf4afd51daf8e44df8f127ddbb94fd885b15f21610f0884e27159ae118e3
+  metadata.gz: 606d359a389873a99e361927e24a26c965491a16286ec22183e514dd6f89fcc14e2fdb1fe838b9fdde72b6cd0e6bb602196de45299afc226d5894c3ac7fdc286
+  data.tar.gz: 66101ebb71fd0f15229ccf480b0b280e4d01793bedbd70e2e8158ef9869799a2b29214257a1e51a37ec11da8d23f325e1b43436ab900aa0841e9f5c561996d88

data/CHANGELOG.md

@@ -5,6 +5,52 @@ 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).
 
+## [5.0.0] — 2026-04-05
+
+### Removed (BREAKING)
+
+This release removes the Design & Styling surface and the Accessibility rule surface. When AI assistants consumed pre-digested design/styling context (color palettes, Tailwind class strings, canonical HTML/ERB snippets), they produced poor UI/UX output by blindly copying class strings instead of understanding visual hierarchy. The accessibility surface was asymmetric (Claude-only static rule file, no live MCP tool) and provided generic best-practice rules that didn't earn their keep.
+
+**Design system:**
+- **Removed `rails_get_design_system` MCP tool** — tool count is now **38** (was 39). Tool class `RailsAiContext::Tools::GetDesignSystem` deleted.
+- **Removed `:design_tokens` introspector** — class `RailsAiContext::Introspectors::DesignTokensIntrospector` deleted.
+- **Removed `ui_patterns`, `canonical_examples`, `shared_partials` keys** from `ViewTemplateIntrospector` output. The introspector now returns only `templates` and `partials`.
+- **Removed `DesignSystemHelper` serializer module** — module `RailsAiContext::Serializers::DesignSystemHelper` deleted. Consumers no longer receive UI Patterns sections in rule files or compact output.
+- **Removed `"design"` option** from the `include:` parameter of `rails_get_context`. Valid options are now: `schema`, `models`, `routes`, `gems`, `conventions`.
+
+**Accessibility:**
+- **Removed `:accessibility` introspector** — class `RailsAiContext::Introspectors::AccessibilityIntrospector` deleted. `ctx[:accessibility]` no longer populated.
+- **Removed `discover_accessibility` cross-cut** from `rails_analyze_feature`. The tool no longer emits a `## Accessibility` section with per-feature a11y findings.
+- **Removed Accessibility line** from root-file Stack Overview (no more "Accessibility: Good/OK/Needs work" label).
+
+**Preset counts:** `:full` is now **31** (was 33); `:standard` is now **17** (was 19). Both lost `:design_tokens` and `:accessibility`.
+
+**Legacy rule files no longer generated:**
+- `.claude/rules/rails-ui-patterns.md`
+- `.cursor/rules/rails-ui-patterns.mdc`
+- `.github/instructions/rails-ui-patterns.instructions.md`
+- `.claude/rules/rails-accessibility.md`
+
+### Migration notes
+
+- **Legacy files are NOT auto-deleted.** On first run after upgrade (via `rake ai:context`, `rails-ai-context context`, install generator, or watcher), the gem detects stale `rails-ui-patterns.*` and `rails-accessibility.md` files and prompts interactively in TTY sessions, or warns (non-destructive) in non-TTY sessions. Answer `y` to remove, or delete the files manually.
+- **If you depended on `rails_get_design_system`**, replace with `rails_get_component_catalog` (component-based) or read view files directly with `rails_read_file` / `rails_search_code`.
+- **If you depended on `include: "design"`** in `rails_get_context`, remove that option.
+- **If you depended on `ctx[:accessibility]`** (custom tools / serializers), that key is gone. Use standard a11y linters (axe-core, lighthouse) in your test suite instead.
+- **The "Build or modify a view" workflow** in tool guides now starts with `rails_get_component_catalog` instead of `rails_get_design_system`.
+
+### Why
+
+AI assistants that consume pre-digested summaries produce worse output than AI that reads actual source files. For design systems, class-string copying defeats the mental model required for cohesive visual hierarchy. For accessibility, generic rules ("add alt text") are universal knowledge that AI already has — the static counts didn't add actionable context, and the asymmetric distribution (Claude-only rule file, no live tool) was incoherent with the gem's charter. The gem's charter is ground truth for Rails structure (schema, associations, routes, controllers) — design-system and accessibility summaries were adjacent to that charter and actively counterproductive or inert.
+
+## [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

@@ -8,10 +8,11 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context.rb` — Main entry point, public API (Zeitwerk autoloaded)
 - `lib/rails_ai_context/configuration.rb` — User-facing config with presets (:standard, :full)
 - `lib/rails_ai_context/introspector.rb` — Orchestrates sub-introspectors
-- `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/introspectors/` — 31 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, view_templates, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database, components, performance, frontend_frameworks)
+- `lib/rails_ai_context/tools/` — 38 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, markdown, JSON, context_file_serializer, compact_serializer_helper, 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, stack_overview_helper)
+- `lib/rails_ai_context/legacy_cleanup.rb` — prompts cleanup of legacy `rails-ui-patterns.*` files (v5.0.0 migration)
 - `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
@@ -35,39 +36,39 @@ structure to AI assistants via the Model Context Protocol (MCP).
 7. **Diff-aware** — context regeneration skips unchanged files
 8. **Per-assistant serializers** — each AI tool gets tailored output format
 9. **Zeitwerk autoloading** — files loaded on-demand, not all upfront
-10. **Introspector presets** — `:full` (33) default, `:standard` (19) for lightweight usage
+10. **Introspector presets** — `:full` (31) default, `:standard` (17) for lightweight usage
 11. **MCP auto-discovery** — `.mcp.json` generated by install generator
 12. **Compact by default** — context files ≤150 lines, MCP tools use `detail` parameter (summary/standard/full)
 13. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`
 14. **Section markers** — root file content wrapped in `<!-- BEGIN/END rails-ai-context -->` to preserve user content
 15. **generate_root_files toggle** — when false, skip root files (CLAUDE.md, etc.), only generate split rules
-16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 39 built-in tools
-17. **Design system extraction** — view templates analyzed for canonical examples, color palette, typography, responsive patterns, interactive states, dark mode
+16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 38 built-in tools
+17. **Legacy cleanup prompting** — v5.0.0 removed `rails_get_design_system` tool + `:design_tokens` introspector + UI pattern rule files. `LegacyCleanup.prompt_legacy_files` detects stale `rails-ui-patterns.*` files at entry points (rake, CLI, watcher, install generator) and prompts (TTY) or warns (non-TTY)
 18. **skip_tools API** — `config.skip_tools` array lets users exclude specific built-in tools (e.g. `%w[rails_security_scan]`)
 19. **Security scanning** — optional Brakeman integration via `rails_security_scan` tool (graceful degradation if not installed)
 20. **tool_mode config** — `:mcp` (default, MCP primary + CLI fallback) or `:cli` (CLI only, no MCP server needed). Selected during install.
-21. **CLI tool access** — all 39 MCP tools callable from terminal: `rails ai:tool[schema]`, `rails-ai-context tool schema`. Tool name resolution: `schema` → `get_schema` → `rails_get_schema`.
+21. **CLI tool access** — all 38 MCP tools callable from terminal: `rails ai:tool[schema]`, `rails-ai-context tool schema`. Tool name resolution: `schema` → `get_schema` → `rails_get_schema`.
 22. **Shared ToolGuideHelper** — serializers use a shared module for tool reference sections, rendering MCP or CLI syntax based on `tool_mode`
 23. **Component catalog** — ViewComponent/Phlex introspection: props, slots, previews, sidecar assets, usage examples via `rails_get_component_catalog`
-24. **Accessibility scanning** — ARIA attributes, semantic HTML, screen reader text, alt text, landmark roles, accessibility score via AccessibilityIntrospector
-25. **Performance analysis** — N+1 query risks, missing counter_cache, missing FK indexes, eager load candidates via `rails_performance_check`
-26. **Migration advisor** — migration code generation with duplicate/nonexistent column warnings, reversibility flags, table name normalization via `rails_migration_advisor`
-27. **Frontend framework detection** — auto-detects React/Vue/Svelte/Angular from package.json, Vite/Shakapacker/Webpacker config, TypeScript setup, monorepo layout, package manager via `rails_get_frontend_stack`
-28. **Install generator idempotency** — re-install preserves existing config, only adds new sections, updates ai_tools/tool_mode selections, prompts per-tool file cleanup for removed tools
-29. **Docs search** — bundled topic index with weighted keyword search, on-demand GitHub fetch
-30. **Safe SQL queries** — defense-in-depth: regex pre-filter + SET TRANSACTION READ ONLY + timeout
-31. **Log reading** — reverse file tail with level filtering and sensitive data redaction
-32. **Config validation** — `http_port`, `cache_ttl`, `max_tool_response_chars`, `query_row_limit` validated on assignment with clear error messages
-33. **Sensitive column redaction** — query tool redacts columns by name AND by suffix pattern (password, secret, token, key, digest, hash) to prevent alias bypass
-34. **Standalone mode** — `gem install rails-ai-context && rails-ai-context init` works without Gemfile entry. CLI pre-loads gem before Rails boot, restores `$LOAD_PATH` entries stripped by `Bundler.setup`. Config from `.rails-ai-context.yml`.
-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.
+24. **Performance analysis** — N+1 query risks, missing counter_cache, missing FK indexes, eager load candidates via `rails_performance_check`
+25. **Migration advisor** — migration code generation with duplicate/nonexistent column warnings, reversibility flags, table name normalization via `rails_migration_advisor`
+26. **Frontend framework detection** — auto-detects React/Vue/Svelte/Angular from package.json, Vite/Shakapacker/Webpacker config, TypeScript setup, monorepo layout, package manager via `rails_get_frontend_stack`
+27. **Install generator idempotency** — re-install preserves existing config, only adds new sections, updates ai_tools/tool_mode selections, prompts per-tool file cleanup for removed tools
+28. **Docs search** — bundled topic index with weighted keyword search, on-demand GitHub fetch
+29. **Safe SQL queries** — defense-in-depth: regex pre-filter + SET TRANSACTION READ ONLY + timeout
+30. **Log reading** — reverse file tail with level filtering and sensitive data redaction
+31. **Config validation** — `http_port`, `cache_ttl`, `max_tool_response_chars`, `query_row_limit` validated on assignment with clear error messages
+32. **Sensitive column redaction** — query tool redacts columns by name AND by suffix pattern (password, secret, token, key, digest, hash) to prevent alias bypass
+33. **Standalone mode** — `gem install rails-ai-context && rails-ai-context init` works without Gemfile entry. CLI pre-loads gem before Rails boot, restores `$LOAD_PATH` entries stripped by `Bundler.setup`. Config from `.rails-ai-context.yml`.
+34. **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.
+35. **Config auto-loading** — `Configuration.auto_load!` checks `configured_via_block?` flag. If initializer ran, YAML is skipped. Corrupted YAML degrades gracefully with a warning.
+36. **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.
+37. **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 (1563 examples)
 bundle exec rubocop         # Lint
 ```
 

data/CONTRIBUTING.md

@@ -19,8 +19,8 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 ```
 lib/rails_ai_context/
 ├── cli/               # CLI tool runner (tool_runner.rb) — executes MCP tools from rake/Thor
-├── introspectors/     # 33 introspectors (schema, models, routes, etc.)
-├── tools/             # 39 MCP tools with detail levels and pagination
+├── introspectors/     # 31 introspectors (schema, models, routes, etc.)
+├── tools/             # 38 MCP tools with detail levels and pagination
 ├── serializers/       # Per-assistant formatters + shared ToolGuideHelper
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── live_reload.rb     # MCP live reload (file watcher + cache invalidation)

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>
 
@@ -66,7 +66,7 @@ rails-ai-context serve    # start MCP server
 
 </div>
 
-Now your AI doesn't guess — it **asks your app directly.** 39 tools that query your schema, models, routes, controllers, views, and conventions on demand. It gets the right answer the first time.
+Now your AI doesn't guess — it **asks your app directly.** 38 tools that query your schema, models, routes, controllers, views, and conventions on demand. It gets the right answer the first time.
 
 <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: raw file + schema vs structured output
-wc -c app/models/user.rb db/schema.rb
-rails 'ai:tool[model_details]' model=User | wc -c
+# Model: associations, scopes, callbacks, concerns — all resolved
+rails 'ai:tool[model_details]' model=User
+
+# 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>
 
@@ -143,7 +147,7 @@ rails ai:serve
 
 ### CLI
 
-Same 39 tools, no server needed. Works in any terminal, any AI tool.
+Same 38 tools, no server needed. Works in any terminal, any AI tool.
 
 ```bash
 rails 'ai:tool[search_code]' pattern="can_cook?" match_type=trace
@@ -211,14 +215,14 @@ rails 'ai:tool[validate]' files=app/controllers/cooks_controller.rb level=rails
 <br>
 
 ```bash
-# Get the design system
-rails 'ai:tool[design_system]' detail=standard
-# → your actual button classes, card patterns, color palette — copy-paste ready
-
 # Check existing view patterns
 rails 'ai:tool[view]' controller=dashboard
 # → templates with ivars, Turbo frames, Stimulus controllers, partial locals
 
+# See existing components + usage examples
+rails 'ai:tool[component_catalog]' detail=standard
+# → ViewComponent/Phlex props, slots, previews, sidecar assets
+
 # Get Stimulus data-attributes
 rails 'ai:tool[stimulus]' controller=chart
 # → correct HTML with dashes (not underscores) + reverse view lookup
@@ -228,9 +232,9 @@ rails 'ai:tool[stimulus]' controller=chart
 
 <br>
 
-## 39 Tools
+## 38 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>
@@ -282,7 +286,6 @@ Every tool is **read-only** and returns structured, token-efficient context.
 |:-----|:------------|
 | `get_view` | Templates with ivars, Turbo wiring, Stimulus refs, partial locals |
 | `get_stimulus` | HTML data-attributes (dashes!) + targets + values + actions |
-| `get_design_system` | Copy-paste HTML/ERB patterns for your actual components |
 | `get_partial_interface` | What locals to pass + what methods are called on them |
 | `get_turbo_map` | Broadcast → subscription wiring + mismatch warnings |
 | `get_frontend_stack` | React/Vue/Svelte/Angular, Hotwire, TypeScript, package manager |
@@ -339,6 +342,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
 
 ```
@@ -346,7 +371,7 @@ Every tool is **read-only** and returns structured, token-efficient context.
 │  Your Rails App                                          │
 │  models + schema + routes + controllers + views + jobs   │
 └────────────────────────┬────────────────────────────────┘
-                         │ introspects (33 introspectors)
+                         │ introspects (31 introspectors)
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │  rails-ai-context                                        │
@@ -356,7 +381,7 @@ Every tool is **read-only** and returns structured, token-efficient context.
          ▼                  ▼              ▼
 ┌──────────────────┐ ┌────────────┐ ┌────────────────────┐
 │  Static Files     │ │  MCP Server │ │  CLI Tools          │
-│  CLAUDE.md        │ │  39 tools   │ │  Same 39 tools      │
+│  CLAUDE.md        │ │  38 tools   │ │  Same 38 tools      │
 │  .cursor/rules/   │ │  stdio/HTTP │ │  No server needed   │
 │  .github/instr... │ │  .mcp.json  │ │  rails 'ai:tool[X]' │
 └──────────────────┘ └────────────┘ └────────────────────┘
@@ -390,7 +415,7 @@ Both paths ask which AI tools you use and whether you want MCP or CLI mode. `.mc
 | In-Gemfile | Standalone | What it does |
 |:-----------|:-----------|:------------|
 | `rails ai:context` | `rails-ai-context context` | Generate context files |
-| `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any of the 39 tools |
+| `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any of the 38 tools |
 | `rails ai:tool` | `rails-ai-context tool --list` | List all available tools |
 | `rails ai:serve` | `rails-ai-context serve` | Start MCP server (stdio) |
 | `rails ai:doctor` | `rails-ai-context doctor` | Diagnostics + AI readiness score |
@@ -405,7 +430,7 @@ Both paths ask which AI tools you use and whether you want MCP or CLI mode. `.mc
 RailsAiContext.configure do |config|
   config.ai_tools   = %i[claude cursor]   # Which AI tools to generate for
   config.tool_mode   = :mcp               # :mcp (default) or :cli
-  config.preset      = :full              # :full (33 introspectors) or :standard (19)
+  config.preset      = :full              # :full (31 introspectors) or :standard (17)
 end
 ```
 
@@ -416,9 +441,10 @@ end
 
 | Option | Default | Description |
 |:-------|:--------|:------------|
-| `preset` | `:full` | `:full` (33 introspectors) or `:standard` (19) |
+| `preset` | `:full` | `:full` (31 introspectors) or `:standard` (17) |
 | `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 +470,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1621 tests. 39 tools. 33 introspectors. Standalone or in-Gemfile.<br>
+1563 tests. 38 tools. 31 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/SECURITY.md

@@ -30,7 +30,7 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 
 ## Security Design
 
-- All 39 MCP tools are **read-only** and never modify your application or database.
+- All 38 MCP tools are **read-only** and never modify your application or database.
 - **Sensitive file blocking** — configurable `sensitive_patterns` blocks access to `.env`, `*.key`, `*.pem`, `credentials.yml.enc` across all search and read tools. Patterns are checked in `rails_search_code`, `rails_get_edit_context`, and all new tools.
 - **Path traversal protection** — all file-reading tools validate paths with `File.realpath()` against `Rails.root` to prevent directory escape.
 - **Command injection prevention** — code search uses `Open3.capture2` with array arguments (never shell strings). The `--` flag separator prevents pattern injection.

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.
 
 ---
 
@@ -126,7 +132,7 @@ end
 
 `rails ai:context` generates **29 files** across all AI assistants:
 
-### Claude Code (6 files)
+### Claude Code (5 files)
 
 | File | Purpose | Notes |
 |------|---------|-------|
@@ -134,7 +140,6 @@ end
 | `.claude/rules/rails-schema.md` | Database table listing | Auto-loaded by Claude Code alongside CLAUDE.md. |
 | `.claude/rules/rails-models.md` | Model listing with associations | Auto-loaded by Claude Code alongside CLAUDE.md. |
 | `.claude/rules/rails-context.md` | Project context and conventions | Auto-loaded by Claude Code alongside CLAUDE.md. |
-| `.claude/rules/rails-ui-patterns.md` | UI patterns and design tokens | Auto-loaded by Claude Code alongside CLAUDE.md. |
 | `.claude/rules/rails-mcp-tools.md` | Full MCP tool reference | Parameters, detail levels, pagination, workflow guide. |
 
 ### OpenCode (3 files)
@@ -145,17 +150,16 @@ end
 | `app/models/AGENTS.md` | Model reference | Auto-loaded by OpenCode when reading files in `app/models/`. |
 | `app/controllers/AGENTS.md` | Controller reference | Auto-loaded by OpenCode when reading files in `app/controllers/`. |
 
-### Cursor (5 files)
+### Cursor (4 files)
 
 | File | Purpose | Notes |
 |------|---------|-------|
 | `.cursor/rules/rails-project.mdc` | Project overview | `alwaysApply: true` — loaded in every conversation. |
 | `.cursor/rules/rails-models.mdc` | Model reference | `globs: app/models/**/*.rb` — auto-attaches when editing models. |
 | `.cursor/rules/rails-controllers.mdc` | Controller reference | `globs: app/controllers/**/*.rb` — auto-attaches when editing controllers. |
-| `.cursor/rules/rails-ui-patterns.mdc` | UI patterns and design tokens | `globs: app/views/**/*.erb` — loaded when editing views. |
 | `.cursor/rules/rails-mcp-tools.mdc` | MCP tool reference | `alwaysApply: true` — always available. |
 
-### GitHub Copilot (6 files)
+### GitHub Copilot (5 files)
 
 | File | Purpose | Notes |
 |------|---------|-------|
@@ -163,7 +167,6 @@ end
 | `.github/instructions/rails-models.instructions.md` | Model context | `applyTo: app/models/**/*.rb` — loaded when editing models. |
 | `.github/instructions/rails-controllers.instructions.md` | Controller context | `applyTo: app/controllers/**/*.rb` — loaded when editing controllers. |
 | `.github/instructions/rails-context.instructions.md` | Project context and conventions | `applyTo: **/*` — loaded everywhere. |
-| `.github/instructions/rails-ui-patterns.instructions.md` | UI patterns and design tokens | `applyTo: app/views/**/*.erb` — loaded when editing views. |
 | `.github/instructions/rails-mcp-tools.instructions.md` | MCP tool reference | `applyTo: **/*` — loaded everywhere. |
 
 ### Generic (1 file)
@@ -255,7 +258,7 @@ rails ai:context:claude           # Use this instead (no quoting needed)
 
 ## CLI Tools
 
-All 39 MCP tools can be run directly from the terminal — no MCP server or AI client needed.
+All 38 MCP tools can be run directly from the terminal — no MCP server or AI client needed.
 
 ### Rake
 
@@ -319,7 +322,7 @@ The `tool_mode` is selected during `rails generate rails_ai_context:install`.
 
 ## MCP Tools — Full Reference
 
-All 39 tools are **read-only** and **idempotent** — they never modify your application or database.
+All 38 tools are **read-only** and **idempotent** — they never modify your application or database.
 
 ### rails_get_schema
 
@@ -701,33 +704,6 @@ rails_analyze_feature(feature: "orders")
 
 **Returns:** Markdown with sections for Models (with columns, associations, validations, scopes, enums), Controllers (with actions and filters), Routes, Services (with methods), Jobs (with queue/retry), Views (with partials and Stimulus refs), Stimulus controllers (with targets/values/actions), Tests (with counts), Related models, Concerns, Callbacks, Channels, Mailers, and Environment dependencies. Each section shows match counts.
 
-### rails_get_design_system
-
-Returns the app's design system: color palette with semantic roles, component patterns with real HTML examples from actual views, typography scale, layout conventions, responsive breakpoints, and interactive state patterns.
-
-**Parameters:**
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `detail` | string | `summary` (palette + components), `standard` (+ canonical page examples + design rules, default), `full` (+ typography, responsive, dark mode, animations, design tokens) |
-
-**Examples:**
-
-```
-rails_get_design_system()
-  → Color palette (primary, danger, success), component patterns (buttons, cards, inputs),
-    canonical page examples (form page, list page), design rules
-
-rails_get_design_system(detail: "summary")
-  → Compact: color roles + component class strings only
-
-rails_get_design_system(detail: "full")
-  → Everything: + typography scale, responsive breakpoints, interactive states,
-    dark mode patterns, animations, icon system, design tokens, shared partials
-```
-
-**Returns:** Structured design system reference. Includes real HTML/ERB snippets from the app's actual views as canonical examples, semantic color roles (primary for CTAs, danger for destructive), component variants, typography hierarchy, spacing scale, and explicit design rules for AI to follow.
-
 ### rails_security_scan
 
 Runs Brakeman static security analysis on the Rails app. Detects SQL injection, XSS, mass assignment, command injection, and other vulnerabilities. Requires the `brakeman` gem — returns installation instructions if not present.
@@ -1142,7 +1118,7 @@ RailsAiContext.configure do |config|
 end
 ```
 
-Both transports are **read-only** — they expose the same 39 tools and never modify your app.
+Both transports are **read-only** — they expose the same 38 tools and never modify your app.
 
 ---
 
@@ -1153,7 +1129,7 @@ Both transports are **read-only** — they expose the same 39 tools and never mo
 RailsAiContext.configure do |config|
   # --- Introspectors ---
 
-  # Presets: :full (33 introspectors, default) or :standard (19)
+  # Presets: :full (31 introspectors, default) or :standard (17)
   config.preset = :full
 
   # Cherry-pick on top of a preset
@@ -1268,7 +1244,7 @@ end
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `preset` | Symbol | `:full` | Introspector preset (`:full` or `:standard`) |
-| `introspectors` | Array | 32 (full preset) | Which introspectors to run |
+| `introspectors` | Array | 31 (full preset) | Which introspectors to run |
 | `context_mode` | Symbol | `:compact` | `:compact` or `:full` |
 | `claude_max_lines` | Integer | `150` | Max lines for CLAUDE.md in compact mode |
 | `max_tool_response_chars` | Integer | `200_000` | Safety cap for MCP tool responses |
@@ -1290,6 +1266,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) |
@@ -1325,7 +1302,7 @@ All split rules include an app overview file, so no context is lost when root fi
 
 ## Introspectors — Full List
 
-### Standard preset (19 introspectors)
+### Standard preset (17 introspectors)
 
 Core Rails structure only. Use `config.preset = :standard` for a lighter footprint.
 
@@ -1342,16 +1319,14 @@ Core Rails structure only. Use `config.preset = :standard` for a lighter footpri
 | `migrations` | Total count, schema version, pending migrations, recent migration history with detected actions (create_table, add_column, etc.), migration statistics. |
 | `config` | Cache store, session store, timezone, queue adapter, mailer settings, middleware stack, initializers, credentials status, CurrentAttributes classes. |
 | `stimulus` | Stimulus controllers with targets, values (with types), actions, outlets, classes. Extracted from JS/TS files. |
-| `view_templates` | View file contents, partial references, Stimulus data attributes, UI pattern extraction, model field usage in partials. |
-| `design_tokens` | Auto-detects CSS framework (Tailwind v3/v4, Bootstrap, Sass, plain CSS) and extracts design tokens from config files and built CSS. |
+| `view_templates` | View file contents, partial references, Stimulus data attributes, model field usage in partials. |
 | `components` | ViewComponent/Phlex components: props, slots, previews, sidecar assets, usage examples. |
 | `turbo` | Turbo Frames (IDs and files), Turbo Stream templates, model broadcasts (`broadcasts_to`, `broadcasts`). |
 | `auth` | Devise models with modules, Rails 8 built-in auth, has_secure_password, Pundit policies, CanCanCan, CORS config, CSP config. |
-| `accessibility` | ARIA attributes, semantic HTML elements, screen reader text, alt text coverage, landmark roles, accessibility score. |
 | `performance` | N+1 query risks, missing counter_cache, missing FK indexes, Model.all anti-patterns, eager load candidates. |
 | `i18n` | Default locale, available locales, locale files with key counts, backend class, parse errors. |
 
-### Full preset (33 introspectors) — default
+### Full preset (31 introspectors) — default
 
 Includes all standard introspectors plus:
 
@@ -1474,11 +1449,11 @@ OpenCode uses **per-directory lazy-loading**: when the agent reads a file, it wa
 
 | Setup | Coverage | Notes |
 |-------|----------|-------|
-| Rails full-stack (ERB + Hotwire) | 32/32 | All introspectors relevant |
-| Rails + Inertia.js (React/Vue) | ~25/32 | Views/Turbo partially useful, backend fully covered |
-| Rails API + React/Next.js SPA | ~23/32 | Schema, models, routes, API, auth, jobs — all covered |
-| Rails API + mobile app | ~23/32 | Same as SPA — backend introspection is identical |
-| Rails engine (mountable gem) | ~18/32 | Core introspectors (schema, models, routes, gems) work |
+| Rails full-stack (ERB + Hotwire) | 31/31 | All introspectors relevant |
+| Rails + Inertia.js (React/Vue) | ~25/31 | Views/Turbo partially useful, backend fully covered |
+| Rails API + React/Next.js SPA | ~23/31 | Schema, models, routes, API, auth, jobs — all covered |
+| Rails API + mobile app | ~23/31 | Same as SPA — backend introspection is identical |
+| Rails engine (mountable gem) | ~18/31 | Core introspectors (schema, models, routes, gems) work |
 
 Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — they report nothing when those features aren't present.