rails-ai-context 5.26.0 → 5.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5554194142695cce91ac263b45bcd692fdfa2fe80d85ddbfe70c52a85eab9087
-  data.tar.gz: 1b040d294942a14f92a5b86b58b185f3c15e840ad9976d2e3b90a888de66b6e8
+  metadata.gz: 78848e75315236681b6b31bba337665e75a143d862d2d1ff828f48f50b1756f5
+  data.tar.gz: 8af5164b8ee4ea9900d82450d2a74905dcf1b831c02d7ba95c5c869274c18e9e
 SHA512:
-  metadata.gz: dc5ee392e5faa628133f7abdf33b1fd655c167f4e7cfbf2fd2dff21b9047dff2648b89e4e5fa3be07ca6fc98a93084e30cf9954e06f588ab43ab40dbf6abc832
-  data.tar.gz: 71dda3b0936a89dce1c56b6b6f5889762b0f0ce2265a3ec42eab7c824155be84728de8ae2da9104bd7653a9e26568a01858fb6207ca705fd66dfdb4fcb52c932
+  metadata.gz: 6dbfa116e75a4675314e6c4a06ada6c2c7d7b8c7f0d9fb5ca0abe9945add65f1729b0101200debf5c25ea2190e66b57f41761b4307d8414d77ccfc62dc292e9d
+  data.tar.gz: 86984bc5566480da28d88b7ef475138bb85c9ba459fcd87e58f8a4afd03239a365ee30d032412701291ec0bd60f7f0e0cccfa882fee0150e6baed74c966a33b1

data/CHANGELOG.md

@@ -5,6 +5,335 @@ 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.28.0] - 2026-09-22
+
+Thirty-six changes an architecture survey of v5.27.0 asked for, nine of them
+defects where a user got a wrong answer, plus what three review rounds found in
+the fixes themselves.
+
+### Added
+
+- **Services, helpers, jobs and concerns are found wherever the app keeps
+  them.** The four tools globbed `app/<kind>` off the app root, so a packwerk
+  app whose services live under `packs/billing/app/services` was told it had no
+  services directory and may not use the pattern. Directory discovery reads
+  `PathResolver.dirs_for`, which already resolved packs, engines and
+  `extra_app_paths` for the payload side. `ConcernPaths.resolve` and
+  `ActiveSupportIntrospector` read the same resolver, so a concern's listing,
+  its lookup and its "Used By" line now agree on one app. Counts move on any
+  app with packs or engines. Each walk names the directory a file came from, so
+  two files of the same basename under different roots no longer collide, and a
+  tool that finds nothing names all three directory patterns it searched
+  instead of the conventional one alone.
+- **`RailsAiContext.debug_fail`.** About 258 rescue bodies in `lib/`
+  hand-rolled the same three lines: rescue the error, write a `DEBUG`-gated
+  warning to stderr, return a fallback. They call one method now, with every
+  message string and every fallback value unchanged. `exe/rails-ai-context`
+  shims it beside `log_warn`, because the standalone install path loads seven
+  files by hand and a converted rescue inside `install_mode.rb` would otherwise
+  raise `NoMethodError` after the removed-tool cleanup had already deleted
+  files.
+- **`PackageJson`.** GemLock's twin for the node side: `package.json` parsed
+  once per root, `dependencies` merged with `devDependencies`, capped by
+  `configuration.max_file_size` rather than by a constant no caller can reach,
+  and empty for anything it cannot read. A scope named after the package
+  counts, so an app reaching tailwind through `@tailwindcss/vite` keeps its
+  answer.
+
+### Removed
+
+- **`config.job_processor`, gone from `.ai-context.json` and from
+  `get_config`.** `ConfigIntrospector` parsed `config/sidekiq.yml` a second
+  time to publish it, and nothing read it: no renderer, no spec, no template.
+  The two readers disagreed, so a `:queues:` block written with weights,
+  `- [critical, 2]`, lost `critical` on the config side and kept it on the jobs
+  side, and one sidekiq.yml shipped two queue lists in one payload. The same
+  concurrency and queues stay under `jobs.sidekiq_config`, which
+  `get_job_pattern` already consumes, and `config.queue_adapter` still names
+  the adapter. Both sections sit in the standard and full presets, so no preset
+  loses the fact.
+- **`action_bindings` and `outlet_controllers`, gone from every Stimulus
+  controller entry.** Filling `action_bindings` read every ERB, HAML and Slim
+  file under `app/views` and `app/components` on every generation, and
+  `outlet_controllers` restated the outlets list one line above it. Nothing in
+  `lib/` read either key: `get_stimulus` renders outlets, and the compact
+  serializer touches the section through `controllers` and `total_controllers`.
+  Both keys leave the artifact, and one full pass over the view and component
+  trees leaves every generation.
+- **`Serializers::SectionGuard`, `DetailLevel::SCHEMA_ENUM` and
+  `Install::Program.select_tool_mode`.** SectionGuard was 15 lines forwarding
+  to `Tools::SectionFetch.usable?`; both callers sat in `SchemaAdapter`, which
+  is not a serializer, and `RouteCoverage` already called SectionFetch
+  directly. SCHEMA_ENUM went with its last reference when
+  `DetailLevel.schema(description)` replaced the same four-line input-schema
+  hash in 21 tools; every published schema is byte-identical, and
+  `rails_onboard` keeps its own literal because its levels are quick, standard
+  and full. `select_tool_mode` was a shim for `select_setup(surface).tool_mode`
+  with no caller left in `lib/`, and it cannot express the MCP-config-only
+  mode. `ModelIntrospector#sti_bases` and
+  `ControllerIntrospector#extract_permit_details` go with them; only their own
+  recursion and their own specs were calling them.
+
+### Changed
+
+- **`.github/instructions/rails-context.instructions.md` prints every gem
+  category.** `.first(6)` on the grouped Hash returned the first six pairs, so
+  the seventh category onward was dropped with nothing saying so, while
+  `.cursor/rules/rails-project.mdc` rendered the same grouping uncapped. One
+  payload, two gem lists.
+- **`.cursor/rules/rails-project.mdc` bolds `Global before_actions:`** like the
+  Claude and Copilot files. The three serializers each hand-wrote the same
+  ten-step overview and had drifted; `StackOverviewHelper#overview_lines`
+  states the body once and each renderer keeps only its frontmatter, title and
+  MCP hint.
+- **Puma settings are read inside blocks.** The hand-rolled recursion stopped
+  at the top level, so a `workers` line guarded by an environment conditional,
+  which is what the generated `puma.rb` ships, was invisible and the answer
+  read as no workers configured. `MethodCallListener` sees a receiverless call
+  at any depth. The cost of the widening is that nesting no longer hides a
+  setting, so a name set twice reports the last one wherever it sits. Also
+  `threads ENV.fetch("RAILS_MIN_THREADS") { 5 }, ENV.fetch("RAILS_MAX_THREADS")
+  { 5 }` reports 5 and 5 where it reported nothing, and the digit match is
+  anchored away from word characters, so `ENV.fetch("PORT_2", 3000)` no longer
+  reads as 2.
+- **`get_conventions`' frontend stack string reads parsed dependencies.**
+  `detect_frontend_stack` matched bare substrings against the raw file, with no
+  quotes at all, so `vite-plugin-ruby` on its own reported Vite. The markers
+  carry alternates where an exact name would have lost an answer the substring
+  caught: svelte or `@sveltejs/kit`, `@hotwired/turbo` or
+  `@hotwired/turbo-rails`.
+- **`api_introspector`'s codegen list reads parsed dependencies.** It searched
+  the file for the quoted tool name, so `openapi-typescript`, `orval` or
+  `@graphql-codegen/cli` named anywhere in `package.json`, an `overrides` block
+  included, counted as a client generator the app runs.
+- **`rails_generate_test` resolves a controller by the rule
+  `rails_get_controllers` uses.** It camelized the string and looked the result
+  up, so with `Admin::GiftCardsController` as the only gift-card controller,
+  `rails_get_controllers(controller: "gift_cards")` resolved and
+  `rails_generate_test(controller: "gift_cards")` answered "not found".
+  `Payload.find_controller` answers for both, with the camelize kept as the
+  fallback for a payload carrying no controllers at all.
+
+### Fixed
+
+Nine defects the survey confirmed against v5.27.0, and the defects three review
+rounds found in the work that fixed them.
+
+- **`onboard(detail: "quick")` no longer prints a guessed domain noun.** Eleven
+  ordered regexes read model, job and service names and stated the result as
+  plain fact with no confidence marker, so one model named `Message` made an
+  app "a messaging app". Quick mode now states what it measured: versions,
+  table, model and job counts, the frontend and the test framework.
+- **`api_namespaces` invented a namespace and missed one.** The two tiers
+  derived the list their own way. The booted regex kept a trailing slash on
+  `/api/users`, matched unanchored so `namespace :admin { namespace :api }`
+  reported `/api/v1` for an app that serves `/admin/api/v1`, and dropped a
+  route sitting at exactly `/api`. The static spelling got the segment boundary
+  wrong, so `/apidocs` reported `/api`. Both tiers read one anchored form.
+- **Turbo drive settings were double-counted for layouts.** `app/views/layouts`
+  was walked again after `app/views/**/*` had already reached it. The permanent
+  element pass threw its duplicate away through `uniq`; the drive settings did
+  not, so one attribute in a layout and one in a view printed as 3.
+- **The asset pipeline reported the wrong bundler and CSS framework.** Three
+  readers asked whether a package was present by searching the raw file for its
+  quoted name, so an app pinning CVE fixes in an `overrides` block was told
+  esbuild is its bundler and postcss its CSS framework, while the one reader
+  that parsed the file called the same app vite. Both answers landed in one
+  payload.
+- **`analyze_feature`'s Jobs, Mailers and Channels sections came from a glob.**
+  Each job's queue was read off its own `queue_as`, so a job inheriting the
+  queue from `ApplicationJob` was reported on a queue it does not use. The
+  three sections read the payload now, which carries what the booted tier
+  resolved, mailer actions and channel stream methods included. A section whose
+  payload entry is not there, because the `:jobs` introspector is off, is left
+  out rather than rendered from a directory walk.
+- **`performance_check` attributed queries to methods that are not actions.** A
+  `def` inside a nested class became a call site, and a one-line
+  `private def set_post` leaked its body into the action above it.
+  `ActionResolver` answers what an action is here, as it does everywhere else.
+  A second collision went with it: each body was found by searching the whole
+  file for the first `def <name>`, so a nested class defining the same name
+  earlier handed back its body and the real action was never scanned. The body
+  is cut from the lines the owner-filtered walk recorded, and `get_controllers`
+  and `get_context` share the seam. An empty owner filter falls back to the
+  line scan rather than answering nothing, and `def self.index` no longer
+  stands in for `def index`.
+- **A model whose only rule is `validate :method` printed its bullets under the
+  wrong heading.** `## Validations` was emitted only when the reflected list
+  had entries, and the custom bullets come from a second list that is disjoint
+  from it on both tiers, so they landed under Associations.
+- **Two ERB readers missed `<%== ... %>` and read a commented ivar as used.**
+  `check_instance_variable_usage` and `extract_local_variable_references` each
+  carried their own copy of the tag regex, byte for byte the same and neither
+  matching `ErbSource::TAG`. Both read `<%[=\-]?`, one optional character, so
+  `<%== title %>` parsed as a body of "= title" and the local never reached a
+  partial's expected locals. The comment skip was a second answer too:
+  `get_partial_interface` re-implemented it and `validate_semantics` never had
+  one, so `<%# @ghost %>` was reported as an ivar used in the view and not set
+  in the controller. Both readers ask `ErbSource` now.
+- **`rails_get_controllers` refused a name the VFS resource accepts.** VFS
+  resolved five ways, the tool two, so `controller: "gift_cards"` failed
+  against `Admin::GiftCardsController` while the resource answered off the same
+  payload. Both read `Payload.find_controller`, so a route key, an unambiguous
+  basename and the singularize and classify spellings now resolve in the tool
+  too.
+- **Two files behind one name no longer hide each other.** Once services,
+  helpers and concerns were read from packs and engines, a name could have more
+  than one file behind it. The ambiguous-service list printed
+  `app/services/<path>` for files that live under a pack, so two candidates
+  printed as two identical lines naming a file that exists in neither, and the
+  suggestion that followed handed back the name it had just refused. Paths
+  print from the app root, and a narrowing suggestion is offered only when some
+  candidate's relative path is unique. `rails_get_helper_methods` rendered the
+  first match as the whole module and listed the others under "Also defined
+  in" even when they declare different modules, so a file declaring
+  `Reports::DashboardHelper` was named under an `Admin::DashboardHelper`
+  heading; matches are split by the module each file declares.
+  `rails_get_concern` broke on the first directory that resolved, so an app
+  with both `app/models/concerns/trackable.rb` and
+  `app/controllers/concerns/trackable.rb` saw only the controller one. Every
+  "available" list is deduplicated where it is built.
+
+## [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/ARCHITECTURE.md

@@ -110,11 +110,12 @@ flowchart LR
 
 The `Introspector` orchestrator runs configured introspectors and merges results.
 
-Three modules answer questions every introspector used to answer for itself:
+Four modules answer questions every introspector used to answer for itself:
 
 - **SourceScan** - one walk over a kind of app source, across every directory `PathResolver` resolves: `paths` stats, `each` reads, `classes` names by the declared constant
 - **EagerLoad** - loads a directory's constants for a booted-tier walk, one file at a time, so an unloadable file costs only itself
 - **GemLock** - which gems the app resolved and at what version, read once per lockfile and matched by exact name across GEM, GIT and PATH
+- **PackageJson** - which npm packages the app depends on, read once per `package.json`: present means named in `dependencies` or `devDependencies`, so an `overrides` pin is not a dependency, and `@tailwindcss/vite` counts as tailwindcss
 
 Two more answer a question a tool asks:
 
@@ -198,7 +199,6 @@ Result: controller and view tools automatically include relevant schema informat
 | `ToolGuideHelper` | MCP/CLI tool reference sections |
 | `TestCommandDetection` | Test framework detection |
 | `SectionFacts` | The facts every surface states about an app - auth, assets, associations, the filter chain, an unread entry's row, the static-tier notice - each rendered in one place |
-| `SectionGuard` | Whether a section resolved, so a refused one is not rendered |
 | `SectionMarkerWriter` | Writes a managed section into a file the user also owns |
 | `ContextModeDispatch` | Picks full or compact rendering for a run |
 

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`