rails-ai-context 5.36.8 → 5.36.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cd401837a164e83cf1558e5ff9ed491e0409974c9ffae9d4b648e56b4e4fb68
-  data.tar.gz: 1667e185eba134e006450acd3edf19ffe1e590b3a6033608db25ad60e529e87a
+  metadata.gz: e4f5530fd8b0a92932d1810f018d01de51af456064f92de2f9b95749360e43a5
+  data.tar.gz: dd8098d2f6d049088e92d857a407a69e84a19963379eaa698749bab6d5564539
 SHA512:
-  metadata.gz: ef8df079d4306b933571f8a01f697a0ca8c6e96b663b71894e065760fc72eb5ffca09a0a07471722afb684e805258ad05c60676f28a7f68599f591e1f955ec67
-  data.tar.gz: 7edafa2842e04597cbc61786c8ee67c7e8c74ab312ce9c75c6d0bc711bf0f496deff280e45984c5104e08b229ec7ba16b6d7dd822990f133d77e945b923ec174
+  metadata.gz: 5ac4f8fb6bdd15d56bf3db2aec1b5e53d3ca39f437d2acead40769014f3747546a931c2ad531250c614ff3f418eaae5d82bf84fe2790036e7931c50f515dd12b
+  data.tar.gz: 943060825f72f4e118bebc8160a209787582d8223050ca65cbdd6149bff4819fc12966962dc2ceb1f999689571db1121f908b68bb4ca27563094d7cf1874b6fd

data/CHANGELOG.md

@@ -5,6 +5,131 @@ 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.36.9] - 2026-10-23
+
+### Security
+
+- **`rails_read_logs` and `rails_query` hide a value under a plural secret name
+  or a list of codes** (#606). A secret word ending a name in its plural (`api_keys`,
+  `tokens`, `secrets`, `passwords`, `accessTokens`) named no secret, and
+  neither did `recovery_codes`, `backup_codes`, `recoveryCodes` or
+  `backupCodes`, so their values came back from a log line, inline or bound,
+  and `rails_query` returned such a column. A list or hash logged under a
+  secret name is now filtered whole, on one line or spread over lines, where
+  only its first element was, and so are a query parameter with a secret word
+  anywhere in its bracketed name (`user[password][new]=`) and every value of
+  `API_KEYS=a,b`. In a log line a count stays shown (`tokens_used`,
+  `token_count`, `prompt_tokens: 12`, `inputTokens: 12`), and so do `keys`,
+  `primary_keys` and `cache_keys`; `rails_query` still refuses a column whose
+  name holds `token` unless `query_allowed_columns` lists it.
+
+### Added
+
+- **The repository is a Claude Code plugin marketplace.** `claude plugin install
+  rails-ai-context --marketplace crisnahine/rails-ai-context --scope project`
+  adds the MCP server and gives each session in a Rails app the six rules the
+  context files open with (unless the app's own files carry them or its config
+  turns them off), and writes no context files or MCP config. It runs the
+  installed rails-ai-context, for the `ruby` on `PATH`, Windows included.
+  Where it cannot serve (no gem for that Ruby, an older one, a Ruby too old,
+  several apps or none) its server still connects, with no tools, and tells
+  the session why, naming the Ruby and the folder it ran in, since Claude Code
+  skips a plugin server that failed to start in every new session for 15
+  minutes. Its command line names no versioned folder, so one
+  `allowedMcpServers` entry admits it across updates. See
+  [SETUP.md](docs/SETUP.md#as-a-plugin).
+- **`doctor` knows the plugin.** It reads Claude Code's settings, install
+  registry, `/mcp` toggles and MCP policy per session folder, as Claude Code
+  does. Where the plugin serves the app it counts as Claude Code's MCP config;
+  where it does not run, `doctor` says why (not installed, a local marketplace
+  folder that is gone, turned off in `/mcp`, blocked by the MCP or marketplace
+  policy, naming each rule and the file that holds it, or a managed settings
+  file Claude Code cannot read) instead of sending you to `init`. A
+  `.mcp.json`, user scope or local scope server of the gem's, an HTTP one
+  included, that a session would start beside it is a warning naming the
+  commands that remove it, since Claude Code would list every tool twice. Where
+  Claude Code never ran, as on CI, what the plugin needs is a warning, so a
+  STRICT run stays green. Where an organization deploys `managed-mcp.json`,
+  which starts its own servers alone, `doctor` judges Claude Code by it; it
+  follows a `CLAUDE_CONFIG_DIR` set in the settings' `env` block, and warns
+  about one there or in the environment that is not an absolute path, which no
+  one can read from outside a session.
+
+### Changed
+
+- **The install writes no Claude Code server where the app's committed settings
+  turn the plugin on.** `init`, the install generator and `context` leave
+  `.mcp.json` alone there and say why, so doctor's fix to remove an old entry
+  lasts; `init` in a folder holding one app does the same where that folder's
+  committed settings turn the plugin on, and writes the app's own `.mcp.json`
+  for sessions started in the app. Its summary marks the plugin off where it
+  does not start for you. Where only your own settings turn the plugin on,
+  Claude Code's next step says to turn the `.mcp.json` server off with `/mcp`.
+- **The update notice in a plugin's server says to reconnect it.** It named
+  `init`, which would add a second server beside the plugin's.
+- **`uninstall` names the Claude Code plugin** that runs the installed gem, and
+  the commands that turn it off for the app (one per folder whose local
+  settings its sessions read) and take it out, before it suggests removing the
+  gem.
+
+### Fixed
+
+- **A YAML alias in `.rails-ai-context.yml` no longer stops the app's boot.**
+  The loader refused aliases and the error escaped the engine's initializer.
+  Aliases now apply, and YAML that will not load warns and keeps the defaults.
+  So does a value of the wrong shape, such as a nested list for `ai_tools`, a
+  list for `preset` or a mapping for a number, which raised past the
+  initializer too, in one short line however many aliases the file nests. A
+  number written as text reads as that number: `1e5` had read as 1, a
+  `query_timeout` of `010` as 8, and a quoted number failed the tools that
+  compare it.
+- **`rails-ai-context init` and `context` read an odd config file as the
+  loader does** (#520). A file holding a list, not settings, and a `tool_mode`
+  that is not a name stopped both with a Ruby error. They now warn and keep the
+  default, as the loader does.
+- **A number setting from a configure block is checked when it is set.** Text
+  such as an ENV lookup, a negative count or a list was stored as given for the
+  settings with no writer of their own, and a tool failed on it later. It now
+  reads as the number it is written as, and a wrong value raises ArgumentError
+  at boot, as `cache_ttl` already did; from the YAML file it warns and keeps
+  the default. `live_reload_debounce` likewise takes a finite number of
+  seconds, zero or more.
+- **A query log tag in a statement's trailing comment is read as a tag.**
+  `rails_read_logs` read the comment as SQL, so where the statement named a
+  secret column, the first tag's value (`/*application='App'*/`) was
+  filtered. A tag is now filtered only when its key names a secret, in the
+  `key='value'` and `key:value` forms; MySQL's `/*!` and `/*+` stay SQL.
+- **`live_reload: "false"` in `.rails-ai-context.yml` no longer turns live
+  reload on.** Any name was taken and meant auto. `true` and `false`, as
+  booleans or text, and `auto` now count; anything else warns and keeps auto
+  from the file, and raises ArgumentError from a configure block.
+- **A Ruby file the app cannot read no longer stops the static tier.** Since
+  5.36.8 the static tier reads the security settings an app's Ruby config
+  writes, and one file it could not open made every answer an error; no boot
+  loads that file either, so it now names no setting.
+- **A `BUNDLE_GEMFILE` inherited from another project is named.** The app
+  booted against that bundle and failed with a bare LoadError; the warning
+  bundle exec already had now covers the variable on its own.
+- **A running server survives `gem cleanup`.** The gem loads its files as it
+  needs them, so a tool call after its copy was removed raised a LoadError that
+  ended the server. A call that needs a file it has not loaded yet now answers
+  with an error that says to reconnect the server, or over HTTP to restart the
+  process serving it.
+- **A boot failure names the Ruby the app pins** when another one runs and the
+  failure can come from that, a missing gem or a load error, as when a client
+  starts in a monorepo's root that pins its own.
+- **No update notice where the app's lockfile names the version running.**
+  That lockfile decides the copy that serves the app, so `gem update` changed
+  nothing there.
+- **A lockfile rewritten within the clock's resolution is read again.** The
+  app's bundle was cached by modification time alone, so a second write in the
+  same tick kept the first answer.
+- **An app whose bundle has its own path runs its own copy.** Where `bundle
+  config set path`, a deployment bundle or `BUNDLE_PATH` put the gem under
+  the app, the installed copy served it and the app's boot loaded the
+  bundle's copy over it, two copies in one process, whichever version the
+  bundle locked. The bundle's path is now read as Bundler reads its settings.
+
 ## [5.36.8] - 2026-10-23
 
 ### Security

data/README.md

@@ -81,6 +81,12 @@ gem install rails-ai-context
 rails-ai-context init                                  # or: rails-ai-context init --tools claude --defaults
 ```
 
+As a Claude Code plugin, which adds the MCP server and gives each session the six rules below, and writes no context files or MCP config. It runs the installed gem, so install that first, with `gem install rails-ai-context` (or `bundle add` alone, when the bundle installs where your `ruby` looks). Run it in the app's folder, and commit the `.claude/settings.json` it writes; the install generator and `init` then leave Claude Code's `.mcp.json` to the plugin ([details](docs/SETUP.md#as-a-plugin)):
+
+```bash
+claude plugin install rails-ai-context --marketplace crisnahine/rails-ai-context --scope project
+```
+
 `--tools` takes `claude`, `cursor`, `copilot`, `opencode`, `codex` or `all`. Add `--cli` for context files only, or `--mcp-only` for the MCP config only. Re-running is safe: with `--defaults` it keeps your recorded tools and setup, keeps what you have and adds what is missing, and in a `CLAUDE.md` you wrote it only touches the block between its `<!-- BEGIN/END rails-ai-context -->` markers. Every step is in [What the install generator does](docs/GUIDE.md#what-the-install-generator-does).
 
 Needs Ruby 3.1+ and Rails 7.0+, on Linux, macOS or Windows. Optional: `brakeman` for `security_scan`, `listen` for `watch`, `ripgrep` for faster `search_code`.

data/docs/CLI.md

@@ -320,7 +320,7 @@ rails-ai-context uninstall
 bundle exec rails-ai-context uninstall   # in-Gemfile; then bundle remove rails-ai-context
 ```
 
-What you wrote stays: your lines around the markers in a shared `CLAUDE.md` or `AGENTS.md`, your rule files, other servers in an MCP config, and a pre-commit hook you changed by hand (named, not touched). Its own config files go even when you edited them: `.rails-ai-context.yml` and the initializer configure nothing once the gem is gone. An HTTP entry under the gem's name goes too, since only the gem's endpoint answers it. A `mount RailsAiContext::Engine` line in `config/routes.rb` is named with its line number for you to delete. In a folder of apps it uninstalls every app below and the folder's MCP configs. It needs no boot. An entry you added by hand to another client's own config from `mcp-entry` (Claude Desktop and the like) lives outside the app, so remove it there. Its last lines say how to remove the gem itself: `bundle remove rails-ai-context` when the Gemfile lists it, `gem uninstall rails-ai-context` once no other app uses the installed copy. Details in the [Guide](GUIDE.md#uninstalling).
+What you wrote stays: your lines around the markers in a shared `CLAUDE.md` or `AGENTS.md`, your rule files, other servers in an MCP config, and a pre-commit hook you changed by hand (named, not touched). Its own config files go even when you edited them: `.rails-ai-context.yml` and the initializer configure nothing once the gem is gone. An HTTP entry under the gem's name goes too, since only the gem's endpoint answers it. A `mount RailsAiContext::Engine` line in `config/routes.rb` is named with its line number for you to delete. In a folder of apps it uninstalls every app below and the folder's MCP configs. It needs no boot. An entry you added by hand to another client's own config from `mcp-entry` (Claude Desktop and the like) lives outside the app, so remove it there. Where the Claude Code plugin runs the gem, it names the commands that turn the plugin off and take it out ([SETUP](SETUP.md#as-a-plugin)), since the plugin's server fails once the gem is gone. Its last lines say how to remove the gem itself: `bundle remove rails-ai-context` when the Gemfile lists it, `gem uninstall rails-ai-context` once no other app uses the installed copy. Details in the [Guide](GUIDE.md#uninstalling).
 
 ### `mcp-entry`
 

data/docs/COMPATIBILITY.md

@@ -375,6 +375,16 @@ Proof sources:
    `--no-boot`, compared with v5.36.7 and every changed answer checked; the
    touched specs on Rails 7.0 (Ruby 3.1) and on prism 1.4; and the unit suite
    and the E2E harness on Linux, macOS and Windows.
+   In the v5.36.9 release QA: each fix's example failing on the code before
+   it; `doctor`'s plugin checks against what Claude Code 2.1.308 and 2.1.309
+   do with the same settings (marketplaces, enabled plugins, server command
+   and URL rules, managed files and `managed-mcp.json`), and the plugin's
+   launcher under Ruby 2.6 and 3.1; `rails_read_logs` and `rails_query` on
+   plural secret names and code lists, compared with v5.36.8 in a booted
+   SQLite app; the QA ladder on the SQLite labs in every tier, the E2E harness
+   and one large open-source app, booted; the unit suite on Ruby 3.4 and on
+   Rails 7.0 (Ruby 3.1); and the unit suite and the E2E harness on Linux,
+   macOS and Windows.
 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/GUIDE.md

@@ -159,7 +159,7 @@ rails-ai-context uninstall               # standalone; then, once no app uses it
 - The lines the install added to `.gitignore`, with their comments.
 - The pre-commit hook, when it is the one the install wrote and covers only this app. A hook that covers other apps of the repository loses this one; a hook changed by hand is named and left for you.
 
-A `mount RailsAiContext::Engine` line in `config/routes.rb` is your code, so it is named with its line number, not edited. Run in a folder of apps, it does the same for every app below and for the folder's MCP configs. It needs no boot, so it works on an app that cannot start, and the binary of any install can run it: in an app whose bundle pins a version from before `uninstall` existed, `gem install rails-ai-context` and run `rails-ai-context uninstall`.
+A `mount RailsAiContext::Engine` line in `config/routes.rb` is your code, so it is named with its line number, not edited. Run in a folder of apps, it does the same for every app below and for the folder's MCP configs. It needs no boot, so it works on an app that cannot start, and the binary of any install can run it: in an app whose bundle pins a version from before `uninstall` existed, `gem install rails-ai-context` and run `rails-ai-context uninstall`. Where the Claude Code plugin runs the gem, it first names the commands that turn the plugin off and take it out ([SETUP](SETUP.md#as-a-plugin)); a release from before the plugin names none, so turn it off yourself with `claude plugin disable rails-ai-context@rails-ai-context --scope local`.
 
 ---
 

data/docs/PROMPTS.md

@@ -276,8 +276,8 @@ rails-ai-context isn't working right in this Rails app. Find out why and fix it.
 1. Check the version: `bundle exec rails-ai-context version` if the Gemfile lists rails-ai-context, else `rails-ai-context version`. If it is older than 5.35.0, upgrade first (`bundle update rails-ai-context --conservative`, or `gem install rails-ai-context -v '>= 5.35.0'`) and check the version again: older versions read `--defaults` in step 5 as every AI tool. If the Gemfile pins it below 5.35.0, change its rails-ai-context line to `gem "rails-ai-context", ">= 5.35.0", group: :development` and run the update again.
 2. Run doctor: `bundle exec rails ai:doctor` if the Gemfile lists the gem, else `rails-ai-context doctor`. Read every failing or warning check and do what each one says.
 3. If doctor itself cannot run because the app won't boot, run `bundle exec rails-ai-context tool onboard --no-boot` (or without bundle exec when standalone) to confirm the tools still answer from source, and tell me what stops the boot.
-4. If my MCP tools are missing, open the MCP config file of the AI tool you are (Claude Code .mcp.json, Cursor .cursor/mcp.json, GitHub Copilot .vscode/mcp.json, OpenCode opencode.json, Codex CLI .codex/config.toml) and check it has a rails-ai-context entry. Run that entry's command and args by hand with `--help` added at the end, for example `bundle exec rails-ai-context serve --help`, and check it prints the serve usage.
-5. Repair the install by running it again: `bundle exec rails generate rails_ai_context:install --defaults` if the Gemfile lists the gem, otherwise `rails-ai-context init --defaults`. On a re-run `--defaults` keeps the recorded AI tools and setup, keeps what exists and adds what is missing. For Codex CLI after a Ruby version change, it also refreshes the Ruby paths saved in .codex/config.toml.
+4. If my MCP tools are missing, open the MCP config file of the AI tool you are (Claude Code .mcp.json, Cursor .cursor/mcp.json, GitHub Copilot .vscode/mcp.json, OpenCode opencode.json, Codex CLI .codex/config.toml) and check it has a rails-ai-context entry. Run that entry's command and args by hand with `--help` added at the end, for example `bundle exec rails-ai-context serve --help`, and check it prints the serve usage. With the Claude Code plugin (rails-ai-context@rails-ai-context enabled in .claude/settings.json, .claude/settings.local.json or my user settings, or doctor names the plugin) there is no entry: where its server has no tools, its instructions in your context say why and what to run; where /mcp lists it as failed, ask me to start `claude --debug` and read that server's stderr. `ruby -S gem list rails-ai-context` run here shows the versions the `ruby` Claude Code starts has.
+5. If doctor named a missing or broken MCP config, missing context files, or Codex's saved Ruby paths, repair the install by running it again: `bundle exec rails generate rails_ai_context:install --defaults` if the Gemfile lists the gem, otherwise `rails-ai-context init --defaults`. On a re-run `--defaults` keeps the recorded AI tools and setup, keeps what exists and adds what is missing. For Codex CLI after a Ruby version change, it also refreshes the Ruby paths saved in .codex/config.toml.
 6. Tell me what was wrong, what you changed, and the "Next step" lines the install printed if I need to do one.
 ```
 
@@ -288,7 +288,7 @@ Removes everything the gem wrote and nothing you wrote: your part of a shared `C
 ```text
 Remove rails-ai-context from this Rails app completely. If the rails-ai-context entry in my MCP config runs `docker` (this app's Ruby lives in a container), run steps 1 and 3 inside that container, prefixed the way the entry's args are.
 
-1. Run `bundle exec rails-ai-context uninstall` if the Gemfile lists rails-ai-context, else `rails-ai-context uninstall`. If the command is missing or unknown, run `gem install rails-ai-context -v '>= 5.35.0'` and then `rails-ai-context uninstall`.
+1. Run `bundle exec rails-ai-context uninstall` if the Gemfile lists rails-ai-context, else `rails-ai-context uninstall`. If the command is missing or unknown, run `gem install rails-ai-context -v '>= 5.35.0'` and then `rails-ai-context uninstall`. If its output names the Claude Code plugin, run the commands it names for it; if it does not, but rails-ai-context@rails-ai-context is enabled in .claude/settings.json, .claude/settings.local.json or my user settings, run `claude plugin disable rails-ai-context@rails-ai-context --scope local` here.
 2. If its output names a config/routes.rb line that mounts RailsAiContext::Engine, delete that line.
 3. If the Gemfile lists rails-ai-context, run `bundle remove rails-ai-context`.
 4. If .git/info/exclude lists rails-ai-context files (a private setup), delete those lines. If I added a rails-ai-context entry to another MCP client's own config (Claude Desktop, Windsurf, Zed and the like), remove that entry there too.

data/docs/SETUP.md

@@ -91,6 +91,197 @@ This is what the generator writes for an in-Gemfile install. A standalone instal
 
 On Windows the command is `cmd` and `"/c"` goes ahead of the args (`["/c", "bundle", "exec", "rails-ai-context", "serve"]`): a gem's executables there are batch files, which a client that starts its server without a shell does not run. The generator writes that form on Windows, and `doctor` names an entry written for the other platform; see [GUIDE.md](GUIDE.md#mcp-server-setup) for teams on both.
 
+### As a plugin
+
+The repository is also a Claude Code plugin marketplace. The plugin brings the
+MCP server and, at the start of each session in a Rails app, the six rules the
+context files open with. It writes no context files or MCP config, so it suits
+a team that keeps its own `CLAUDE.md`; the install records it in
+`.claude/settings.json`.
+
+```bash
+gem install rails-ai-context      # the plugin runs the installed gem
+claude plugin install rails-ai-context --marketplace crisnahine/rails-ai-context --scope project
+```
+
+In a session the second line is `/plugin install rails-ai-context --marketplace crisnahine/rails-ai-context`.
+A Claude Code too old for `--marketplace` takes two steps:
+`/plugin marketplace add crisnahine/rails-ai-context`, then
+`/plugin install rails-ai-context@rails-ai-context`. Project scope records the
+plugin in `.claude/settings.json` of the folder you run it in, so run it in the
+app's folder; commit that file, and add the marketplace there too so a
+teammate's Claude Code offers to install it:
+
+```json
+{
+  "enabledPlugins": { "rails-ai-context@rails-ai-context": true },
+  "extraKnownMarketplaces": {
+    "rails-ai-context": { "source": { "source": "github", "repo": "crisnahine/rails-ai-context" } }
+  }
+}
+```
+
+A teammate who has the committed setting runs `claude plugin install
+rails-ai-context --marketplace crisnahine/rails-ai-context --scope local`,
+which leaves the committed file as it is.
+
+- **Where it runs.** Claude Code reads `.claude/settings.json` only from the
+  folder a session starts in, so project scope reaches sessions started in the
+  app's folder. For sessions started in a folder inside the app, or in a
+  monorepo's app folder from the repository's root, enable it with `--scope
+  local` (the git repository's `settings.local.json`) or at user scope. The
+  server then reads the app Claude Code was started in, the app above that
+  folder, or the one app below it, as every command does. At user scope the
+  plugin starts in every project; outside a Rails app its server connects with
+  no tools and tells the session why. In a folder that holds several apps it
+  says to start Claude Code in one of them; for a session over all of them,
+  use the [workspace](CLI.md#init-standalone-only) entries `init` writes, and
+  turn the plugin off for that folder with `claude plugin disable
+  rails-ai-context@rails-ai-context --scope project` run there, or `--scope
+  local` where a `--scope local` install turns it on. On macOS and Linux a
+  local setting written at a git repository's root reaches every session in
+  that repository, the apps' too. On Windows, and where the repository's root
+  is your home folder or belongs to another user, a local setting reaches only
+  sessions started in the folder it was written in. Where `init` at a
+  repository's root wrote an app's own `.mcp.json`, which sessions started in
+  the app read, a `--scope local` install that reaches those sessions runs the
+  plugin beside it; `doctor` names the one to turn off.
+- **The gem comes first.** The plugin needs rails-ai-context 5.35.1 or later,
+  installed for the `ruby` on Claude Code's `PATH` (Ruby 3.1 or later); `gem
+  update rails-ai-context` brings an older one up. A shim version manager
+  (rbenv, asdf, or mise with its shims on `PATH`) picks that Ruby by the folder
+  Claude Code starts in: that folder's `.ruby-version` or `.tool-versions`, or
+  the global one, so a session started above the app runs that folder's Ruby. A
+  shell-hook one (rvm, chruby, `mise activate`) leaves the Ruby of the shell
+  that started Claude Code, and a Claude Code started from the Dock or an IDE
+  may see the system Ruby instead. An app that also has the gem in its Gemfile
+  gets its bundled copy, as with any standalone install, a bundle kept under
+  its own path such as `vendor/bundle` too. A copy from git is the exception:
+  the installed copy serves and the app's boot loads the git copy over it, so
+  point the Gemfile at a release or a `path:` checkout. When the plugin cannot
+  serve, its server still connects, with no tools, and tells the session why,
+  naming the Ruby and the folder: no gem for that Ruby, an older one, a Ruby
+  too old, a bundle Claude Code inherited from `bundle exec` that lacks the
+  gem, several apps or none. The same line is the server's stderr, which
+  `claude --debug` shows. A start that fails after that, from the gem's own
+  error or an inherited bundle not installed for that Ruby (Bundler's trace,
+  [TROUBLESHOOTING.md](TROUBLESHOOTING.md#mcp-server-fails-to-start)), is
+  listed as failed in `/mcp`, and Claude Code then skips the server in new
+  sessions for about 15 minutes: reconnect it in `/mcp` once the cause is
+  fixed. A session gets no rules while the server has no tools for them to
+  name.
+- **Install the gem, not its setup, for Claude Code.** Where the app's
+  `.claude/settings.json` turns the plugin on, the install generator and
+  `init` write no `.mcp.json` server and say why, and so does `init` in a
+  folder holding one app, where that folder's own `.claude/settings.json`
+  turns it on; it still writes the app's own `.mcp.json` for sessions started
+  in the app, which do not read that folder's settings, and says so. Where
+  only your own settings turn it on, they still write one for the team, and
+  their next step says to turn it off for yourself with `/mcp`.
+- **The plugin or another server, not both.** Claude Code starts the plugin's
+  server and one from `.mcp.json` or `claude mcp add`, an HTTP entry under the
+  gem's name included, as two servers and lists every tool twice. `doctor`
+  reads Claude Code the way a session does, by the folder it started in: that
+  folder's settings and the local settings that reach it (its git
+  repository's, a linked worktree's being its repository's, as "Where it runs"
+  says), every `.mcp.json` from that folder up, the `/mcp` toggles and local
+  servers Claude Code keeps for the repository, the MCP policy in
+  `allowedMcpServers` and `deniedMcpServers` (by name, command or url), and a
+  deployed `managed-mcp.json`, whose servers are then the only ones Claude
+  Code starts, each still subject to `/mcp` and `deniedMcpServers`, and to
+  `allowedMcpServers` where its entry expands a `${VAR}`, and the marketplace
+  policy in `strictKnownMarketplaces` and `blockedMarketplaces`. It follows a
+  `CLAUDE_CONFIG_DIR` set in your settings' `env` block, as Claude Code does.
+  It does not see settings an organization delivers from the Claude console,
+  through MDM or the Windows registry, and it reads the managed settings files
+  as if all of them were in force; where policy comes that way, its MCP
+  verdicts can be wrong. It checks the shape of `enabledPlugins` only, while
+  Claude Code ignores a whole settings file that breaks its schema elsewhere
+  and says so when it starts: fix such a file first. It looks at the app, the
+  folder `doctor` runs in, the folders above the app that hold it alone, and
+  the folders Claude Code keeps projects for. The plugin counts where it is
+  enabled, installed for that project, not turned off in `/mcp` and not
+  blocked by policy; then Claude Code's MCP check passes without a
+  `.mcp.json`, and with no AI tools chosen it checks no other tool's config
+  unless that config is broken. Where the plugin runs only for sessions
+  started in another folder, `doctor` names that folder and what turns it on
+  for this one. Where Claude Code never ran, as on CI, what the plugin needs
+  is a warning, not a failure. Where it runs nowhere, `doctor` names why: not
+  installed (with the install that leaves a committed file alone), a local
+  marketplace folder that is gone, its server turned off in `/mcp`, the MCP or
+  marketplace policy, a managed settings file Claude Code cannot read, or a
+  `CLAUDE_CONFIG_DIR` that is empty or not an absolute path, set in the
+  environment or a settings `env` block (`doctor` names which), which leaves
+  each session reading its own folder's. A second server counts where such a
+  session would start it, and `doctor` names the command that removes it and
+  the folder to run it in: a `.mcp.json` entry comes out where the committed
+  settings turn the plugin on, and is turned off with `/mcp` where only your
+  own settings do.
+- **The rules load once.** The hook skips them where Claude Code already loads
+  the generator's rules for that session: from the app's `CLAUDE.md` or
+  `.claude/rules/rails-mcp-tools.md`, or from its `AGENTS.md` where
+  `CLAUDE.md` imports it or no `CLAUDE.md` is on the way up from the folder
+  the session started in, or from a `CLAUDE.md`, `.claude/CLAUDE.md` or
+  `CLAUDE.local.md` on that way up that carries them, as an engine's above its
+  test/dummy app does (your own `~/.claude/CLAUDE.md` does not count). It
+  skips them too where `.rails-ai-context.yml` or a configure block in
+  `config/application.rb`, the environment's file or an initializer sets
+  `anti_hallucination_rules` to `false` or `nil`; a block's value wins over
+  the file's, as when the app boots. It reads that Ruby without running it, so
+  only a literal that ends its statement counts, and rule 3 leaves out the
+  `rails_get_config` sections `skip_tools` turns off, in the YAML or a literal
+  list, assigned or appended (`=`, `<<` chained or not, `+=`, `|=`, `push`,
+  `append`, `concat`); a symbol appended in place, a Set or a value built at
+  boot is not read, as the server skips none of those either. A session
+  started above the app gets the rules from the hook, and once a file in the
+  app is read, Claude Code also loads that app's `CLAUDE.md`, so such a
+  session can hold them twice. So can a session resumed after the app's
+  `CLAUDE.md` gained the rules (from `init`, `context` or a pull), until
+  `/clear` or a compaction.
+- **Windows works the same.** The server starts `ruby` without a shell, so it
+  needs no `cmd /c`.
+- **One allowlist entry lasts.** The server's command line names no plugin
+  folder, so no update changes it, and under an `allowedMcpServers` list this
+  entry admits it (`doctor` names it where it is missing). It admits any plugin
+  that ships the same line, too. Where the list admits other stdio servers by
+  `serverName`, adding this entry switches every stdio server to matching by
+  command, so each of them needs a `serverCommand` entry as well; `doctor`
+  says so. Naming no script also keeps rbenv from picking the Ruby by the
+  plugin's own folder.
+
+  ```json
+  {"serverCommand":["ruby","-e","load File.join(ENV.fetch('CLAUDE_PLUGIN_ROOT'), 'scripts', 'serve.rb')"]}
+  ```
+- **Permission rules name the plugin's server.** Its tools are
+  `mcp__plugin_rails-ai-context_rails-ai-context__<tool>`, so a rule for the
+  `.mcp.json` server (`mcp__rails-ai-context`) does not cover them;
+  `mcp__plugin_rails-ai-context_rails-ai-context` allows them all.
+- **A slow app's boot.** The plugin's server entry is the plugin's own, so set
+  `RAILS_AI_CONTEXT_BOOT_TIMEOUT` and `MCP_TIMEOUT` in Claude Code's settings
+  `env` (user, project or local) or in the shell that starts Claude Code; see
+  [TROUBLESHOOTING.md](TROUBLESHOOTING.md#answers-say-boot-did-not-finish-within-20s).
+- **Updates follow this repository.** The plugin's version is the commit it was
+  installed from. Claude Code updates it only with auto-update on (under
+  `/plugin`, Marketplaces) or `claude plugin update
+  rails-ai-context@rails-ai-context`. The server is versioned by the gem: `gem
+  update rails-ai-context`, then reconnect the server in `/mcp` or start a new
+  session. Run `gem cleanup` only after that: a running server loads its files
+  as it needs them, so once its copy is gone, a call that needs a file it has
+  not loaded yet answers with a request to reconnect it.
+- **Removing it** from one app is `claude plugin disable
+  rails-ai-context@rails-ai-context --scope local` run there, which wins over
+  your own and the committed settings for every session the local setting
+  reaches ("Where it runs"). Taking an install out is `claude plugin uninstall
+  rails-ai-context@rails-ai-context --scope <scope>`, with the scope it went in
+  at, run in the folder it was installed from: once for a user install, once
+  per project for a project or local one. A marketplace added from a local
+  folder or file runs the plugin with no install, so there only the disable
+  turns it off. The gem's `uninstall` leaves Claude Code's
+  settings alone and names those commands, one disable per repository whose
+  sessions run the plugin, before it suggests removing the gem, which the
+  plugin runs; where managed settings turn the plugin on, or a deployed
+  `managed-mcp.json` runs the gem, it says to ask whoever manages them.
+
 ### Split rules with `paths:` frontmatter
 
 Claude Code loads `.claude/rules/` files conditionally based on YAML frontmatter:

data/docs/STANDALONE.md

@@ -60,7 +60,7 @@ rails-ai-context version            # Show version
 1. **Loads only its boot shim** before the app - the binary requires the two files it needs to boot Rails, then `config/environment.rb`, and requires the gem itself only after the boot returns. Nothing it loads first is a gem an app pins: it reads the Gemfile and `config/boot.rb` with Ruby's own Ripper, not the prism gem, and loads json only once the app's bundle is set up
 2. **Restores `$LOAD_PATH`** entries that `Bundler.setup` strips (since the gem isn't in the Gemfile). The gem's own dependencies come off the load path for the duration of the boot, so every gem the app locks resolves to the app's pin, and go back behind it afterwards
 3. **YAML config** - uses `.rails-ai-context.yml` instead of a Ruby initializer
-4. **Steps aside for the app's own copy** - in an app whose bundle carries its own rails-ai-context (another installed version, or a `path:` copy), a command that boots the app runs through that copy, as `bundle exec rails-ai-context` would, and says so on stderr. That is the copy the app's MCP configs start, and two copies in one process would each load half the gem. The bundle is the one `BUNDLE_GEMFILE` names when you set it (a dual boot's `Gemfile.next`), and a command typed in a subdirectory runs from the app root it found. `init` asks its questions itself and has that copy write only the context files; an MCP-only setup, chosen with `--mcp-only` or at the prompt, runs nothing of the app's. So does `--no-boot`: bundle exec would evaluate the app's Gemfile and start whatever copy the app names, which on a repo just cloned is code nobody has read. A bundle not installed yet (`bundle check` fails) is left alone too: its boot fails, and the static tier answers. A copy installed only under a vendored bundle path or from git is not seen from outside the bundle, so there the installed copy runs
+4. **Steps aside for the app's own copy** - in an app whose bundle carries its own rails-ai-context (another installed version, or a `path:` copy), a command that boots the app runs through that copy, as `bundle exec rails-ai-context` would, and says so on stderr. That is the copy the app's MCP configs start, and two copies in one process would each load half the gem. The bundle is the one `BUNDLE_GEMFILE` names when you set it (a dual boot's `Gemfile.next`), and a command typed in a subdirectory runs from the app root it found. `init` asks its questions itself and has that copy write only the context files; an MCP-only setup, chosen with `--mcp-only` or at the prompt, runs nothing of the app's. So does `--no-boot`: bundle exec would evaluate the app's Gemfile and start whatever copy the app names, which on a repo just cloned is code nobody has read. A bundle not installed yet (`bundle check` fails) is left alone too: its boot fails, and the static tier answers. A copy installed under the bundle's own path (`bundle config set path vendor/bundle`, or a deployment bundle) is handed the run as well. A copy from git is not seen from outside the bundle, so there the installed copy runs and the app's boot loads the bundle's copy over it: in such an app, start the server with `bundle exec rails-ai-context`.
 
 This means you get the same 35 tools, same MCP server, same context generation - without touching the project's Gemfile.
 

data/docs/TROUBLESHOOTING.md

@@ -127,6 +127,8 @@ Codex reads `config.toml` as TOML, which is UTF-8, and loads nothing from a file
 - `can't find executable rails-ai-context for gem rails-ai-context`: the bundle's copy of the gem lists no executable, as a `path:` copy of 5.32.2 or earlier outside a git checkout does. Point the Gemfile at a git checkout or a release.
 - On Windows, a config that runs `bundle` or `rails-ai-context` itself rather than through `cmd /c`: those are batch files there, which Claude Code, Codex and the other clients that start a server without a shell do not run (`doctor` warns about it). Run the install again; on Windows it writes `cmd /c bundle exec rails-ai-context serve`.
 - On macOS or Linux, a config that runs `cmd /c ...`: it was written on Windows, and there is no `cmd` here (`doctor` fails it). Run the install again on this machine, and keep the MCP configs out of git if the team works on both.
+- The Claude Code plugin's server connects with no tools: it tells the session why (no gem for its Ruby, an older one, a Ruby too old, several apps or none) and what to run; `claude --debug` shows the same line as its stderr.
+- The Claude Code plugin's server is listed as failed in `/mcp`, and `claude --debug` shows a `Bundler::GemNotFound` trace in its stderr: Claude Code was started from `bundle exec`, or from a shell holding the `RUBYOPT` or `BUNDLER_SETUP` it sets, for a bundle not installed for the plugin's Ruby, which fails before the plugin runs. Start Claude Code outside `bundle exec`, or unset those two where a shell profile sets them. After a failed start Claude Code skips the server in new sessions for about 15 minutes, so reconnect it in `/mcp` once the cause is fixed.
 
 Check for Bundler/Ruby path issues:
 
@@ -148,8 +150,10 @@ command gives it 60. Start the service, or, for an app that is healthy but
 slow to boot, raise both limits in the server's MCP entry: the boot's with
 `RAILS_AI_CONTEXT_BOOT_TIMEOUT` (seconds) in its `env`, and the client's with
 its own setting (Claude Code reads `MCP_TIMEOUT`, in milliseconds). Raising
-only the boot's leaves a client that gives up first. `rails ai:serve` has no
-static tier, so it exits with the same message instead.
+only the boot's leaves a client that gives up first. The Claude Code plugin's
+entry is the plugin's own: set both in Claude Code's settings `env` (user,
+project or local) or in the shell that starts Claude Code. `rails ai:serve`
+has no static tier, so it exits with the same message instead.
 
 ### A server set up for a folder of apps fails to start