rails-ai-context 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4dfcbb5d44af0ed1defb25731f71a4777f9e0905dd662f0e7fa3ff83a870f02
-  data.tar.gz: 8321f5166e78daa800a68c34f05b4b30eb83c6096a43d87916463d4ff7f07ee2
+  metadata.gz: af24e6340b8328b0526c9f030d60b495f4cb1e7130b7f16cadd039e2b9912aab
+  data.tar.gz: e74d337f614f853fec1bacaff748bea4b212ed96034c22b5fd3d75326da6fc13
 SHA512:
-  metadata.gz: e66d58d898c8136321ba0d7bd3e188a446f219746bbb2073f73bf9b270b7e71ff0e776afa568ab91f9abe4343e9957b066384c63d0571d68592643bf740811ea
-  data.tar.gz: fcfc393aa754c35ee729157322e58fd03d47649ddd4c1e4d68ff8e6f40c4498ab2c9375381c28e10b0016880cf0672ed030de927d432762651b32493e7a64889
+  metadata.gz: 9e8d9261310e038cce1cc20ba21d81d203eec2d813dcf318aa3f2071da646a67dc11fd812671a0d982d6d0d234ed84c2079144be3b62863b311e09d0b12181f9
+  data.tar.gz: 3f6001ba2d788b76e4a6e7b576a9447e7eed91df1a0b689dba679a3c6fbd876db1278e7ebd70637b35bedb01e2e77b1546cf3b96d8c5d37536f1f053fd35f9d3

data/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.1.0] — 2026-03-29
+
+### Added
+- New `rails_get_frontend_stack` tool: detects React/Vue/Svelte/Angular, Inertia/react-rails mounting, state management, TypeScript config, monorepo layout, package manager
+- New `FrontendFrameworkIntrospector`: parses package.json (JSON.parse with BOM-safe reading), config/vite.json, config/shakapacker.yml, tsconfig.json
+- Frontend framework detection covers patterns 3 (hybrid SPA), 4 (API+SPA), and 7 (Turbo Native)
+- API introspector: OpenAPI/Swagger spec detection, CORS config parsing, API codegen tool detection (openapi-typescript, graphql-codegen, orval)
+- Auth introspector: JWT strategy (devise-jwt, Doorkeeper config), HTTP token auth detection
+- Turbo introspector: Turbo Native detection (turbo_native_app?, native navigation patterns, native conditionals in views)
+- Gem introspector: 6 new notable gems (devise-jwt, rswag-api, rswag-ui, grape-swagger, apipie-rails, hotwire-native-rails)
+- Optional config: `frontend_paths`, `mobile_paths` (auto-detected if nil, user override for edge cases)
+- Install generator: re-install now updates `ai_tools` and `tool_mode` selections, adds missing config sections without removing existing settings
+- Install generator: prompts to remove generated files when AI tools are deselected (per-tool chooser)
+- `rails ai:context:cursor` (and other format tasks) now auto-adds the format to `config.ai_tools`
+- CLI tool_runner: warns on invalid enum values instead of silent fallback
+
+### Fixed
+- `analyze_feature` crash on nil/empty input — now returns helpful prompt
+- `analyze_feature` with nonexistent feature — returns clean "no match" instead of scaffolded empty sections
+- `migration_advisor` crash on empty/invalid action — now validates with "Did you mean?" suggestions
+- `migration_advisor` generates broken SQL with empty table/column — now validates required params
+- `migration_advisor` doesn't normalize table names — "Cook" now auto-resolves to "cooks"
+- `migration_advisor` no duplicate column/index detection — now warns on existing columns, indexes, and FKs
+- `migration_advisor` no nonexistent column detection — now warns on remove/rename/change_type/add_index for missing columns
+- `edit_context` "File not found" with no hint — now suggests full path with "Did you mean?"
+- `performance_check` model filter fails for multi-word models — "BrandProfile" now resolves to "brand_profiles"
+- `performance_check` unknown model silently ignored — now returns "not found" with suggestions
+- `turbo_map` stream filter misses dynamic broadcasts — multi-line call handling + snippet fallback + fuzzy prefix matching
+- `turbo_map` controller filter misses job broadcasts — now includes broadcasts matching filtered subscriptions' streams
+- `security_scan` wrong check name examples — added CHECK_ALIASES mapping (CheckXSS → CheckCrossSiteScripting, sql → CheckSQL, etc.)
+- `search_code` unknown match_type silently ignored — now returns error with valid values
+- `validate` unknown level silently ignored — now returns error with valid values
+- `get_view` no "Did you mean?" on wrong controller — now uses `find_closest_match`
+- `get_context` plural model name ("Cooks") produces mixed output — now normalizes via singularize/classify, fails fast when not found
+- `component_catalog` specific component returns generic "no components" — now acknowledges the input
+- `stimulus` doesn't strip `_controller` suffix — now auto-strips for lookup
+- `controller_introspector_spec` rate_limit test crashes on Rails 7.1 — split into source-parsing test (no class loading)
+
+### Changed
+- Full preset: 31 → 32 introspectors (added :frontend_frameworks)
+- Tool count: 29 → 30
+- Test count: 817 → 893
+- Install generator always writes `config.ai_tools` and `config.tool_mode` uncommented for re-install detection
+
 ## [4.0.0] — 2026-03-26
 
 ### Added

data/CLAUDE.md

@@ -8,8 +8,8 @@ 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/` — 32 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)
-- `lib/rails_ai_context/tools/` — 29 MCP tools using the official mcp SDK
+- `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/` — 30 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/resources.rb` — MCP resources (static data AI clients read directly)
@@ -34,28 +34,30 @@ 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` (31) default, `:standard` (14 core) for lightweight usage
+10. **Introspector presets** — `:full` (32) default, `:standard` (14 core) 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 29 built-in tools
+16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 30 built-in tools
 17. **Design system extraction** — view templates analyzed for canonical examples, color palette, typography, responsive patterns, interactive states, dark mode
 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 29 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 30 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 reversibility warnings and affected model detection via `rails_migration_advisor`
+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
 
 ## Testing
 
 ```bash
-bundle exec rspec           # Run specs (806 examples)
+bundle exec rspec           # Run specs (893 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/     # 32 introspectors (schema, models, routes, etc.)
-├── tools/             # 29 MCP tools with detail levels and pagination
+├── introspectors/     # 33 introspectors (schema, models, routes, etc.)
+├── tools/             # 30 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

@@ -9,14 +9,14 @@
 
 **Works with:** Claude Code • Cursor • GitHub Copilot • OpenCode • Any terminal
 
-> Built by a Rails developer with 10+ years of production experience. AI assisted — the same way it assists me shipping features at work. I designed the architecture, made every decision, reviewed every line, and wrote 806 tests. This gem exists because I understand Rails deeply enough to know exactly what AI agents get wrong and what context they need to get it right.
+> Built by a Rails developer with 10+ years of production experience. AI assisted — the same way it assists me shipping features at work. I designed the architecture, made every decision, reviewed every line, and wrote 893 tests. This gem exists because I understand Rails deeply enough to know exactly what AI agents get wrong and what context they need to get it right.
 
 ```bash
 gem "rails-ai-context", group: :development
 rails generate rails_ai_context:install
 ```
 
-That's it. Your AI now has 29 tools that understand your entire Rails app — via MCP server or CLI. Zero config.
+That's it. Your AI now has 30 tools that understand your entire Rails app — via MCP server or CLI. Zero config.
 
 > **[Full Guide →](docs/GUIDE.md)** — every command, every parameter, every configuration option.
 
@@ -46,7 +46,7 @@ rails 'ai:tool[schema]' table=users
 rails 'ai:tool[analyze_feature]' feature=billing
 ```
 
-Same 29 tools. Same output. AI agents run these as shell commands. **Works in any terminal, any AI tool, any workflow.** No MCP client required.
+Same 30 tools. Same output. AI agents run these as shell commands. **Works in any terminal, any AI tool, any workflow.** No MCP client required.
 
 ---
 
@@ -170,7 +170,7 @@ Tested on a real Rails 8 app (5 models, 19 controllers, 95 routes):
 
 ---
 
-## 29 Tools
+## 30 Tools
 
 Every tool is **read-only** and returns structured, token-efficient data.
 
@@ -214,6 +214,8 @@ Every tool is **read-only** and returns structured, token-efficient data.
 | `performance_check` | `rails_performance_check` | `rails 'ai:tool[performance_check]'` | N+1 risks, missing indexes, counter_cache, eager load candidates |
 | `dependency_graph` | `rails_dependency_graph` | `rails 'ai:tool[dependency_graph]'` | Model/service dependency graph in Mermaid or text format |
 | `migration_advisor` | `rails_migration_advisor` | `rails 'ai:tool[migration_advisor]'` | Migration code generation with reversibility + affected models |
+| **Frontend** | | | |
+| `get_frontend_stack` | `rails_get_frontend_stack` | `rails 'ai:tool[frontend_stack]'` | React/Vue/Svelte/Angular, Inertia, TypeScript, package manager |
 
 > **[Full parameter docs →](docs/GUIDE.md)**
 
@@ -226,7 +228,7 @@ Every tool is **read-only** and returns structured, token-efficient data.
 │  Your Rails App                                          │
 │  models + schema + routes + controllers + views + jobs   │
 └────────────────────────┬────────────────────────────────┘
-                         │ introspects (32 introspectors)
+                         │ introspects (33 introspectors)
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │  rails-ai-context                                        │
@@ -236,7 +238,7 @@ Every tool is **read-only** and returns structured, token-efficient data.
          ▼                  ▼              ▼
 ┌──────────────────┐ ┌────────────┐ ┌────────────────────┐
 │  Static Files     │ │  MCP Server │ │  CLI Tools          │
-│  CLAUDE.md        │ │  29 tools   │ │  Same 29 tools      │
+│  CLAUDE.md        │ │  30 tools   │ │  Same 30 tools      │
 │  .cursor/rules/   │ │  stdio/HTTP │ │  No server needed   │
 │  .github/instr... │ │  .mcp.json  │ │  rails 'ai:tool[X]' │
 └──────────────────┘ └────────────┘ └────────────────────┘
@@ -272,7 +274,7 @@ MCP auto-discovery: `.mcp.json` is detected automatically by Claude Code and Cur
 | Command | What it does |
 |---------|-------------|
 | `rails ai:context` | Generate context files for your AI tools |
-| `rails 'ai:tool[NAME]'` | Run any of the 29 tools from the CLI |
+| `rails 'ai:tool[NAME]'` | Run any of the 30 tools from the CLI |
 | `rails ai:tool` | List all available tools with short names |
 | `rails ai:serve` | Start MCP server (stdio) |
 | `rails ai:doctor` | Diagnostics + AI readiness score |
@@ -292,7 +294,7 @@ RailsAiContext.configure do |config|
   # Tool mode: :mcp (default, MCP + CLI fallback) or :cli (CLI only)
   # config.tool_mode = :mcp
 
-  # Presets: :full (31 introspectors, default) or :standard (14 core)
+  # Presets: :full (32 introspectors, default) or :standard (14 core)
   # config.preset = :full
 
   # Exclude models from introspection
@@ -310,7 +312,7 @@ end
 |--------|---------|-------------|
 | **Presets & Introspectors** | | |
 | `preset` | `:full` | Introspector preset (`:full` or `:standard`) |
-| `introspectors` | 31 (full) | Array of introspector symbols |
+| `introspectors` | 32 (full) | Array of introspector symbols |
 | **Context Generation** | | |
 | `context_mode` | `:compact` | `:compact` (≤150 lines) or `:full` (dump everything) |
 | `claude_max_lines` | `150` | Max lines for CLAUDE.md in compact mode |
@@ -345,7 +347,7 @@ end
 ```bash
 git clone https://github.com/crisnahine/rails-ai-context.git
 cd rails-ai-context && bundle install
-bundle exec rspec       # 806 examples
+bundle exec rspec       # 893 examples
 bundle exec rubocop     # Lint
 ```
 

data/SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 4.1.x   | :white_check_mark: |
 | 4.0.x   | :white_check_mark: |
 | 3.1.x   | :white_check_mark: |
 | 3.0.x   | :x:                |
@@ -24,7 +25,7 @@ If you discover a security vulnerability in rails-ai-context, please report it r
 
 ## Security Design
 
-- All 29 MCP tools are **read-only** and never modify your application or database.
+- All 30 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

@@ -252,7 +252,7 @@ rails ai:context:claude           # Use this instead (no quoting needed)
 
 ## CLI Tools
 
-All 29 MCP tools can be run directly from the terminal — no MCP server or AI client needed.
+All 30 MCP tools can be run directly from the terminal — no MCP server or AI client needed.
 
 ### Rake
 
@@ -316,7 +316,7 @@ The `tool_mode` is selected during `rails generate rails_ai_context:install`.
 
 ## MCP Tools — Full Reference
 
-All 29 tools are **read-only** and **idempotent** — they never modify your application or database.
+All 30 tools are **read-only** and **idempotent** — they never modify your application or database.
 
 ### rails_get_schema
 
@@ -1117,7 +1117,7 @@ RailsAiContext.configure do |config|
 end
 ```
 
-Both transports are **read-only** — they expose the same 29 tools and never modify your app.
+Both transports are **read-only** — they expose the same 30 tools and never modify your app.
 
 ---
 
@@ -1128,7 +1128,7 @@ Both transports are **read-only** — they expose the same 29 tools and never mo
 RailsAiContext.configure do |config|
   # --- Introspectors ---
 
-  # Presets: :full (31 introspectors, default) or :standard (14 core)
+  # Presets: :full (32 introspectors, default) or :standard (14 core)
   config.preset = :full
 
   # Cherry-pick on top of a preset
@@ -1243,7 +1243,7 @@ end
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `preset` | Symbol | `:full` | Introspector preset (`:full` or `:standard`) |
-| `introspectors` | Array | 28 (full preset) | Which introspectors to run |
+| `introspectors` | Array | 32 (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 |
@@ -1321,7 +1321,7 @@ Core Rails structure only. Use `config.preset = :standard` for a lighter footpri
 | `design_tokens` | Auto-detects CSS framework (Tailwind v3/v4, Bootstrap, Sass, plain CSS) and extracts design tokens from config files and built CSS. |
 | `components` | ViewComponent/Phlex components: props, slots, previews, sidecar assets, usage examples. |
 
-### Full preset (31 introspectors) — default
+### Full preset (32 introspectors) — default
 
 Includes all standard introspectors plus:
 
@@ -1344,6 +1344,7 @@ Includes all standard introspectors plus:
 | `multi_database` | Multiple databases, replicas, sharding config, model-specific `connects_to` declarations. database.yml parsing fallback. |
 | `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. |
+| `frontend_frameworks` | Frontend JS framework detection (React/Vue/Svelte/Angular), mounting strategy (Inertia/react-rails), TypeScript config, state management, package manager. |
 | `database_stats` | PostgreSQL approximate row counts via `pg_stat_user_tables`. **Opt-in only** — not in any preset, add manually: `config.introspectors += [:database_stats]`. |
 
 ### Using the standard preset

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

@@ -16,6 +16,14 @@ module RailsAiContext
         "4" => { key: :opencode, name: "OpenCode",        files: "AGENTS.md",                                          format: :opencode }
       }.freeze
 
+      # Files/dirs generated per AI tool format — used for cleanup on tool removal
+      FORMAT_PATHS = {
+        claude:   %w[CLAUDE.md .claude/rules],
+        cursor:   %w[.cursor/rules],
+        copilot:  %w[.github/copilot-instructions.md .github/instructions],
+        opencode: %w[AGENTS.md app/models/AGENTS.md app/controllers/AGENTS.md]
+      }.freeze
+
       def select_ai_tools
         say ""
         say "Which AI tools do you use? (select all that apply)", :yellow
@@ -45,6 +53,56 @@ module RailsAiContext
         say "Selected: #{selected_names.join(', ')}", :green
       end
 
+      def cleanup_removed_tools
+        @previous_formats = read_previous_ai_tools
+        return unless @previous_formats&.any?
+
+        removed = @previous_formats - @selected_formats
+        return if removed.empty?
+
+        say ""
+        say "These AI tools were removed from your selection:", :yellow
+        removed.each_with_index do |fmt, idx|
+          tool = AI_TOOLS.values.find { |t| t[:format] == fmt }
+          say "  #{idx + 1}. #{tool[:name]} (#{tool[:files]})" if tool
+        end
+        say ""
+
+        say "Remove their generated files?", :yellow
+        say "  y — remove all listed above"
+        say "  n — keep all (default)"
+        say "  1,2 — remove only specific ones by number"
+        say ""
+
+        input = ask("Enter choice:").strip.downcase
+        return if input.empty? || input == "n" || input == "no"
+
+        to_remove = if input == "y" || input == "yes" || input == "a"
+          removed
+        else
+          nums = input.split(/[\s,]+/).filter_map { |n| n.to_i - 1 }
+          nums.filter_map { |i| removed[i] if i >= 0 && i < removed.size }
+        end
+
+        return if to_remove.empty?
+
+        to_remove.each do |fmt|
+          tool = AI_TOOLS.values.find { |t| t[:format] == fmt }
+          paths = FORMAT_PATHS[fmt] || []
+          paths.each do |rel_path|
+            full = Rails.root.join(rel_path)
+            if File.directory?(full)
+              FileUtils.rm_rf(full)
+              say "  Removed #{rel_path}/", :red
+            elsif File.exist?(full)
+              FileUtils.rm_f(full)
+              say "  Removed #{rel_path}", :red
+            end
+          end
+          say "  ✓ #{tool[:name]} files removed", :green if tool
+        end
+      end
+
       def select_tool_mode
         say ""
         say "Do you also want MCP server support?", :yellow
@@ -95,39 +153,28 @@ module RailsAiContext
         end
       end
 
-      def create_initializer
-        tools_line = if @selected_formats.size == AI_TOOLS.size
-          "  # config.ai_tools = %i[claude cursor copilot opencode]  # default: all"
-        else
-          "  config.ai_tools = %i[#{@selected_formats.join(' ')}]"
-        end
-
-        tool_mode_line = if @tool_mode == :cli
-          "  config.tool_mode = :cli    # CLI only (no MCP server needed)"
-        else
-          "  # config.tool_mode = :mcp  # MCP primary + CLI fallback (default)"
-        end
-
-        create_file "config/initializers/rails_ai_context.rb", <<~RUBY
-          # frozen_string_literal: true
-
-          RailsAiContext.configure do |config|
+      # All config sections with their marker comment and content.
+      # Each section is identified by its marker (e.g., "── AI Tools ──").
+      # On re-install, only sections NOT already present are appended.
+      CONFIG_SECTIONS = {
+        "AI Tools" => <<~SECTION,
             # ── AI Tools ──────────────────────────────────────────────────────
             # Which AI tools to generate context files for (selected during install)
             # Run `rails generate rails_ai_context:install` to change selection
-          #{tools_line}
+            # config.ai_tools = %i[claude cursor copilot opencode]  # default: all
 
             # Tool invocation mode:
             #   :mcp — MCP primary + CLI fallback (default, requires `rails ai:serve`)
             #   :cli — CLI only (no MCP server needed, uses `rails 'ai:tool[NAME]'`)
-          #{tool_mode_line}
-
+            # config.tool_mode = :mcp
+        SECTION
+        "Introspection" => <<~SECTION,
             # ── Introspection ─────────────────────────────────────────────────
             # Introspector preset:
-            #   :full     — all 28 introspectors (default)
-            #   :standard — 13 core introspectors (schema, models, routes, jobs, gems,
+            #   :full     — all #{RailsAiContext::Configuration::PRESETS[:full].size} introspectors (default)
+            #   :standard — #{RailsAiContext::Configuration::PRESETS[:standard].size} core introspectors (schema, models, routes, jobs, gems,
             #               conventions, controllers, tests, migrations, stimulus,
-            #               view_templates, design_tokens, config)
+            #               view_templates, design_tokens, config, components)
             # config.preset = :full
 
             # Context mode: :compact (default, ≤150 lines) or :full (dumps everything)
@@ -139,7 +186,8 @@ 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
-
+        SECTION
+        "Models & Filtering" => <<~SECTION,
             # ── Models & Filtering ────────────────────────────────────────────
             # Models to exclude from introspection
             # config.excluded_models += %w[AdminUser InternalThing]
@@ -149,7 +197,8 @@ module RailsAiContext
 
             # Route prefixes to hide with app_only filter
             # config.excluded_route_prefixes += %w[sidekiq/]
-
+        SECTION
+        "MCP Server" => <<~SECTION,
             # ── MCP Server ────────────────────────────────────────────────────
             # Cache TTL in seconds for introspection data
             # config.cache_ttl = 60
@@ -167,7 +216,8 @@ module RailsAiContext
             # config.auto_mount = false
             # config.http_path = "/mcp"
             # config.http_port = 6029
-
+        SECTION
+        "File Size Limits" => <<~SECTION,
             # ── File Size Limits ──────────────────────────────────────────────
             # Increase for larger projects
             # config.max_file_size = 5_000_000         # Per-file read (5MB)
@@ -177,32 +227,160 @@ module RailsAiContext
             # config.max_view_file_size = 1_000_000    # Per-view file (1MB)
             # config.max_search_results = 200          # Max search results per call
             # config.max_validate_files = 50           # Max files per validate call
-
+        SECTION
+        "Extensibility" => <<~SECTION,
             # ── Extensibility ─────────────────────────────────────────────────
-            # Register additional MCP tool classes alongside the 25 built-in tools
+            # Register additional MCP tool classes alongside the #{RailsAiContext::Server::TOOLS.size} built-in tools
             # config.custom_tools = [MyApp::CustomTool]
 
             # Exclude specific built-in tools by name
             # config.skip_tools = %w[rails_security_scan]
-
+        SECTION
+        "Security" => <<~SECTION,
             # ── Security ──────────────────────────────────────────────────────
             # Paths excluded from code search
             # config.excluded_paths += %w[vendor/cache]
 
             # File patterns blocked from search and read tools
             # config.sensitive_patterns += %w[config/secrets.yml]
-
+        SECTION
+        "Search" => <<~SECTION,
             # ── Search ────────────────────────────────────────────────────────
             # File extensions for fallback search (when ripgrep unavailable)
             # config.search_extensions = %w[rb js erb yml yaml json ts tsx vue svelte haml slim]
 
             # Where to look for concern source files
             # config.concern_paths = %w[app/models/concerns app/controllers/concerns]
+        SECTION
+        "Frontend" => <<~SECTION
+            # ── 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
+
+      def create_initializer
+        initializer_path = "config/initializers/rails_ai_context.rb"
+        full_path = Rails.root.join(initializer_path)
+
+        if File.exist?(full_path)
+          update_existing_initializer(full_path)
+        else
+          create_new_initializer(initializer_path)
+        end
+      end
+
+      no_tasks do
+      def create_new_initializer(path)
+        # Always write uncommented so re-install can detect previous selection
+        tools_line = "  config.ai_tools = %i[#{@selected_formats.join(' ')}]"
+
+        tool_mode_line = if @tool_mode == :cli
+          "  config.tool_mode = :cli    # CLI only (no MCP server needed)"
+        else
+          "  config.tool_mode = :mcp   # MCP primary + CLI fallback"
+        end
+
+        content = "# frozen_string_literal: true\n\nRailsAiContext.configure do |config|\n"
+
+        # AI Tools section gets dynamic values from user selection
+        content += <<~SECTION
+            # ── AI Tools ──────────────────────────────────────────────────────
+            # Which AI tools to generate context files for (selected during install)
+            # Run `rails generate rails_ai_context:install` to change selection
+          #{tools_line}
+
+            # Tool invocation mode:
+            #   :mcp — MCP primary + CLI fallback (default, requires `rails ai:serve`)
+            #   :cli — CLI only (no MCP server needed, uses `rails 'ai:tool[NAME]'`)
+          #{tool_mode_line}
+
+        SECTION
+
+        # All remaining sections use defaults (commented out)
+        CONFIG_SECTIONS.each do |name, section_content|
+          next if name == "AI Tools" # already added with dynamic values
+          content += section_content + "\n"
+        end
+
+        content += "end\n"
+
+        create_file path, content
+        say "Created #{path} with all #{CONFIG_SECTIONS.size} config sections", :green
+      end
+
+      def update_existing_initializer(full_path)
+        existing = File.read(full_path)
+        changes = []
+
+        # 1. Update ai_tools selection if user picked new tools
+        existing, changed = update_config_line(existing, "config.ai_tools", build_ai_tools_line)
+        changes << "ai_tools" if changed
+
+        # 2. Update tool_mode if user picked a new mode
+        existing, changed = update_config_line(existing, "config.tool_mode", build_tool_mode_line)
+        changes << "tool_mode" if changed
+
+        # 3. Add any missing config sections
+        CONFIG_SECTIONS.each do |name, section_content|
+          marker = "── #{name}"
+          next if existing.include?(marker)
+
+          insert_point = existing.rindex(/^end\b/)
+          if insert_point
+            existing = existing.insert(insert_point, "\n#{section_content}\n")
+            changes << "section: #{name}"
           end
-        RUBY
+        end
+
+        if changes.any?
+          File.write(full_path, existing)
+          say "Updated #{full_path.relative_path_from(Rails.root)}: #{changes.join(', ')}", :green
+        else
+          say "#{full_path.relative_path_from(Rails.root)} is up to date — no changes needed", :green
+        end
+      end
+
+      # Replace or uncomment a config line. Returns [new_content, changed?]
+      def update_config_line(content, key, new_line)
+        # Match both commented and uncommented versions of this config key
+        pattern = /^[ \t]*#?\s*#{Regexp.escape(key)}\s*=.*$/
+        if content.match?(pattern)
+          updated = content.sub(pattern, new_line)
+          [ updated, updated != content ]
+        else
+          # Key not found at all — don't add (it's in a section that will be added)
+          [ content, false ]
+        end
+      end
+
+      def build_ai_tools_line
+        # Always write uncommented so re-install can detect previous selection
+        "  config.ai_tools = %i[#{@selected_formats.join(' ')}]"
+      end
+
+      def build_tool_mode_line
+        if @tool_mode == :cli
+          "  config.tool_mode = :cli    # CLI only (no MCP server needed)"
+        else
+          "  config.tool_mode = :mcp   # MCP primary + CLI fallback"
+        end
+      end
+
+      def read_previous_ai_tools
+        init_path = Rails.root.join("config/initializers/rails_ai_context.rb")
+        return nil unless File.exist?(init_path)
+
+        content = File.read(init_path)
+        match = content.match(/^\s*config\.ai_tools\s*=\s*%i\[([^\]]*)\]/)
+        return nil unless match
 
-        say "Created config/initializers/rails_ai_context.rb", :green
+        match[1].split.map(&:to_sym)
+      rescue
+        nil
       end
+      end # no_tasks
 
       def add_to_gitignore
         gitignore = Rails.root.join(".gitignore")
@@ -258,9 +436,9 @@ module RailsAiContext
         say ""
         say "Commands:", :yellow
         say "  rails ai:context         # Regenerate context files"
-        say "  rails 'ai:tool[schema]'    # Run any of the 25 tools from CLI"
+        say "  rails 'ai:tool[schema]'    # Run any of the 30 tools from CLI"
         if @tool_mode == :mcp
-          say "  rails ai:serve           # Start MCP server (25 live tools)"
+          say "  rails ai:serve           # Start MCP server (30 live tools)"
         end
         say "  rails ai:doctor          # Check AI readiness"
         say "  rails ai:inspect         # Print introspection summary"

data/lib/rails_ai_context/cli/tool_runner.rb

@@ -249,6 +249,7 @@ module RailsAiContext
           if matched
             kwargs[key] = matched
           else
+            $stderr.puts "Warning: '#{value}' is not a valid value for #{key}. Valid: #{prop[:enum].join(', ')}. Using default."
             kwargs.delete(key)
           end
         end