rails-ai-context 5.36.7 → 5.36.9

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.
 
@@ -117,7 +117,7 @@ A key the gem does not know warns on stderr and is ignored; the rest of the file
 
 ### Precedence
 
-In standalone mode `.rails-ai-context.yml` is the only config source. The gem is not loaded while `config/initializers` runs, so a `config/initializers/rails_ai_context.rb` contributes nothing: the generated file, which guards on `defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)`, is a silent no-op, and one without that guard raises `NoMethodError` (the binary opens the `RailsAiContext` namespace before the boot, so the constant exists but `configure` is not defined on it) and drops the command into the static tier.
+In standalone mode `.rails-ai-context.yml` is the only config source of a booted run. The gem is not loaded while `config/initializers` runs, so a `config/initializers/rails_ai_context.rb` contributes nothing there: the generated file, which guards on `defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)`, is a silent no-op, and one without that guard raises `NoMethodError` (the binary opens the `RailsAiContext` namespace before the boot, so the constant exists but `configure` is not defined on it) and drops the command into the static tier. On the static tier the gem reads the literal `sensitive_patterns`, `excluded_paths` and `skip_tools` values such a file writes, without running it ([SECURITY.md](SECURITY.md#configuration)).
 
 For in-Gemfile installs both sources apply and merge key by key - see [Precedence](CONFIGURATION.md#precedence).
 

data/docs/TOOLS.md

@@ -77,7 +77,7 @@ Search your codebase with regex, ripgrep acceleration, and sensitive file blocki
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
 | `pattern` | string | *required* | Regex pattern to search for. With `definition` or `class`, a plain method or constant name matches literally (`valid?`), anything else as a regex (`generate_.*`) |
-| `path` | string | - | Subdirectory or file to search (relative to Rails root); a file is searched whatever its type or ignore files say, as ripgrep does, unless it is sensitive |
+| `path` | string | - | Subdirectory or file to search (relative to Rails root); a file is searched whatever its type or ignore files say, as ripgrep does, unless it is sensitive or over `max_file_size` (`File too large`). A path through a link inside the app is searched as the folder it leads to |
 | `match_type` | enum | `any` | `any`, `definition` (def lines whose method name contains the pattern), `class` (class/module lines whose name contains it), `call`, `trace` |
 | `file_type` | string | - | Filter by extension (`rb`, `erb`, `js`, etc.) |
 | `exact_match` | boolean | `false` | Literal, whole-word match. `def reblog?` does not match `def reblog` |
@@ -566,7 +566,7 @@ ActiveSupport surface: concerns registry, deprecators, MessageVerifier/MessageEn
 
 #### `env` (was `rails_get_env`)
 
-Environment variables + credentials keys (values are never exposed). Scans `.rb`, `.rake`, ERB views and config YAML under `app`, `config` and `lib`, plus `config.ru`, `db/seeds.rb`, `db/seeds/` and the Ruby scripts in `bin/`. A tag on a YAML comment line is not read: ERB runs it, but what it writes goes with the comment. Config YAML matching `sensitive_patterns` (`config/database.yml`, `config/cable.yml`, `config/storage.yml` and the rest) is read only for the ENV names in its ERB tags, so a default there is listed as present and not read; credentials and keys are never read, and the answer says so. A default is read from a second argument or from a block whose one statement is a literal (`ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" }`). The env Kamal's `config/deploy.yml` gives the app container is listed too: secret names only, and clear values, except one holding a URL or a key-like token, or under a secret-named variable, which shows as hidden, and one an ERB tag sets, which says so. So are the setting keys in the config gem's `config/settings.yml` and `config/settings/<env>.yml` when the bundle has the config gem, and the attributes of each `Anyway::Config` class in `config/configs` or `app/configs` with the env name it reads (`PAYMENT_API_KEY`), never their values. A variable whose call sites pass different defaults is labelled as such rather than with one site's default; `detail:"full"` names each site's. A default is redacted by the rule a source literal gets: a credential format under any name, a URL's password, and under a secret-named variable a value that is not clearly something else, so an address, URL or hostname default prints as written.
+Environment variables + credentials keys (values are never exposed). Scans `.rb`, `.rake`, ERB views and config YAML under `app`, `config` and `lib`, plus `config.ru`, `db/seeds.rb`, `db/seeds/` and the Ruby scripts in `bin/`. A tag on a YAML comment line is not read: ERB runs it, but what it writes goes with the comment. Config YAML matching `sensitive_patterns` (`config/database.yml`, `config/cable.yml`, `config/storage.yml` and the rest) is read only for the ENV names in its ERB tags, so a default there is listed as present and not read; credentials and keys are never read, and the answer says so. A default is read from a second argument or from a block whose one statement is a literal (`ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" }`). The env Kamal's `config/deploy.yml` gives the app container is listed too: secret names only, and clear values, except one holding a URL or a key-like token, or under a secret-named variable, which shows as hidden, and one an ERB tag sets, which says so. A Dockerfile `ENV` or `ARG` value, an `.env.example` value and a default in code read `[FILTERED]` when their shape can carry a secret: a URL whose user part is a key or holds a password, a webhook's address, a token in a query, a key-like run of characters, or a `BUNDLE_<HOST>` gem server credential ([Credential handling](SECURITY.md#credential-handling)). An `.env.example` value in quotes keeps a `#`, and an inline comment is hidden when it holds a credential or one of those shapes. So are the setting keys in the config gem's `config/settings.yml` and `config/settings/<env>.yml` when the bundle has the config gem, and the attributes of each `Anyway::Config` class in `config/configs` or `app/configs` with the env name it reads (`PAYMENT_API_KEY`), never their values. A variable whose call sites pass different defaults is labelled as such rather than with one site's default; `detail:"full"` names each site's. A default is redacted by the rule a source literal gets: a credential format under any name, a URL's password, and under a secret-named variable a value that is not clearly something else, so an address, a hostname or a URL of none of the shapes above prints as written.
 
 #### `env_config` (was `rails_get_env_config`)
 
@@ -782,13 +782,13 @@ Each database other than the primary is reached through a connection handler of
 
 > Disabled in production by default.
 
-> Name the columns you need. A query is refused, with a message that says why, when it does one of these: it references a secret column (directly, or through an alias or expression; an `encrypts` column also when `query_allowed_columns` lists it); it serialises a whole row; it carries a column-alias list that renames a wildcard (a `VALUES`-body list such as `(VALUES (1,'a')) AS v(id, name)` is allowed, since it renames no table column); it uses UNION; it calls a session-effecting function, a function that returns a whole table as one value (`table_to_xml`), or any function by a quoted name; it reads a statistics, session or credential relation (`pg_stats`, `pg_stat_activity`, `pg_settings`, `performance_schema`, the `mysql` schema) or a PostgreSQL setting that can hold a password (`primary_conninfo`); it is a `SHOW` with a `WHERE` clause, `SHOW ALL` on PostgreSQL or `EXPLAIN FOR CONNECTION` on MySQL and MariaDB; or it is over 1,000,000 bytes long. `SELECT *` is allowed and its secret columns come back `[FILTERED]`. `SHOW CREATE TABLE` / `SHOW CREATE VIEW` are allowed and their definition text is secret-redacted; other `SHOW CREATE` forms are refused. In the default format a definition is shown whole, as the DDL in a fenced code block with its line breaks kept (a view's character set and collation follow as `name: value` lines); `csv` returns it as one quoted field. When the row limit holds rows back - only when the query really returned more than the cap - the answer says so in every format. With `csv`, a query that returns no rows answers the header row alone.
+> Name the columns you need. A query is refused, with a message that says why, when it does one of these: it references a secret column (directly, or through an alias or expression; an `encrypts` column also when `query_allowed_columns` lists it); it serialises a whole row; it carries a column-alias list that renames a wildcard (a `VALUES`-body list such as `(VALUES (1,'a')) AS v(id, name)` is allowed, since it renames no table column); it uses UNION; it calls a session-effecting function, a function that returns a whole table as one value (`table_to_xml`), or any function by a quoted name; it reads a statistics, session or credential relation (`pg_stats`, `pg_stat_activity`, `pg_settings`, `performance_schema`, the `mysql` schema) or a PostgreSQL setting that can hold a password (`primary_conninfo`); it is a `SHOW` with a `WHERE` clause, `SHOW ALL` on PostgreSQL, or `EXPLAIN FOR CONNECTION` or a `PROCEDURE` clause on MySQL and MariaDB; or it is over 1,000,000 bytes long. `SELECT *` is allowed and its secret columns come back `[FILTERED]`. `SHOW CREATE TABLE` / `SHOW CREATE VIEW` are allowed and their definition text is secret-redacted; other `SHOW CREATE` forms are refused. In the default format a definition is shown whole, as the DDL in a fenced code block with its line breaks kept (a view's character set and collation follow as `name: value` lines); `csv` returns it as one quoted field. When the row limit holds rows back - only when the query really returned more than the cap - the answer says so in every format. With `csv`, a query that returns no rows answers the header row alone.
 
 > **Cell rendering by format.** A `markdown` table cell shows `NULL` as `_NULL_`, escapes a pipe (`a\|b`) so it cannot end the cell, renders a line break as the two characters `\n` so it cannot end the row, and shortens a value over 100 characters to `…` (a `SHOW CREATE` definition is not a table cell, so it is never shortened). A `csv` cell is the value itself: `NULL` is an empty field, nothing is escaped beyond RFC 4180 quoting (a field holding a comma, a quote or a line break is wrapped in quotes with its quotes doubled), and nothing is truncated - so a line break stays a real line break inside the quoted field. Binary (non-text) data shows as `[BLOB]` in both.
 
 ### `rails_read_logs`
 
-Reverse file tail with level filtering and sensitive data redaction.
+Reverse file tail with level filtering and sensitive data redaction. A value an SQL statement holds inline is filtered when the column it meets is a secret, and so are the values a database error repeats ([Redaction](SECURITY.md#redaction)).
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -822,7 +822,7 @@ A changed migration lists the tables it affects: the table each schema method ta
 
 An app in a subfolder of its repository (a monorepo's `backend/`) is reviewed on its own: its changed files, named from the app root as `rails_validate` takes them, and the commits that touched it.
 
-Each diff passes through the redaction every tool's source does, read as the file it comes from, so a secret a change adds or takes out reads `[FILTERED]`, in a hunk header's line too. A changed file on `sensitive_patterns` (`config/database.yml`, `.env`, a key) is listed with its line counts and none of its lines.
+Each diff line is shown as the line of its side, redacted with the whole of that side the way every tool's source is, so a secret a change adds or takes out reads `[FILTERED]`, and so does a key's body in a hunk that opens inside the key, in a hunk header's line too. A changed file on `sensitive_patterns` (`config/database.yml`, `.env`, a key) is listed with its line counts and none of its lines, and so is one whose diff is over `max_file_size` and a merge conflict's combined diff. The diff is read with the repository's colour, external diff and textconv settings off, and a submodule's change shows as the commits it moves between.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|

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
 

data/exe/rails-ai-context

@@ -311,12 +311,13 @@ class RailsAiContextCLI < Thor
       # gets less than that.
       if options[:transport] == "stdio"
         entry_boot
+        require_relative "../lib/rails_ai_context/boot_manager"
         ::RailsAiContext::BootManager.default_timeout = ::RailsAiContext::BootManager::STDIO_TIMEOUT
       end
 
       # Live reload uses `listen` when it is there, standalone included.
       reach_installed_gem("listen")
-      boot_rails!(command: "serve", allow_static: true)
+      boot_rails!(command: "serve", allow_static: true, client: options[:transport] == "stdio")
 
       transport = options[:transport].to_sym
       # No Thor default: it would overwrite the config file's http_port.
@@ -503,7 +504,8 @@ class RailsAiContextCLI < Thor
       program.remove_mcp_entries(program_surface, unwired, root: Dir.pwd)
       program.remove_context_files(program_surface, ai_tools, root: Dir.pwd) if stale
       record_selection(ai_tools, tool_mode, context_files)
-      write_mcp_configs(ai_tools, tool_mode)
+      written = write_mcp_configs(ai_tools, tool_mode)
+      held = written[:held] || []
       add_to_gitignore(context_files)
 
       if bundled
@@ -519,7 +521,7 @@ class RailsAiContextCLI < Thor
       end
 
       # --- Instructions ---
-      show_standalone_instructions(ai_tools, tool_mode, context_files, removed: stale)
+      show_standalone_instructions(ai_tools, tool_mode, context_files, removed: stale, held: held, plugin_off: written[:plugin_off])
     end
 
     desc "uninstall", "Remove what rails-ai-context wrote: context files, MCP entries, its config, .gitignore lines and pre-commit hook"
@@ -541,6 +543,9 @@ class RailsAiContextCLI < Thor
       bundled = app_roots.any? { |app| bundled_app?(app) }
       where = display_place || (resolution.workspace? ? "this folder" : "this app")
       $stderr.puts ""
+      require_relative "../lib/rails_ai_context/install/claude_plugin_removal"
+      ::RailsAiContext::Install::ClaudePluginRemoval.lines(app_roots, cwd: @app_root_result&.cwd || Dir.pwd, workspace: resolution.workspace?)
+                                                   .each { |line| $stderr.puts line }
       if changed
         $stderr.puts "rails-ai-context is uninstalled from #{where}. To remove the gem itself:"
       else
@@ -742,8 +747,10 @@ class RailsAiContextCLI < Thor
     def write_mcp_configs(ai_tools, tool_mode, root: Dir.pwd, servers: nil)
       standalone = servers ? nil : ::RailsAiContext::InstallMode.standalone?(root: root)
       in_starting_env do
+        there = run_there(root).delete_prefix(" run in ")
         ::RailsAiContext::Install::Program.write_mcp_configs(
-          program_surface, tools: ai_tools, tool_mode: tool_mode, root: root, servers: servers, standalone: standalone
+          program_surface, tools: ai_tools, tool_mode: tool_mode, root: root, servers: servers, standalone: standalone,
+          place: (there unless there.empty?)
         )
       end
     end
@@ -827,7 +834,8 @@ class RailsAiContextCLI < Thor
       end
 
       $stderr.puts ""
-      write_mcp_configs(ai_tools, tool_mode, root: dir, servers: configured.map(&:server))
+      written = write_mcp_configs(ai_tools, tool_mode, root: dir, servers: configured.map(&:server))
+      held = written[:held] || []
       # This folder's own .gitignore, when it has one: the Codex config here
       # embeds this machine's PATH and GEM_HOME too.
       add_to_gitignore(false, root: dir)
@@ -845,7 +853,7 @@ class RailsAiContextCLI < Thor
         $stderr.puts "MCP-only setup: no context files written."
       end
 
-      show_workspace_instructions(dir, apps, ai_tools, tool_mode, context_files, configured: configured)
+      show_workspace_instructions(dir, apps, ai_tools, tool_mode, context_files, configured: configured, held: held, plugin_off: written[:plugin_off])
       return if failed.empty?
 
       $stderr.puts "Error: no context files for #{failed.map { |app| "#{app.path}/" }.join(', ')} - see the output above. " \
@@ -927,7 +935,7 @@ class RailsAiContextCLI < Thor
               "= #{spec.version}" ], false ]
     end
 
-    def show_workspace_instructions(dir, apps, ai_tools, tool_mode, context_files, configured: apps)
+    def show_workspace_instructions(dir, apps, ai_tools, tool_mode, context_files, configured: apps, held: [], plugin_off: false)
       $stderr.puts ""
       $stderr.puts "=" * 50
       $stderr.puts " rails-ai-context initialized for #{apps.size == 1 ? '1 app' : "#{apps.size} apps"}"
@@ -940,10 +948,16 @@ class RailsAiContextCLI < Thor
 
         # The MCP config is this folder's, so it leaves the per-app list.
         files = context_files ? "#{tool.files_label(mcp: false)} in each app" : "no context files"
-        files = "#{tool.mcp_config[:path]} #{where}; #{files}" if tool_mode == :mcp
+        # A committed plugin serves where no server was written, and the app's own .mcp.json its own sessions.
+        if tool_mode == :mcp
+          served = held.include?(tool.key) ? plugin_label(plugin_off) : "#{tool.mcp_config[:path]} #{where}"
+          own = configured.one? && held.include?(tool.key) && ::RailsAiContext::Install::Program.app_mcp_json(dir, configured.first.root)
+          served += ", and #{configured.first.path}/.mcp.json for sessions started in #{configured.first.path}" if own
+          files = "#{served}; #{files}"
+        end
         $stderr.puts "  #{tool.name.ljust(16)} -> #{files}"
       end
-      if tool_mode == :mcp && configured.any?
+      if tool_mode == :mcp && configured.any? && (ai_tools - held).any?
         $stderr.puts ""
         $stderr.puts "MCP servers, one per app:"
         width = configured.map { |app| app.server_name.size }.max
@@ -959,7 +973,8 @@ class RailsAiContextCLI < Thor
       first = app_root.command_line([ app_root.option_path(app_root.display(example.root, Dir.pwd)) ])
       if tool_mode == :mcp && configured.any?
         $stderr.puts ""
-        say_next_steps(ai_tools)
+        # A folder holding one app is one the plugin serves.
+        say_next_steps(ai_tools, root: (dir if configured.one?), app: configured.first&.root)
       end
       $stderr.puts ""
       $stderr.puts "Commands, from here:"
@@ -972,18 +987,32 @@ class RailsAiContextCLI < Thor
       $stderr.puts ""
     end
 
+    # Where a command has to run, when that is not where this one was typed.
+    def run_there(folder)
+      cwd = @app_root_result&.cwd or return ""
+      return "" if ::RailsAiContext::SafePath.canonical(folder) == ::RailsAiContext::SafePath.canonical(cwd)
+
+      " run in #{app_root.display(folder, cwd)}"
+    end
+
     # Whether the app's bundle starts the gem. An app with no Gemfile has no
     # bundle at all, which InstallMode, unable to read one, counts as bundled.
     def bundled_app?(root)
       File.file?(File.join(root.to_s, "Gemfile")) && !::RailsAiContext::InstallMode.standalone?(root: root)
     end
 
-    def say_next_steps(ai_tools)
+    def say_next_steps(ai_tools, root: nil, app: root)
       $stderr.puts "Next step, before the MCP tools appear:"
-      ::RailsAiContext::Install::Program.next_steps(ai_tools).each { |line| $stderr.puts "  #{line}" }
+      place = root && run_there(root).sub(" run in ", "in ")
+      ::RailsAiContext::Install::Program.next_steps(ai_tools, root: root, place: place.to_s.empty? ? "here" : place, app: app).each { |line| $stderr.puts "  #{line}" }
+    end
+
+    # The next step names what serves instead where the committed plugin does not start for this user.
+    def plugin_label(off)
+      off ? "the rails-ai-context plugin (off here: see below)" : "the rails-ai-context plugin"
     end
 
-    def show_standalone_instructions(ai_tools, tool_mode, context_files = true, removed: false)
+    def show_standalone_instructions(ai_tools, tool_mode, context_files = true, removed: false, held: [], plugin_off: false)
       $stderr.puts ""
       $stderr.puts "=" * 50
       $stderr.puts " rails-ai-context initialized!"
@@ -992,7 +1021,9 @@ 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)} -> #{context_files ? tool.files_label(mcp: tool_mode == :mcp) : 'MCP config only'}"
+        files = context_files ? tool.files_label(mcp: tool_mode == :mcp) : "MCP config only"
+        files = context_files ? "#{plugin_label(plugin_off)}; #{files}" : plugin_label(plugin_off) if held.include?(tool.key)
+        $stderr.puts "  #{tool.name.ljust(16)} -> #{files}"
       end
       unless context_files || removed
         $stderr.puts ""
@@ -1015,7 +1046,7 @@ class RailsAiContextCLI < Thor
       $stderr.puts "  #{binary} doctor     # Check AI readiness"
       $stderr.puts ""
       if tool_mode == :mcp
-        say_next_steps(ai_tools)
+        say_next_steps(ai_tools, root: Dir.pwd)
       else
         $stderr.puts "CLI tools:"
         $stderr.puts "  AI agents can run `rails-ai-context tool schema table=users` directly."
@@ -1112,9 +1143,9 @@ class RailsAiContextCLI < Thor
     # A command that needs more than the tier gives it says so here rather
     # than being recognised by name.
     def boot_rails!(command:, allow_static: false, no_boot: false, allow_source_only: allow_static,
-                    boot_failure_hint: nil)
+                    boot_failure_hint: nil, client: false)
       outcome = enter_app(command: command, allow_static: allow_static, no_boot: no_boot,
-                          allow_source_only: allow_source_only)
+                          allow_source_only: allow_source_only, client: client)
       outcome.messages.each { |line| $stderr.puts line }
       return unless outcome.tier == :absent
 
@@ -1125,7 +1156,7 @@ class RailsAiContextCLI < Thor
 
     # The app this command reads, booted or read from source as the command
     # allows. Prints nothing: the outcome carries the lines to say.
-    def enter_app(command:, allow_static:, no_boot:, allow_source_only:)
+    def enter_app(command:, allow_static:, no_boot:, allow_source_only:, client: false)
       # Read by the hand-off, which resolving the root may start: `tool`
       # takes --no-boot after the tool's name, where Thor never sees it.
       @no_boot = true if no_boot
@@ -1141,7 +1172,8 @@ class RailsAiContextCLI < Thor
       # A command that can serve the static tier reads a source-only tree
       # instead of refusing it.
       entry_boot.call(root: Dir.pwd, allow_static: allow_static, no_boot: no_boot || options[:no_boot],
-                      allow_source_only: allow_source_only, command: command, doctor: doctor_command, shown: shown_root)
+                      allow_source_only: allow_source_only, command: command, doctor: doctor_command, shown: shown_root,
+                      client: client)
     end
 
     # Which app this command reads, decided once and before anything reads
@@ -1194,6 +1226,7 @@ class RailsAiContextCLI < Thor
       warning = app_root.bundle_warning(result.root, cwd) if entry_boot.app_present?(result.root, allow_source_only: true)
       $stderr.puts warning if warning
       hand_off_to_bundle!(result.root, cwd) if hand_off
+      @start_update_check&.pinned! if app_root.pinned?(result.root)
       result
     end
 
@@ -1377,7 +1410,7 @@ class RailsAiContextCLI < Thor
       %w[
         gem_lock install/ai_tool install/selection_record install/cleanup
         install/surface install/validation_hook install/program install/uninstall mcp_config_generator install/workspace
-        legacy_cleanup
+        legacy_cleanup claude_code_settings
       ].each { |file| require_relative "../lib/rails_ai_context/#{file}" }
 
       # Both are defined in the entry file, which is the thing that must not

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

@@ -100,11 +100,13 @@ module RailsAiContext
       # itself the generator reads Rails.root's, which is an engine's dummy
       # app.
       def create_mcp_config
-        RailsAiContext::Install::Program.write_mcp_configs(
+        written = RailsAiContext::Install::Program.write_mcp_configs(
           program_surface,
           tools: @selected_formats, tool_mode: @tool_mode, root: install_root,
           standalone: RailsAiContext::InstallMode.standalone?(root: install_root)
         )
+        @held = written[:held]
+        @plugin_off = written[:plugin_off]
         program = RailsAiContext::Install::Program
         unless context_files?
           @removed_context_files = program.ask_context_removal(program_surface, tools: @selected_formats, root: install_root,
@@ -801,6 +803,8 @@ module RailsAiContext
         RailsAiContext::Install::AiTool.all.each do |tool|
           next unless @selected_formats.include?(tool.key)
           files = context_files? ? tool.files_label(mcp: tool_mode == :mcp) : "MCP config only"
+          plugin = @plugin_off ? "the rails-ai-context plugin (off here: see below)" : "the rails-ai-context plugin"
+          files = context_files? ? "#{plugin}; #{files}" : plugin if Array(@held).include?(tool.key)
           say "  ✅ #{tool.name.ljust(16)} -> #{files}"
         end
         unless context_files? || @removed_context_files
@@ -816,7 +820,7 @@ module RailsAiContext
         say ""
         if @tool_mode == :mcp
           say "Next step, before the MCP tools appear:", :yellow
-          RailsAiContext::Install::Program.next_steps(@selected_formats).each { |line| say "  #{line}" }
+          RailsAiContext::Install::Program.next_steps(@selected_formats, root: install_root).each { |line| say "  #{line}" }
         else
           say "CLI tools:", :yellow
           example = engine_root ? "bundle exec rails-ai-context tool schema --table users" : "rails 'ai:tool[schema]' table=users"
@@ -825,8 +829,8 @@ module RailsAiContext
         end
         say ""
         show_more_tools
-        committed = [ ("context files" if context_files?), ("MCP configs" if tool_mode == :mcp) ].compact
-        say "Commit the #{committed.join(' and ')} so your team benefits!", :green
+        committed = [ ("context files" if context_files?), ("MCP configs" if tool_mode == :mcp && (@selected_formats - Array(@held)).any?) ].compact
+        say "Commit the #{committed.join(' and ')} so your team benefits!", :green if committed.any?
         # Only where a Codex config was written, and only while a commit
         # would still take it along.
         if tool_mode == :mcp && @selected_formats.include?(:codex) &&

data/lib/rails_ai_context/boot_manager.rb

@@ -138,7 +138,13 @@ module RailsAiContext
 
       Result.new(status: :failed, error: BootError.new("config/environment.rb loaded but defined no Rails application"))
     rescue SystemExit => e
-      Result.new(status: :failed, error: BootExitError.new("App called exit(#{e.status}) during boot"))
+      # Bundler in a terminal exits on a missing gem; keeping its error as the cause lets callers name it.
+      error = begin
+        raise BootExitError, "App called exit(#{e.status}) during boot", cause: e.cause
+      rescue BootExitError => raised
+        raised
+      end
+      Result.new(status: :failed, error: error)
     end
 
     # The same three protections for callers that boot through their own