rails-ai-context 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4aecabdd89f6a8bb9cb32189de791a98ebe632e3dcdb7406c4ae334eda9cb71
-  data.tar.gz: 546be87729c99383fd4eed6cb94df487f106fac6035e7a683902bf764694297b
+  metadata.gz: 7aa2c43d22465356700ded7ac615f4d38ba24e1bee512658dc1ec43196935e9c
+  data.tar.gz: f718d8e2c3b790294e212c557216cd2babd99459fea3a5f1245f9ad09329e52d
 SHA512:
-  metadata.gz: cf2ebe640b6dcf2d98b48dac91efb7fde81804f26d3f2b71e4f6ee59de23ed10d15e4e8b0ae5a4fe6ffc5dff2d4fb6904a99e269153da9a54909050b23d7c123
-  data.tar.gz: 9f62a8d2e6a9e73fad88bf5bbf86881976f80aa687cee579b2116d26c3d3719d4bbb82e4226d6193531efe6299abeff8272eee82190fe4703efd8e427865e133
+  metadata.gz: c4c9d908941193ffd7cda89bc8a5da67a9531ffd09e723382eebc39c7ac77a06faa3958bf4048f550d0d3a5883edf9f8a67a2b62c65130847589db53d954fe5d
+  data.tar.gz: 38a1f37c770eff7680ed3b0acb43627a5ba36b8168eafbf087907d8e5445103ec4cc06b4cb08103e48baf772c710d6333278759789f3bcc44e7b745787cc9b11

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [0.7.1] - 2026-03-19
+
+### Added
+
+- **Full MCP tool reference in all context files** — every generated file (CLAUDE.md, .cursorrules, .windsurfrules, copilot-instructions.md) now includes complete tool documentation with parameters, detail levels, pagination examples, and usage workflow. Dedicated `rails-mcp-tools` split rule files added for Claude, Cursor, Windsurf, and Copilot.
+
+### Fixed
+
+- **Schema version parsing** — versions with underscores (e.g. `2024_01_15_123456`) were truncated to the first digit group. Now captures the full version string.
+- **Documentation** — updated README (detail levels, pagination, generated file tree, config options), SECURITY.md (supported versions), CONTRIBUTING.md (project structure), gemspec (post-install message), demo_script.sh (all 17 generated files).
+
 ## [0.7.0] - 2026-03-19
 
 ### Added

data/CONTRIBUTING.md

@@ -18,12 +18,12 @@ The test suite uses [Combustion](https://github.com/pat/combustion) to boot a mi
 
 ```
 lib/rails_ai_context/
-├── introspectors/     # One class per data source (schema, models, routes, etc.)
-├── tools/             # MCP tool definitions (one per introspector)
-├── serializers/       # Output formatters (markdown, JSON, context files)
+├── introspectors/     # 27 introspectors (schema, models, routes, etc.)
+├── tools/             # 9 MCP tools with detail levels and pagination
+├── serializers/       # Per-assistant formatters (claude, cursor, windsurf, copilot, JSON)
 ├── server.rb          # MCP server setup (stdio + HTTP)
 ├── engine.rb          # Rails Engine for auto-integration
-└── configuration.rb   # User-facing config options
+└── configuration.rb   # User-facing config (presets, context_mode, limits)
 ```
 
 ## Adding a New Introspector

data/README.md

@@ -61,13 +61,26 @@ rails generate rails_ai_context:install
 rails ai:context
 ```
 
-This creates:
-- `CLAUDE.md` — for Claude Code (with behavioral rules)
-- `.cursorrules` — for Cursor (compact rules format)
-- `.windsurfrules` — for Windsurf (compact rules format)
-- `.github/copilot-instructions.md` — for GitHub Copilot (task-oriented)
+This creates context files **and** split rule files for each AI assistant:
 
-Each file is tailored to the AI assistant's preferred format. **Commit these files.** Your entire team gets smarter AI assistance.
+```
+CLAUDE.md                                    # ≤150 lines (compact mode)
+.claude/rules/rails-schema.md                # Auto-loaded by Claude Code
+.claude/rules/rails-models.md                # Auto-loaded by Claude Code
+.cursorrules                                 # Legacy format (compact)
+.cursor/rules/rails-project.mdc              # Always-on project overview
+.cursor/rules/rails-models.mdc              # Auto-attaches in app/models/
+.cursor/rules/rails-controllers.mdc          # Auto-attaches in app/controllers/
+.windsurfrules                               # ≤5,800 chars (within 6K limit)
+.windsurf/rules/rails-context.md             # New rules format
+.github/copilot-instructions.md              # ≤500 lines (compact mode)
+.github/instructions/rails-models.instructions.md       # applyTo: app/models/
+.github/instructions/rails-controllers.instructions.md  # applyTo: app/controllers/
+```
+
+Each file is tailored to the AI assistant's preferred format and respects its size limits. **Commit these files.** Your entire team gets smarter AI assistance.
+
+> **Context modes:** The default `:compact` mode generates small, focused files that point to MCP tools for details. Use `rails ai:context:full` to dump everything into the files instead (good for small apps).
 
 ### 3. MCP Server
 
@@ -182,6 +195,29 @@ The gem exposes 9 tools via MCP that AI clients can call:
 
 All tools are **read-only** — they never modify your application or database.
 
+### Detail Levels & Pagination
+
+Tools support a `detail` parameter so AI assistants can start with an overview, then drill into specifics — critical for apps with hundreds of models or tables:
+
+| Detail Level | What it returns | Default limit |
+|-------------|-----------------|---------------|
+| `summary` | Names + counts (e.g. "users — 12 columns, 3 indexes") | 50 |
+| `standard` | Names + key details (e.g. column names and types) | 15 |
+| `full` | Everything including indexes, FKs, constraints | 5 |
+
+```
+# AI calls summary first to understand the landscape
+rails_get_schema(detail: "summary")
+
+# Then drills into a specific table
+rails_get_schema(table: "users")
+
+# Pagination for large schemas
+rails_get_schema(detail: "summary", limit: 20, offset: 40)
+```
+
+Schema and routes tools also support `limit` and `offset` for pagination. A configurable safety net (`max_tool_response_chars`, default 120K) truncates oversized responses with hints to use filters.
+
 ## MCP Resources
 
 In addition to tools, the gem registers MCP resources that AI clients can read directly:
@@ -239,13 +275,24 @@ In addition to tools, the gem registers MCP resources that AI clients can read d
 # config/initializers/rails_ai_context.rb
 RailsAiContext.configure do |config|
   # Introspector presets:
-  #   :standard — 8 core introspectors (default, fast)
+  #   :standard — 9 core introspectors (default, fast)
   #   :full     — all 26 introspectors (thorough)
   config.preset = :standard
 
   # Or cherry-pick on top of a preset:
   # config.introspectors += %i[views turbo auth api]
 
+  # Context mode for generated files (CLAUDE.md, .cursorrules, etc.)
+  # :compact — smart, ≤150 lines, references MCP tools (default)
+  # :full    — dumps everything into context files (good for small apps)
+  # config.context_mode = :compact
+
+  # Max lines for CLAUDE.md in compact mode
+  # config.claude_max_lines = 150
+
+  # Max response size for MCP tool results (safety net for large apps)
+  # config.max_tool_response_chars = 120_000
+
   # Exclude internal models from introspection
   config.excluded_models += %w[AdminUser InternalAuditLog]
 
@@ -289,13 +336,13 @@ This gives AI assistants context about your frontend JavaScript alongside your b
 
 ## Supported AI Assistants
 
-| AI Assistant | Context File | Format | Command |
-|--------------|-------------|--------|---------|
-| Claude Code | `CLAUDE.md` | Verbose + behavioral rules | `rails ai:context:claude` |
-| Cursor | `.cursorrules` | Compact imperative rules | `rails ai:context:cursor` |
-| Windsurf | `.windsurfrules` | Compact imperative rules | `rails ai:context:windsurf` |
-| GitHub Copilot | `.github/copilot-instructions.md` | Task-oriented GFM | `rails ai:context:copilot` |
-| JSON (generic) | `.ai-context.json` | Structured JSON | `rails ai:context:json` |
+| AI Assistant | Main File | Split Rules | Command |
+|--------------|-----------|------------|---------|
+| Claude Code | `CLAUDE.md` | `.claude/rules/*.md` | `rails ai:context:claude` |
+| Cursor | `.cursorrules` | `.cursor/rules/*.mdc` | `rails ai:context:cursor` |
+| Windsurf | `.windsurfrules` | `.windsurf/rules/*.md` | `rails ai:context:windsurf` |
+| GitHub Copilot | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | `rails ai:context:copilot` |
+| JSON (generic) | `.ai-context.json` | — | `rails ai:context:json` |
 
 ---
 
@@ -321,11 +368,12 @@ Introspectors that target frontend concerns (views, Turbo, Stimulus, assets) are
 
 | Command | Description |
 |---------|-------------|
-| `rails ai:context` | Generate all context files (skips unchanged) |
-| `rails ai:context:claude` | Generate CLAUDE.md only |
-| `rails ai:context:cursor` | Generate .cursorrules only |
-| `rails ai:context:windsurf` | Generate .windsurfrules only |
-| `rails ai:context:copilot` | Generate .github/copilot-instructions.md only |
+| `rails ai:context` | Generate all context files + split rules (skips unchanged) |
+| `rails ai:context:full` | Generate all files in full mode (dumps everything) |
+| `rails ai:context:claude` | Generate CLAUDE.md + .claude/rules/ |
+| `rails ai:context:cursor` | Generate .cursorrules + .cursor/rules/ |
+| `rails ai:context:windsurf` | Generate .windsurfrules + .windsurf/rules/ |
+| `rails ai:context:copilot` | Generate copilot-instructions.md + .github/instructions/ |
 | `rails ai:context:json` | Generate .ai-context.json only |
 | `rails ai:serve` | Start MCP server (stdio, for Claude Code) |
 | `rails ai:serve_http` | Start MCP server (HTTP, for remote clients) |
@@ -333,6 +381,8 @@ Introspectors that target frontend concerns (views, Turbo, Stimulus, assets) are
 | `rails ai:doctor` | Run diagnostics and report AI readiness score |
 | `rails ai:watch` | Watch for changes and auto-regenerate context files |
 
+> You can also override context mode via environment variable: `CONTEXT_MODE=full rails ai:context`
+
 > **zsh users:** The bracket syntax `rails ai:context_for[claude]` requires quoting in zsh (`rails 'ai:context_for[claude]'`). The named tasks above (`rails ai:context:claude`) work without quoting in any shell.
 
 ---

data/SECURITY.md

@@ -4,8 +4,9 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 0.5.x   | :white_check_mark: |
-| < 0.5   | :x:                |
+| 0.7.x   | :white_check_mark: |
+| 0.6.x   | :white_check_mark: |
+| < 0.6   | :x:                |
 
 ## Reporting a Vulnerability
 

data/demo_script.sh

@@ -8,7 +8,7 @@ echo 'Fetching gem metadata from https://rubygems.org...'
 sleep 0.3
 echo 'Resolving dependencies...'
 sleep 0.3
-echo 'Installing rails-ai-context 0.6.0'
+echo 'Installing rails-ai-context 0.7.0'
 echo ''
 sleep 1
 
@@ -46,12 +46,28 @@ printf '\033[1;36m$\033[0m rails ai:context\n'
 echo ''
 sleep 0.2
 echo '  ✅ CLAUDE.md'
-sleep 0.15
+sleep 0.1
+echo '  ✅ .claude/rules/rails-schema.md'
+sleep 0.1
+echo '  ✅ .claude/rules/rails-models.md'
+sleep 0.1
 echo '  ✅ .cursorrules'
-sleep 0.15
+sleep 0.1
+echo '  ✅ .cursor/rules/rails-project.mdc'
+sleep 0.1
+echo '  ✅ .cursor/rules/rails-models.mdc'
+sleep 0.1
+echo '  ✅ .cursor/rules/rails-controllers.mdc'
+sleep 0.1
 echo '  ✅ .windsurfrules'
-sleep 0.15
+sleep 0.1
+echo '  ✅ .windsurf/rules/rails-context.md'
+sleep 0.1
 echo '  ✅ .github/copilot-instructions.md'
+sleep 0.1
+echo '  ✅ .github/instructions/rails-models.instructions.md'
+sleep 0.1
+echo '  ✅ .github/instructions/rails-controllers.instructions.md'
 echo ''
 sleep 0.3
 printf '  \033[1;32mDone! Your AI assistants now understand your Rails app.\033[0m\n'

data/lib/rails_ai_context/introspectors/schema_introspector.rb

@@ -100,8 +100,8 @@ module RailsAiContext
       def current_schema_version
         if File.exist?(schema_file_path)
           content = File.read(schema_file_path)
-          match = content.match(/version:\s*(\d+)_?\d*/)
-          match ? match[1] : nil
+          match = content.match(/version:\s*([\d_]+)/)
+          match ? match[1].delete("_") : nil
         end
       end
 

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -22,7 +22,8 @@ module RailsAiContext
 
         files = {
           "rails-schema.md" => render_schema_reference,
-          "rails-models.md" => render_models_reference
+          "rails-models.md" => render_models_reference,
+          "rails-mcp-tools.md" => render_mcp_tools_reference
         }
 
         files.each do |filename, content|
@@ -92,6 +93,55 @@ module RailsAiContext
 
         lines.join("\n")
       end
+
+      def render_mcp_tools_reference # rubocop:disable Metrics/MethodLength
+        lines = [
+          "# MCP Tool Reference",
+          "",
+          "All introspection tools support a `detail` parameter:",
+          "- `summary` — names + counts (default limit: 50)",
+          "- `standard` — names + key details (default limit: 15, this is the default)",
+          "- `full` — everything including indexes, FKs (default limit: 5)",
+          "",
+          "## rails_get_schema",
+          "Params: `table`, `detail`, `limit`, `offset`, `format`",
+          "- `rails_get_schema(detail:\"summary\")` — all tables with column counts",
+          "- `rails_get_schema(table:\"users\")` — full detail for one table",
+          "- `rails_get_schema(detail:\"summary\", limit:20, offset:40)` — paginate",
+          "",
+          "## rails_get_model_details",
+          "Params: `model`, `detail`",
+          "- `rails_get_model_details(detail:\"summary\")` — list all model names",
+          "- `rails_get_model_details(model:\"User\")` — associations, validations, scopes, enums, callbacks",
+          "- `rails_get_model_details(detail:\"full\")` — all models with full association lists",
+          "",
+          "## rails_get_routes",
+          "Params: `controller`, `detail`, `limit`, `offset`",
+          "- `rails_get_routes(detail:\"summary\")` — route counts per controller",
+          "- `rails_get_routes(controller:\"users\")` — routes for one controller",
+          "- `rails_get_routes(detail:\"full\", limit:50)` — full table with route names",
+          "",
+          "## rails_get_controllers",
+          "Params: `controller`, `detail`",
+          "- `rails_get_controllers(detail:\"summary\")` — names + action counts",
+          "- `rails_get_controllers(controller:\"UsersController\")` — actions, filters, strong params",
+          "",
+          "## Other tools (no detail param)",
+          "- `rails_get_config` — cache store, session, timezone, middleware, initializers",
+          "- `rails_get_test_info` — test framework, factories/fixtures, CI config, coverage",
+          "- `rails_get_gems` — notable gems categorized by function",
+          "- `rails_get_conventions` — architecture patterns, directory structure",
+          "- `rails_search_code(pattern:\"regex\", file_type:\"rb\", max_results:20)` — codebase search",
+          "",
+          "## Workflow",
+          "1. Start with `detail:\"summary\"` to understand the landscape",
+          "2. Drill into specifics with filters (`table:`, `model:`, `controller:`)",
+          "3. Use `detail:\"full\"` only when you need indexes, FKs, constraints",
+          "4. Paginate large results with `limit` and `offset`"
+        ]
+
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/rails_ai_context/serializers/claude_serializer.rb

@@ -158,22 +158,50 @@ module RailsAiContext
         lines
       end
 
-      def render_mcp_guide
+      def render_mcp_guide # rubocop:disable Metrics/MethodLength
         [
-          "## MCP tools (live introspection)",
+          "## MCP Tool Reference",
           "",
-          "This project exposes MCP tools. Always use `detail:\"summary\"` first,",
-          "then drill into specifics with `detail:\"full\"` + a filter.",
+          "This project exposes live MCP tools. **Always start with `detail:\"summary\"`**,",
+          "then drill into specifics with a filter or `detail:\"full\"`.",
           "",
-          "- `rails_get_schema` — tables, columns, indexes, foreign keys",
-          "- `rails_get_model_details` — associations, validations, scopes, enums",
-          "- `rails_get_routes` — HTTP verbs, paths, controller actions",
-          "- `rails_get_controllers` — actions, filters, strong params",
-          "- `rails_get_config` — cache, session, timezone, middleware",
-          "- `rails_get_test_info` — framework, factories, CI config",
-          "- `rails_get_gems` — categorized gem analysis",
-          "- `rails_get_conventions` — architecture and design patterns",
-          "- `rails_search_code` — regex search across the codebase",
+          "### Detail levels (schema, routes, models, controllers)",
+          "",
+          "| Level | Returns | Default limit |",
+          "|-------|---------|---------------|",
+          "| `summary` | Names + counts | 50 |",
+          "| `standard` | Names + key details | 15 (default) |",
+          "| `full` | Everything (indexes, FKs, etc.) | 5 |",
+          "",
+          "### rails_get_schema",
+          "Params: `table`, `detail`, `limit`, `offset`, `format`",
+          "- `rails_get_schema(detail:\"summary\")` — all tables with column counts",
+          "- `rails_get_schema(table:\"users\")` — full detail for one table",
+          "- `rails_get_schema(detail:\"summary\", limit:20, offset:40)` — paginate",
+          "",
+          "### rails_get_model_details",
+          "Params: `model`, `detail`",
+          "- `rails_get_model_details(detail:\"summary\")` — list all model names",
+          "- `rails_get_model_details(model:\"User\")` — associations, validations, scopes, enums, callbacks",
+          "- `rails_get_model_details(detail:\"full\")` — all models with full association lists",
+          "",
+          "### rails_get_routes",
+          "Params: `controller`, `detail`, `limit`, `offset`",
+          "- `rails_get_routes(detail:\"summary\")` — route counts per controller",
+          "- `rails_get_routes(controller:\"users\")` — routes for one controller",
+          "- `rails_get_routes(detail:\"full\", limit:50)` — full table with route names",
+          "",
+          "### rails_get_controllers",
+          "Params: `controller`, `detail`",
+          "- `rails_get_controllers(detail:\"summary\")` — names + action counts",
+          "- `rails_get_controllers(controller:\"UsersController\")` — actions, filters, strong params",
+          "",
+          "### Other tools (no detail param)",
+          "- `rails_get_config` — cache store, session, timezone, middleware, initializers",
+          "- `rails_get_test_info` — test framework, factories/fixtures, CI config, coverage",
+          "- `rails_get_gems` — notable gems categorized by function (auth, background jobs, etc.)",
+          "- `rails_get_conventions` — architecture patterns, directory structure, config files",
+          "- `rails_search_code(pattern:\"regex\", file_type:\"rb\", max_results:20)` — ripgrep search",
           ""
         ]
       end

data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb

@@ -20,7 +20,8 @@ module RailsAiContext
 
         files = {
           "rails-models.instructions.md" => render_models_instructions,
-          "rails-controllers.instructions.md" => render_controllers_instructions
+          "rails-controllers.instructions.md" => render_controllers_instructions,
+          "rails-mcp-tools.instructions.md" => render_mcp_tools_instructions
         }
 
         files.each do |filename, content|
@@ -89,6 +90,54 @@ module RailsAiContext
 
         lines.join("\n")
       end
+
+      def render_mcp_tools_instructions # rubocop:disable Metrics/MethodLength
+        lines = [
+          "---",
+          "applyTo: \"**/*\"",
+          "---",
+          "",
+          "# MCP Tool Reference",
+          "",
+          "This project has MCP tools for live introspection.",
+          "**Start with `detail:\"summary\"`, then drill into specifics.**",
+          "",
+          "## Detail levels (schema, routes, models, controllers)",
+          "- `summary` — names + counts (default limit: 50)",
+          "- `standard` — names + key details (default limit: 15, this is the default)",
+          "- `full` — everything including indexes, FKs (default limit: 5)",
+          "",
+          "## rails_get_schema",
+          "Params: `table`, `detail`, `limit`, `offset`, `format`",
+          "- `rails_get_schema(detail:\"summary\")` — all tables with column counts",
+          "- `rails_get_schema(table:\"users\")` — full detail for one table",
+          "- `rails_get_schema(detail:\"summary\", limit:20, offset:40)` — paginate",
+          "",
+          "## rails_get_model_details",
+          "Params: `model`, `detail`",
+          "- `rails_get_model_details(detail:\"summary\")` — list all model names",
+          "- `rails_get_model_details(model:\"User\")` — full associations, validations, scopes",
+          "",
+          "## rails_get_routes",
+          "Params: `controller`, `detail`, `limit`, `offset`",
+          "- `rails_get_routes(detail:\"summary\")` — route counts per controller",
+          "- `rails_get_routes(controller:\"users\")` — routes for one controller",
+          "",
+          "## rails_get_controllers",
+          "Params: `controller`, `detail`",
+          "- `rails_get_controllers(detail:\"summary\")` — names + action counts",
+          "- `rails_get_controllers(controller:\"UsersController\")` — actions, filters, params",
+          "",
+          "## Other tools",
+          "- `rails_get_config` — cache store, session, timezone, middleware",
+          "- `rails_get_test_info` — test framework, factories/fixtures, CI config",
+          "- `rails_get_gems` — notable gems categorized by function",
+          "- `rails_get_conventions` — architecture patterns, directory structure",
+          "- `rails_search_code(pattern:\"regex\", file_type:\"rb\", max_results:20)` — codebase search"
+        ]
+
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/rails_ai_context/serializers/copilot_serializer.rb

@@ -81,20 +81,43 @@ module RailsAiContext
         end
 
         # MCP tools
-        lines << "## MCP tools"
+        lines << "## MCP Tool Reference"
         lines << ""
         lines << "This project has MCP tools for live introspection."
-        lines << "Call with `detail:\"summary\"` first, then filter for specifics."
+        lines << "**Always start with `detail:\"summary\"`, then drill into specifics.**"
         lines << ""
-        lines << "- `rails_get_schema` — database tables, columns, indexes, foreign keys"
-        lines << "- `rails_get_model_details` — associations, validations, scopes, enums"
-        lines << "- `rails_get_routes` — HTTP verbs, paths, controller actions"
-        lines << "- `rails_get_controllers` — actions, filters, strong params"
-        lines << "- `rails_get_config` — cache, session, middleware, timezone"
-        lines << "- `rails_get_test_info` — test framework, factories, CI"
-        lines << "- `rails_get_gems` — categorized gem analysis"
-        lines << "- `rails_get_conventions` — architecture patterns"
-        lines << "- `rails_search_code` — regex search across codebase"
+        lines << "### Detail levels (schema, routes, models, controllers)"
+        lines << "- `summary` — names + counts (default limit: 50)"
+        lines << "- `standard` — names + key details (default limit: 15, this is the default)"
+        lines << "- `full` — everything including indexes, FKs (default limit: 5)"
+        lines << ""
+        lines << "### rails_get_schema"
+        lines << "Params: `table`, `detail`, `limit`, `offset`, `format`"
+        lines << "- `rails_get_schema(detail:\"summary\")` — all tables with column counts"
+        lines << "- `rails_get_schema(table:\"users\")` — full detail for one table"
+        lines << "- `rails_get_schema(detail:\"summary\", limit:20, offset:40)` — paginate"
+        lines << ""
+        lines << "### rails_get_model_details"
+        lines << "Params: `model`, `detail`"
+        lines << "- `rails_get_model_details(detail:\"summary\")` — list all model names"
+        lines << "- `rails_get_model_details(model:\"User\")` — associations, validations, scopes, enums"
+        lines << ""
+        lines << "### rails_get_routes"
+        lines << "Params: `controller`, `detail`, `limit`, `offset`"
+        lines << "- `rails_get_routes(detail:\"summary\")` — route counts per controller"
+        lines << "- `rails_get_routes(controller:\"users\")` — routes for one controller"
+        lines << ""
+        lines << "### rails_get_controllers"
+        lines << "Params: `controller`, `detail`"
+        lines << "- `rails_get_controllers(detail:\"summary\")` — names + action counts"
+        lines << "- `rails_get_controllers(controller:\"UsersController\")` — actions, filters, params"
+        lines << ""
+        lines << "### Other tools"
+        lines << "- `rails_get_config` — cache store, session, timezone, middleware"
+        lines << "- `rails_get_test_info` — test framework, factories/fixtures, CI config"
+        lines << "- `rails_get_gems` — notable gems categorized by function"
+        lines << "- `rails_get_conventions` — architecture patterns, directory structure"
+        lines << "- `rails_search_code(pattern:\"regex\", file_type:\"rb\", max_results:20)` — codebase search"
         lines << ""
 
         # Conventions

data/lib/rails_ai_context/serializers/cursor_rules_serializer.rb

@@ -24,7 +24,8 @@ module RailsAiContext
         files = {
           "rails-project.mdc" => render_project_rule,
           "rails-models.mdc" => render_models_rule,
-          "rails-controllers.mdc" => render_controllers_rule
+          "rails-controllers.mdc" => render_controllers_rule,
+          "rails-mcp-tools.mdc" => render_mcp_tools_rule
         }
 
         files.each do |filename, content|
@@ -85,8 +86,8 @@ module RailsAiContext
         end
 
         lines << ""
-        lines << "Use MCP tools (rails_get_schema, rails_get_model_details, etc.) for details."
-        lines << "Call with detail:\"summary\" first, then drill into specifics."
+        lines << "MCP tools available — see rails-mcp-tools.mdc for full reference."
+        lines << "Always call with detail:\"summary\" first, then drill into specifics."
 
         lines.join("\n")
       end
@@ -152,6 +153,52 @@ module RailsAiContext
 
         lines.join("\n")
       end
+
+      # Always-on MCP tool reference
+      def render_mcp_tools_rule # rubocop:disable Metrics/MethodLength
+        lines = [
+          "---",
+          "description: \"MCP tool reference with parameters and examples\"",
+          "alwaysApply: true",
+          "---",
+          "",
+          "# MCP Tool Reference",
+          "",
+          "Detail levels: summary | standard (default) | full",
+          "",
+          "## rails_get_schema",
+          "Params: table, detail, limit, offset, format",
+          "- `rails_get_schema(detail:\"summary\")` — all tables with column counts",
+          "- `rails_get_schema(table:\"users\")` — full detail for one table",
+          "- `rails_get_schema(detail:\"summary\", limit:20, offset:40)` — paginate",
+          "",
+          "## rails_get_model_details",
+          "Params: model, detail",
+          "- `rails_get_model_details(detail:\"summary\")` — list model names",
+          "- `rails_get_model_details(model:\"User\")` — full detail",
+          "",
+          "## rails_get_routes",
+          "Params: controller, detail, limit, offset",
+          "- `rails_get_routes(detail:\"summary\")` — counts per controller",
+          "- `rails_get_routes(controller:\"users\")` — one controller",
+          "",
+          "## rails_get_controllers",
+          "Params: controller, detail",
+          "- `rails_get_controllers(detail:\"summary\")` — names + action counts",
+          "- `rails_get_controllers(controller:\"UsersController\")` — full detail",
+          "",
+          "## Other tools",
+          "- `rails_get_config` — cache, session, middleware",
+          "- `rails_get_test_info` — framework, factories, CI",
+          "- `rails_get_gems` — categorized gems",
+          "- `rails_get_conventions` — architecture patterns",
+          "- `rails_search_code(pattern:\"regex\", file_type:\"rb\", max_results:20)`",
+          "",
+          "Start with detail:\"summary\", then drill into specifics."
+        ]
+
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/rails_ai_context/serializers/rules_serializer.rb

@@ -74,17 +74,38 @@ module RailsAiContext
         end
 
         # MCP tools
-        lines << "## MCP tools"
-        lines << "Use detail:\"summary\" first, then drill into specifics."
-        lines << "- rails_get_schema — tables, columns, indexes, foreign keys"
-        lines << "- rails_get_model_details — associations, validations, scopes"
-        lines << "- rails_get_routes — HTTP verbs, paths, actions"
-        lines << "- rails_get_controllers — actions, filters, strong params"
-        lines << "- rails_get_config — cache, session, middleware"
-        lines << "- rails_get_test_info — framework, factories, CI"
-        lines << "- rails_get_gems — categorized gem analysis"
-        lines << "- rails_get_conventions — architecture patterns"
-        lines << "- rails_search_code — regex codebase search"
+        lines << "## MCP Tool Reference"
+        lines << ""
+        lines << "All introspection tools support detail:\"summary\"|\"standard\"|\"full\"."
+        lines << "Start with summary, drill into specifics with a filter."
+        lines << ""
+        lines << "### rails_get_schema"
+        lines << "Params: table, detail, limit, offset, format"
+        lines << "- `rails_get_schema(detail:\"summary\")` — all tables with column counts"
+        lines << "- `rails_get_schema(table:\"users\")` — full detail for one table"
+        lines << "- `rails_get_schema(detail:\"summary\", limit:20, offset:40)` — paginate"
+        lines << ""
+        lines << "### rails_get_model_details"
+        lines << "Params: model, detail"
+        lines << "- `rails_get_model_details(detail:\"summary\")` — list model names"
+        lines << "- `rails_get_model_details(model:\"User\")` — full associations, validations, scopes"
+        lines << ""
+        lines << "### rails_get_routes"
+        lines << "Params: controller, detail, limit, offset"
+        lines << "- `rails_get_routes(detail:\"summary\")` — route counts per controller"
+        lines << "- `rails_get_routes(controller:\"users\")` — routes for one controller"
+        lines << ""
+        lines << "### rails_get_controllers"
+        lines << "Params: controller, detail"
+        lines << "- `rails_get_controllers(detail:\"summary\")` — names + action counts"
+        lines << "- `rails_get_controllers(controller:\"UsersController\")` — full detail"
+        lines << ""
+        lines << "### Other tools"
+        lines << "- `rails_get_config` — cache, session, middleware, timezone"
+        lines << "- `rails_get_test_info` — framework, factories, CI"
+        lines << "- `rails_get_gems` — categorized gem analysis"
+        lines << "- `rails_get_conventions` — architecture patterns"
+        lines << "- `rails_search_code(pattern:\"regex\", file_type:\"rb\", max_results:20)`"
         lines << ""
 
         # Rules

data/lib/rails_ai_context/serializers/windsurf_rules_serializer.rb

@@ -21,7 +21,8 @@ module RailsAiContext
         skipped = []
 
         files = {
-          "rails-context.md" => render_context_rule
+          "rails-context.md" => render_context_rule,
+          "rails-mcp-tools.md" => render_mcp_tools_rule
         }
 
         files.each do |filename, content|
@@ -47,6 +48,37 @@ module RailsAiContext
         # Reuse WindsurfSerializer content
         WindsurfSerializer.new(context).call
       end
+
+      def render_mcp_tools_rule # rubocop:disable Metrics/MethodLength
+        lines = [
+          "# MCP Tool Reference",
+          "",
+          "Detail levels: summary | standard (default) | full",
+          "",
+          "## Schema",
+          "rails_get_schema(table:\"name\"|detail:\"summary\"|limit:N|offset:N)",
+          "",
+          "## Models",
+          "rails_get_model_details(model:\"Name\"|detail:\"summary\")",
+          "",
+          "## Routes",
+          "rails_get_routes(controller:\"name\"|detail:\"summary\"|limit:N|offset:N)",
+          "",
+          "## Controllers",
+          "rails_get_controllers(controller:\"Name\"|detail:\"summary\")",
+          "",
+          "## Other",
+          "- rails_get_config — cache, session, middleware",
+          "- rails_get_test_info — framework, factories, CI",
+          "- rails_get_gems — categorized gems",
+          "- rails_get_conventions — architecture patterns",
+          "- rails_search_code(pattern:\"regex\"|file_type:\"rb\"|max_results:N)",
+          "",
+          "Start with detail:\"summary\", then drill into specifics."
+        ]
+
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/rails_ai_context/serializers/windsurf_serializer.rb

@@ -71,17 +71,19 @@ module RailsAiContext
           end
         end
 
-        # MCP tools
-        lines << "# MCP tools available"
-        lines << "Use detail:\"summary\" first, then drill into specifics."
-        lines << "- rails_get_schema — tables, columns, indexes"
-        lines << "- rails_get_model_details — associations, validations"
-        lines << "- rails_get_routes — HTTP verbs, paths, actions"
-        lines << "- rails_get_controllers — actions, filters, params"
-        lines << "- rails_search_code — regex codebase search"
+        # MCP tools — compact but complete (character budget is tight)
+        lines << "# MCP Tools (detail:\"summary\"|\"standard\"|\"full\")"
+        lines << "- rails_get_schema(table:\"name\"|detail:\"summary\"|limit:N|offset:N)"
+        lines << "- rails_get_model_details(model:\"Name\"|detail:\"summary\")"
+        lines << "- rails_get_routes(controller:\"name\"|detail:\"summary\"|limit:N|offset:N)"
+        lines << "- rails_get_controllers(controller:\"Name\"|detail:\"summary\")"
+        lines << "- rails_get_config — cache, session, middleware"
+        lines << "- rails_get_test_info — framework, factories, CI"
+        lines << "- rails_get_gems — categorized gems"
+        lines << "- rails_get_conventions — architecture patterns"
+        lines << "- rails_search_code(pattern:\"regex\"|file_type:\"rb\"|max_results:N)"
+        lines << "Start with detail:\"summary\", then drill into specifics."
         lines << ""
-
-        # Conventions
         lines << "# Rules"
         lines << "- Follow existing patterns"
         lines << "- Check schema via MCP before writing migrations"

data/lib/rails_ai_context/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - crisnahine
@@ -265,8 +265,8 @@ metadata:
 post_install_message: |
   rails-ai-context installed! Quick start:
     rails generate rails_ai_context:install
-    rails ai:context         # generate all context files
-    rails ai:context:claude  # generate CLAUDE.md only (zsh-friendly)
+    rails ai:context         # generate context files (compact mode)
+    rails ai:context:full    # full dump (good for small apps)
     rails ai:serve           # start MCP server for Claude Code / Cursor
 rdoc_options: []
 require_paths: