rails-ai-context 5.26.0 → 5.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5554194142695cce91ac263b45bcd692fdfa2fe80d85ddbfe70c52a85eab9087
-  data.tar.gz: 1b040d294942a14f92a5b86b58b185f3c15e840ad9976d2e3b90a888de66b6e8
+  metadata.gz: 44038590682c51bc7722a4a5b587ee31b5b78f3842575b6386390a584038b81e
+  data.tar.gz: 4c7de07da1f44144291ba86e9bfc34ab3a3da893c0a159b8cfe99de284d3d3be
 SHA512:
-  metadata.gz: dc5ee392e5faa628133f7abdf33b1fd655c167f4e7cfbf2fd2dff21b9047dff2648b89e4e5fa3be07ca6fc98a93084e30cf9954e06f588ab43ab40dbf6abc832
-  data.tar.gz: 71dda3b0936a89dce1c56b6b6f5889762b0f0ce2265a3ec42eab7c824155be84728de8ae2da9104bd7653a9e26568a01858fb6207ca705fd66dfdb4fcb52c932
+  metadata.gz: b581d96cb4ff655823a103c21527a53ddb71c3cb36d644a59485a796693001e247f6480b381d1f54ea8ec0995e175aa0389109fe1155bfbeea2dfeefd5566d9c
+  data.tar.gz: 61c4aa682dd49afaf780652300f41de2216a0bfbe0b6ed7e6ec188237c63eade5036fe2051ba6771f89e96803a0971811230e532a7c623d7a25d0bfb1f069df8

data/CHANGELOG.md

@@ -5,6 +5,146 @@ 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.27.0] - 2026-09-22
+
+### Added
+
+- **MCP-only install (`--mcp-only`, `config.context_files`).** Some apps keep
+  their own `CLAUDE.md`, `AGENTS.md`, rules files and Copilot instructions and
+  want the server and nothing else. There was no supported way to ask for it:
+  every install entry point ended by generating context files. The install
+  menu now has a third answer, `rails generate rails_ai_context:install
+  --mcp-only` and `rails-ai-context init --mcp-only` take it non-interactively,
+  and the choice is recorded in the initializer and the YAML like the tool
+  mode. With it off, `ai:context` writes nothing and exits 0, `ai:watch` writes
+  nothing, `ai:doctor` raises no context-file warning, and the `.ai-context.json`
+  line is left out of `.gitignore` because nothing writes that file. A command
+  that names a file still writes it: `ai:context:claude` and
+  `context --format claude` both work.
+- **Sidekiq workers in `job_pattern`.** A class that includes `Sidekiq::Job` is
+  not an ActiveJob descendant and does not live in `app/jobs`, so both job
+  passes missed it and no tool in either tier could describe the biggest code
+  area of an app that runs its background work that way. Workers are read from
+  `app/workers` in both tiers, with each one's `sidekiq_options` and `perform`
+  signature. The conventions directory structure counts every directory the app
+  keeps under `app/` rather than a fixed list.
+- **ActiveInteraction services.** `service_pattern` lists a service's declared
+  filters with their types and defaults, names `ActiveInteraction::Base` as the
+  dominant pattern when it is, and `generate_test` writes `.run` with those
+  filters rather than a `.call` the base class does not define.
+- **Notable gems that shape an app.** `active_interaction`, `paper_trail`,
+  `rack-cors`, `figaro`, `webauthn`, `stripe`, `plaid`, `braintree`,
+  `lockbox`, `blind_index`, `neighbor`, `pgvector`, `interactor`,
+  `trailblazer-operation` and the Sidekiq add-ons (`sidekiq-pro`,
+  `sidekiq-scheduler`, `sidekiq-cron`, `sidekiq-unique-jobs`,
+  `sidekiq-throttled`).
+
+### Changed
+
+- **`config.ai_tools = []` writes no context files.** It used to write every
+  tool's files, which is the opposite of what the value says and of what
+  `ContextFileSerializer` has always done with `format: []`. Only an unset
+  selection means "all". The install flow never produced an empty list, so this
+  reaches hand-edited configs only.
+- **The inherited filter list is emitted root first.** Rails runs the root's
+  callbacks first, and the static tier printed the nearest parent's first, so a
+  chain read as authentication running before the current user is loaded.
+- **A filter no ancestor's body declares names no class.** `sentry_around_action`
+  and `set_paper_trail_whodunnit` arrive through a gem's
+  `on_load :action_controller` block; crediting them to the nearest app
+  controller sent an agent to a file that never mentions them. They now carry
+  `provenance` instead of `from`.
+- **Model callbacks print the macro Rails has.** `after_commit_on_create` is a
+  key this gem synthesizes to order the events of one `after_commit on: [...]`;
+  copying it got a `NoMethodError`. Every renderer prints
+  `after_commit (on: :create)`.
+- **`sanitize_options` keeps Array, numeric, boolean, nil and Symbol option
+  values.** They were stringified, so `in: %w[draft sent]` reached
+  `generate_test` as one String and `in_array` got a quoted list. A consumer
+  reading `validations[].options`, `.ai-context.json` included, sees the
+  change: `dependent: :destroy` is the Symbol `:destroy` rather than
+  `"destroy"`, and `allow_nil: false` is `false` rather than the truthy String
+  `"false"`.
+- **Only a handler extension counts as a template.** A JPEG or a seed file under
+  `app/views` was counted as a template and had ivar names read out of its
+  bytes.
+
+### Fixed
+
+Defects found by a tenth QA round of v5.26.0 against a private Rails 8.0.5.1
+API-only app (issues #184 to #222), each rebuilt on a minimal fixture before
+filing.
+
+- **One dangling reflection cost the whole model.** A `has_many :through` naming
+  an association the model does not declare loads fine and only raises when
+  something touches it, so `class_name` ended in `nil.klass` and the per-model
+  rescue replaced the model - its callbacks, its table heading, its graph node -
+  with a single error line. The rescue is per association now, and the
+  reflection is marked `[UNAVAILABLE: through :x is not an association]`.
+- **The MCP transport lost its stdout across a Bundler re-exec.** `exec` closed
+  the saved descriptor, so the new image saved fd 1, by then pointing at stderr,
+  and wrote every JSON-RPC response there. A client launched from outside the
+  app got no answer to `initialize`.
+- **`dependency_graph` drew nodes no app defines.** A `through` hop was the
+  association name camelized (`PrimaryBuyer`, `InvoicePdfAttachment`), the
+  static target ignored `source:`, and a derived name knew none of the app's
+  acronyms. It also cut the graph at 50 models without saying so.
+- **`service_pattern` named a service after a word in a comment.** The regex ran
+  over raw source, never matched `module`, and its basename fallback dropped
+  every namespace. The lookup matched by basename before exact path, so only
+  the alphabetically first `create.rb` could be looked up, and "Called By" was a
+  substring search that listed a non-caller and dropped the real one.
+- **Static route helper names did not exist.** Hyphens were kept
+  (`api_v1_gift-cards_redeem_path` is a subtraction in Ruby), a dotted path was
+  used in the name where Rails uses none, and a name that cannot be one was
+  kept anyway. A booted redirect route appeared in no row and no count.
+- **`get_context` for one action listed every strong-params method in the
+  controller**, so `create_params`' permit list read as the fields `deactivate`
+  accepts.
+- **Controller Schema Hints reported services, serializers and plain constants
+  as missing models.** Only names that resolve to a model are kept now, and the
+  rest are dropped without a line.
+- **`env` read only `.rb` files**, so ENV names in `config/*.yml`, ERB views and
+  rake tasks were missing with nothing saying a file type was skipped. Category
+  matching was unanchored (`PORT` inside `PORTAL`), and a `nil` default printed
+  as `[FILTERED]`.
+- **`env_config` reported the first assignment in a file**, so it printed the
+  branch that is not running and disagreed with `config` on the same app.
+- **`gems` reported a Minitest suite in a `test/` directory that is not there**,
+  from a lockfile entry every Rails app resolves through activesupport, and
+  pointed at a `config/sidekiq.yml` without checking that it exists.
+- **`generate_test` wrote specs that cannot run.** Shoulda matchers were emitted
+  into apps that do not bundle the gem, a namespaced controller produced
+  `create(:api/v1/admin/order)`, the example sent GET whatever the route's verb,
+  and a controller with no file was answered with "no routes found".
+- **`performance_check` suggested indexes and counters the app cannot use.**
+  Every unindexed `*_id` column was a missing foreign key index whatever its
+  type, and a counter the app maintains itself was offered a `counter_cache`
+  that double-counts every create.
+- **`query` answered an unknown column with "Database not found" and exit 0.**
+  Postgres words a missing column, table and database the same way.
+- **`view` counted images and text files as templates**, read ivars out of
+  binary data, and read the CSS rule `@page` as an ivar.
+- **`partial_interface` could not resolve a `.text.erb` partial** by the Rails
+  name its own "Available" list had just printed, and cut a local's method calls
+  at ten with no marker.
+- **`api` merged every CORS allow block and environment branch into one origin
+  list**, so the line read as the API allowing `*` on every resource.
+- **`active_support` listed validator classes as "plain module" concerns.**
+- **`validate` flagged an `acceptance:` virtual attribute as a missing column**
+  and suggested a migration for a column nobody needs.
+- **`search_code --match-type trace` reported no internal calls** for a body
+  whose calls take no parentheses, counted a comment mentioning the method as a
+  call site, and tagged `app/services/models/...` as a Model.
+- **Static answers missed an app's inflections.** A route group found no
+  controller for `api/v1/ai_matches`, and a service file with no `class` line
+  was named by its camelized basename.
+- **The `controllers/{name}` resource refused a short name** the `routes/{name}`
+  resource accepts, and the controller answer pointed at a model that does not
+  exist.
+- **`ai:watch` rewrote every tool's files** whatever the configuration asked
+  for.
+
 ## [5.26.0] - 2026-09-11
 
 ### Added

data/README.md

@@ -87,7 +87,9 @@ bundle add rails-ai-context --group development
 rails generate rails_ai_context:install
 ```
 
-The generator asks which AI tools you use and whether you want MCP or CLI mode, then writes the context files, the MCP config for each tool, and `config/initializers/rails_ai_context.rb`. Re-running it is safe; it keeps what you have and adds what is missing.
+The generator asks which AI tools you use and what to write, then creates the context files, the MCP config for each tool, and `config/initializers/rails_ai_context.rb`. Re-running it is safe; it keeps what you have and adds what is missing.
+
+Keeping your own `CLAUDE.md` and `AGENTS.md`? `rails generate rails_ai_context:install --mcp-only` writes the MCP config and leaves every context file alone.
 
 ### Install standalone
 

data/docs/COMPATIBILITY.md

@@ -200,7 +200,10 @@ Proof sources:
    (Rails 8.1, Ruby 3.4) in the v5.25.0 release QA, booted and static tiers,
    standalone and in-Gemfile installs; Mastodon again in the v5.26.0 release QA,
    with packs, in-repo engines, Postgres and concurrent tool calls covered by
-   hand where no lab shape plants them.
+   hand where no lab shape plants them; a private Rails 8.0.5.1 API-only app
+   (Ruby 3.4.10, 133 models, 102 controllers, 1630 ActiveInteraction services,
+   516 Sidekiq workers) in the v5.27.0 QA round, booted and static tiers, with
+   every report rebuilt on a minimal Rails 8.0.5.1 fixture before it was filed.
 2. Non-crash coverage for every built-in tool including `get_view` in
    `spec/e2e/in_gemfile_install_spec.rb`'s full-tool sweep; output correctness
    (ivar cross-check, render-form detection, partial interfaces) verified

data/docs/CONFIGURATION.md

@@ -51,6 +51,33 @@ preset: full
 |:-------|:-----|:--------|:------------|
 | `ai_tools` | Array of symbols | `[:claude]` | Which AI tools to generate context for. Options: `:claude`, `:cursor`, `:copilot`, `:opencode`, `:codex` |
 | `tool_mode` | Symbol | `:mcp` | `:mcp` (MCP server primary, CLI fallback) or `:cli` (CLI only, no MCP server) |
+| `context_files` | Boolean | `true` | Set `false` for MCP-only: the server and the CLI still answer, and no context file is written or touched |
+
+#### MCP only
+
+Some apps keep their own `CLAUDE.md`, `AGENTS.md` and rules files and want the
+server and nothing else:
+
+```bash
+rails generate rails_ai_context:install --mcp-only   # or: rails-ai-context init --mcp-only
+```
+
+That writes the MCP config for the tools you pick and records:
+
+```ruby
+RailsAiContext.configure do |config|
+  config.tool_mode = :mcp
+  config.context_files = false
+end
+```
+
+`rails ai:context` then writes nothing and exits 0, `rails ai:watch` writes
+nothing, and `rails ai:doctor` raises no context-file warning. A command that
+names a file still writes it: `rails ai:context:claude` and
+`rails-ai-context context --format claude`.
+
+`config.ai_tools = []` means no context files too, and still picks which MCP
+config file is written. Before v5.27.0 an empty list wrote every tool's files.
 
 ### Introspection
 

data/docs/FAQ.md

@@ -59,6 +59,19 @@ Yes, freely. Both generate identical context files and provide the same 45 tools
 **Don't commit:**
 - `.ai-context.json` - auto-added to .gitignore by the install generator
 
+### Can I use only the MCP server?
+
+Yes:
+
+```bash
+rails generate rails_ai_context:install --mcp-only   # or: rails-ai-context init --mcp-only
+```
+
+The MCP config is written, `config.context_files = false` is recorded, and no
+`CLAUDE.md`, `AGENTS.md`, rules file or `.ai-context.json` is written or
+touched. Every tool still answers over MCP and over the CLI. See
+[CONFIGURATION.md](CONFIGURATION.md#mcp-only).
+
 ---
 
 ## MCP & Tools

data/docs/INTROSPECTORS.md

@@ -126,7 +126,7 @@ end
 
 | Introspector | Key | What it extracts |
 |:-------------|:----|:-----------------|
-| JobIntrospector | `:jobs` | Background jobs and mailers: queue, retries, schedules, and the `file:` each one is defined in |
+| JobIntrospector | `:jobs` | Background jobs, Sidekiq workers under `app/workers`, and mailers: queue, retries, `sidekiq_options`, schedules, and the `file:` each one is defined in |
 | RakeTaskIntrospector | `:rake_tasks` | Custom rake tasks |
 
 ### Security & Auth

data/docs/QUICKSTART.md

@@ -23,7 +23,11 @@ rails generate rails_ai_context:install
 The generator asks two questions:
 
 1. **Which AI tools do you use?** - Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI, or all
-2. **Do you want MCP server support?** - Yes (MCP mode) or No (CLI-only mode)
+2. **What should rails-ai-context write?** - MCP config + context files (default), context files only (CLI mode), or MCP config only
+
+The third answer is MCP-only: the server and the CLI answer in full, and your
+own `CLAUDE.md`, `AGENTS.md` and rules files are left alone. Non-interactively
+that is `--mcp-only`.
 
 That's it. Your AI tool now has live access to your schema, models, routes, controllers, views, and conventions.
 

data/docs/SETUP.md

@@ -66,6 +66,10 @@ This creates:
 - `.claude/rules/rails-context.md` - General context rules (always loaded)
 - `.claude/rules/rails-mcp-tools.md` - Tool reference (always loaded)
 
+Keeping your own `CLAUDE.md`? Add `--mcp-only` and only `.mcp.json` is
+written; every context file is left alone. See
+[CONFIGURATION.md](CONFIGURATION.md#mcp-only).
+
 ### Manual MCP config
 
 If you need to configure manually, create `.mcp.json`:

data/docs/STANDALONE.md

@@ -143,6 +143,9 @@ rails-ai-context init
 
 The MCP config files are updated automatically. Both modes generate identical context files and provide the same 45 tools.
 
+Both also take `--mcp-only`, which writes the MCP config and no context files
+at all. See [CONFIGURATION.md](CONFIGURATION.md#mcp-only).
+
 ## Troubleshooting
 
 ### "Bundler::GemNotFound" on `rails-ai-context serve`

data/docs/TOOLS.md

@@ -349,7 +349,7 @@ Notable gems with versions, categories, and config file locations.
 
 ### `rails_get_env`
 
-Environment variables + credentials keys (values are never exposed).
+Environment variables + credentials keys (values are never exposed). Scans `.rb`, `.rake`, ERB views and config YAML under `app`, `config` and `lib`; files matching `sensitive_patterns` (`config/database.yml`, credentials, keys) are never read, and the answer says so.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -374,7 +374,9 @@ Service object interface, dependencies, side effects, callers.
 
 ### `rails_get_job_pattern`
 
-Background job queue, retries, guard clauses, broadcasts, schedules.
+Background job queue, retries, guard clauses, broadcasts, schedules. Sidekiq
+workers under `app/workers` are listed alongside the ActiveJob jobs, with
+their `sidekiq_options` and `perform` signature.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -430,7 +432,7 @@ ActiveSupport surface: concerns registry, deprecators, MessageVerifier/MessageEn
 
 ### `rails_get_env_config`
 
-Per-environment configuration from `config/environments/*.rb`: notable toggles (`force_ssl`, `eager_load`, caching, log level, queue adapter, mailer delivery) and every config key each environment sets.
+Per-environment configuration from `config/environments/*.rb`: notable toggles (`force_ssl`, `eager_load`, caching, log level, queue adapter, mailer delivery) and every config key each environment sets. A key assigned in more than one branch reports every value with its condition; booted, the running environment reports the value the app resolved.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -450,9 +452,13 @@ Model/service dependency graph in Mermaid or text format.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
-| `root` | string | - | Starting node |
-| `format` | enum | `text` | `text`, `mermaid` |
-| `detail` | enum | `standard` | `summary`, `standard`, `full` |
+| `model` | string | - | Center the graph on this model |
+| `depth` | integer | `2` | Hops from the centre model (1-3) |
+| `format` | enum | `mermaid` | `mermaid`, `text` |
+| `show_cycles` | boolean | `false` | Detect and list circular dependencies |
+| `show_sti` | boolean | `false` | Show Single Table Inheritance hierarchies |
+
+Without `model` the graph is capped at 50 nodes, and says so when it cuts.
 
 ### `rails_migration_advisor`
 

data/exe/rails-ai-context

@@ -191,6 +191,16 @@ class RailsAiContextCLI < Thor
       end
       ::RailsAiContext::LegacyCleanup.prompt_legacy_files(cleanup_tools, root: Dir.pwd)
 
+      # An explicit --format names a file, so it is written either way. With
+      # no format and an MCP-only install there is nothing to write, and the
+      # rake surface says the same thing in the same words.
+      if options[:format].nil? && !::RailsAiContext.configuration.context_files
+        $stderr.puts "MCP-only install (config.context_files = false): no context files written."
+        $stderr.puts "Run `rails-ai-context context --format claude` to write one anyway, " \
+                     "or set config.context_files = true."
+        return
+      end
+
       $stderr.puts "Introspecting Rails app..."
 
       # An explicit --format overrides the recorded selection.
@@ -264,6 +274,8 @@ class RailsAiContextCLI < Thor
 
     desc "init", "Set up rails-ai-context for standalone use (creates .rails-ai-context.yml and .mcp.json)"
     option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
+    option :mcp_only, type: :boolean, default: false,
+      desc: "Write the MCP config and nothing else: no CLAUDE.md, AGENTS.md, rules files or .ai-context.json"
     def init
       unless entry_boot.app_present?(Dir.pwd, allow_source_only: true)
         $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
@@ -278,7 +290,9 @@ class RailsAiContextCLI < Thor
 
       # --- Prompts (no Rails needed) ---
       ai_tools = prompt_ai_tools
-      tool_mode = prompt_tool_mode
+      setup = prompt_setup
+      tool_mode = setup.tool_mode
+      context_files = setup.context_files
 
       # --- Cleanup removed tools ---
       cleanup_removed_tools(previous_tools, ai_tools) if previous_tools&.any?
@@ -287,13 +301,13 @@ class RailsAiContextCLI < Thor
       ::RailsAiContext::LegacyCleanup.prompt_legacy_files(ai_tools, root: Dir.pwd)
 
       # --- Record the selection (YAML, plus the initializer line) ---
-      record_selection(ai_tools, tool_mode)
+      record_selection(ai_tools, tool_mode, context_files)
 
       # --- Write per-tool MCP config files (MCP mode only) ---
       write_mcp_configs(ai_tools, tool_mode)
 
       # --- Add .ai-context.json to .gitignore ---
-      add_to_gitignore
+      add_to_gitignore(context_files)
 
       # --- Boot Rails, load config, generate context ---
       # The config files are already on disk by now, so failing here leaves the
@@ -301,12 +315,17 @@ class RailsAiContextCLI < Thor
       # what you run on a repo you have just cloned.
       boot_rails!(command: "init", allow_static: true)
 
-      $stderr.puts ""
-      $stderr.puts "Generating AI context files..."
-      print_context_result(::RailsAiContext.generate_context(format: ai_tools))
+      if context_files
+        $stderr.puts ""
+        $stderr.puts "Generating AI context files..."
+        print_context_result(::RailsAiContext.generate_context(format: ai_tools))
+      else
+        $stderr.puts ""
+        $stderr.puts "MCP-only setup: no context files written."
+      end
 
       # --- Instructions ---
-      show_standalone_instructions(ai_tools, tool_mode)
+      show_standalone_instructions(ai_tools, tool_mode, context_files)
     end
 
     desc "preset NAME", "Run a multi-tool preset (architecture, debugging, migration)"
@@ -367,8 +386,12 @@ class RailsAiContextCLI < Thor
       ::RailsAiContext::Install::Program.select_ai_tools(program_surface)
     end
 
-    def prompt_tool_mode
-      ::RailsAiContext::Install::Program.select_tool_mode(program_surface)
+    def prompt_setup
+      if options[:mcp_only]
+        return ::RailsAiContext::Install::Program::Setup.new(:mcp, false)
+      end
+
+      ::RailsAiContext::Install::Program.select_setup(program_surface)
     end
 
     def read_previous_ai_tools
@@ -381,14 +404,17 @@ class RailsAiContextCLI < Thor
       )
     end
 
-    def add_to_gitignore
-      ::RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Dir.pwd)
+    def add_to_gitignore(context_files = true)
+      ::RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Dir.pwd,
+                                                       context_files: context_files)
     end
 
-    def record_selection(ai_tools, tool_mode)
+    def record_selection(ai_tools, tool_mode, context_files = true)
       result = ::RailsAiContext::Install::SelectionRecord.write(
-        ai_tools, root: Dir.pwd, extra_yaml: { "tool_mode" => tool_mode.to_s }
+        ai_tools, root: Dir.pwd,
+        extra_yaml: { "tool_mode" => tool_mode.to_s, "context_files" => context_files }
       )
+      ::RailsAiContext::Install::SelectionRecord.write_context_files(context_files, root: Dir.pwd)
 
       ::RailsAiContext::Install::SelectionRecord.messages(result).each do |level, text|
         $stderr.puts(level == :warn ? "Warning: #{text}" : text)
@@ -402,7 +428,7 @@ class RailsAiContextCLI < Thor
       )
     end
 
-    def show_standalone_instructions(ai_tools, tool_mode)
+    def show_standalone_instructions(ai_tools, tool_mode, context_files = true)
       $stderr.puts ""
       $stderr.puts "=" * 50
       $stderr.puts " rails-ai-context initialized!"
@@ -411,11 +437,15 @@ class RailsAiContextCLI < Thor
       $stderr.puts "Your setup:"
       ::RailsAiContext::Install::AiTool.all.each do |tool|
         next unless ai_tools.include?(tool.key)
-        $stderr.puts "  #{tool.name.ljust(16)} -> #{tool.files}"
+        $stderr.puts "  #{tool.name.ljust(16)} -> #{context_files ? tool.files : 'MCP config only'}"
+      end
+      unless context_files
+        $stderr.puts ""
+        $stderr.puts "  Left alone on purpose: CLAUDE.md, AGENTS.md, the rules directories and .ai-context.json."
       end
       $stderr.puts ""
       $stderr.puts "Commands:"
-      $stderr.puts "  rails-ai-context context    # Regenerate context files"
+      $stderr.puts "  rails-ai-context context    # Regenerate context files" if context_files
       $stderr.puts "  rails-ai-context tool NAME  # Run any of the #{RailsAiContext::CountPhrase.call(builtin_tool_count, "tool")}"
       if tool_mode == :mcp
         $stderr.puts "  rails-ai-context serve      # Start MCP server"

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

@@ -38,6 +38,9 @@ module RailsAiContext
       class_option :defaults, type: :boolean, default: false,
         desc: "Skip all interactive prompts and use each prompt's documented default (for CI/non-interactive use)"
 
+      class_option :mcp_only, type: :boolean, default: false,
+        desc: "Write the MCP config and nothing else: no CLAUDE.md, AGENTS.md, rules files or .ai-context.json"
+
       BARE_GUARD_PATTERN = RailsAiContext::Install::InitializerFile::BARE_GUARD
 
       def select_ai_tools
@@ -54,8 +57,16 @@ module RailsAiContext
         )
       end
 
-      def select_tool_mode
-        @tool_mode = RailsAiContext::Install::Program.select_tool_mode(program_surface)
+      def select_setup
+        if options[:mcp_only]
+          @tool_mode = :mcp
+          @context_files = false
+          return
+        end
+
+        setup = RailsAiContext::Install::Program.select_setup(program_surface)
+        @tool_mode = setup.tool_mode
+        @context_files = setup.context_files
       end
 
       def create_mcp_config
@@ -79,6 +90,11 @@ module RailsAiContext
             #   :mcp - MCP primary + CLI fallback (default, requires `rails ai:serve`)
             #   :cli - CLI only (no MCP server needed, uses `rails 'ai:tool[NAME]'`)
             # config.tool_mode = :mcp
+
+            # Whether this gem writes context files at all. false is MCP-only:
+            # the server and the CLI still answer, and CLAUDE.md, AGENTS.md,
+            # the rules directories and .ai-context.json are left alone.
+            # config.context_files = true
         SECTION
         "Introspection" => <<~SECTION,
             # ── Introspection ─────────────────────────────────────────────────
@@ -261,11 +277,7 @@ module RailsAiContext
         # Always write uncommented so re-install can detect previous selection
         tools_line = RailsAiContext::Install::SelectionRecord.initializer_line(@selected_formats)
 
-        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
+        tool_mode_line = build_tool_mode_line
 
         content = "# frozen_string_literal: true\n\nRailsAiContext.configure do |config|\n"
 
@@ -280,6 +292,7 @@ module RailsAiContext
             #   :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}
+          #{build_context_files_line}
 
         SECTION
 
@@ -312,7 +325,11 @@ module RailsAiContext
         existing, changed = update_config_line(existing, "config.tool_mode", build_tool_mode_line)
         changes << "tool_mode" if changed
 
-        # 3. Add any missing config sections
+        # 3. Record whether this install writes context files at all
+        existing, changed = update_config_line(existing, "config.context_files", build_context_files_line)
+        changes << "context_files" if changed
+
+        # 4. Add any missing config sections
         CONFIG_SECTIONS.each do |name, section_content|
           marker = "── #{name}"
           next if existing.include?(marker)
@@ -423,6 +440,20 @@ module RailsAiContext
         end
       end
 
+      # Written uncommented either way, so a re-run reads the same answer the
+      # last one recorded.
+      def build_context_files_line
+        if context_files?
+          "  config.context_files = true   # write CLAUDE.md, AGENTS.md and rules files"
+        else
+          "  config.context_files = false  # MCP only: no context files are written"
+        end
+      end
+
+      def context_files?
+        @context_files.nil? ? true : @context_files
+      end
+
       def read_previous_ai_tools
         RailsAiContext::Install::SelectionRecord.read(root: Rails.root)
       end
@@ -435,7 +466,7 @@ module RailsAiContext
         # comment behind. One writer per file, and it is not this call.
         result = RailsAiContext::Install::SelectionRecord.write(
           @selected_formats, root: Rails.root,
-          extra_yaml: { "tool_mode" => @tool_mode.to_s },
+          extra_yaml: { "tool_mode" => @tool_mode.to_s, "context_files" => context_files? },
           initializer: false
         )
 
@@ -445,7 +476,8 @@ module RailsAiContext
       end
 
       def add_to_gitignore
-        RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Rails.root)
+        RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Rails.root,
+                                                        context_files: context_files?)
       end
 
       def install_validation_hook
@@ -505,6 +537,12 @@ module RailsAiContext
       end
 
       def generate_context_files
+        unless context_files?
+          say ""
+          say "MCP-only install: no context files written.", :yellow
+          return
+        end
+
         say ""
         say "Generating AI context files...", :yellow
 
@@ -540,7 +578,12 @@ module RailsAiContext
         say "Your setup:", :yellow
         RailsAiContext::Install::AiTool.all.each do |tool|
           next unless @selected_formats.include?(tool.key)
-          say "  ✅ #{tool.name.ljust(16)} -> #{tool.files}"
+          files = context_files? ? tool.files : "MCP config only"
+          say "  ✅ #{tool.name.ljust(16)} -> #{files}"
+        end
+        unless context_files?
+          say ""
+          say "  Left alone on purpose: CLAUDE.md, AGENTS.md, the rules directories and .ai-context.json.", :yellow
         end
         say ""
         say "Commands:", :yellow