rails-ai-context 5.32.2 → 5.34.0

data/exe/rails-ai-context

@@ -45,10 +45,58 @@ PREBOOT_GEM_SPECS = preboot_gem_specs.freeze
 # entry puts those back, so re-registering their specs would tell it not to.
 PREBOOT_FRAMEWORK_NAMES = preboot_framework_names.freeze
 
+# A C or POSIX locale names no encoding, so Ruby tags every path it reads -
+# the working directory, $HOME, a glob - binary or US-ASCII, and the first
+# one outside ASCII can be neither compared with nor joined to the gem's own
+# UTF-8 strings. Rails makes UTF-8 the default when it boots; this binary
+# reads paths and files before any boot, so it does the same first, for
+# them and for the arguments it was given - when they are UTF-8. A folder
+# or an argument in another encoding (Latin-1 bytes on disk) keeps the
+# locale's tags, under which it is read byte by byte as before.
+if Encoding.default_external == Encoding::US_ASCII
+  utf8 = ->(text) { text.dup.force_encoding(Encoding::UTF_8).valid_encoding? }
+  if (utf8.call(Dir.pwd) rescue false) && ARGV.all?(&utf8)
+    verbose, $VERBOSE = $VERBOSE, nil
+    Encoding.default_external = Encoding::UTF_8
+    $VERBOSE = verbose
+    ARGV.map! { |arg| arg.dup.force_encoding(Encoding::UTF_8) }
+  end
+end
+
+# This file, wherever the gem is installed: what a child re-entering this very
+# copy runs when no installed spec names it.
+EXE_PATH = File.expand_path(__FILE__).freeze
+
+# The command as typed, for the run a handoff to the app's bundled copy starts.
+ORIGINAL_ARGV = ARGV.dup.freeze
+
+# The environment this binary was started in, before an app's boot sets up
+# the app's bundle in it.
+STARTING_ENV = ENV.to_h.freeze
+
+# How the person who ran init in a folder of apps names the app a child
+# `context` of it runs in. The child runs at the app's root, and the files
+# it reports - the rm line for legacy files among them - are named from
+# where init was run, so a line pasted there does what it says. A variable
+# rather than a flag: an app whose bundle pins an older gem ignores it.
+PLACE_ENV = "RAILS_AI_CONTEXT_PLACE"
+
+# Where a command handed to the app's bundle was typed. The handoff starts
+# that copy at the app's root when it walked there from a folder inside the
+# app or above it, and doctor writes each fix's command to run where it was
+# typed. A variable for the same reason as PLACE_ENV.
+TYPED_IN_ENV = "RAILS_AI_CONTEXT_TYPED_IN"
+
+# The first release whose `context` takes --no-mcp-refresh. An older copy
+# refuses a switch it does not know, and it writes no MCP config in
+# `context` either.
+MCP_REFRESH_FLAG_SINCE = "5.33.0"
+
 # After one of these tools' names `--environment` is its filter, never RAILS_ENV: this is
 # decided before boot, when no tool schema can load. cli_smoke_spec holds it to the schemas.
 ENVIRONMENT_PARAM_TOOLS = %w[env_config].freeze
 
+require "shellwords"
 require "thor"
 
 # Top-level class to avoid conflict with RailsAiContext::CLI module (which contains ToolRunner).
@@ -66,18 +114,69 @@ class RailsAiContextCLI < Thor
       true
     end
 
+    # The words Thor is handed: switches behind the command name, and a
+    # command's --help turned into `help <command>`.
+    def self.normalize_argv(argv)
+      help_request(reorder_switches(argv))
+    end
+
+    # Every switch this binary declares, global or per-command, and its type.
+    def self.switch_types
+      declared = class_options.values + commands.each_value.flat_map { |c| c.options.values }
+      declared.each_with_object({}) do |option, table|
+        ([ option.switch_name ] + Array(option.aliases)).each { |name| table[name] = option.type }
+      end
+    end
+
+    HELP_FLAGS = %w[--help -h].freeze
+
+    # `<command> --help` asks for that command's help, which Thor only gives
+    # as `help <command>`: it read the flag as an argument the command does
+    # not take, and `tool` and `preset` as the name to run. After a tool's
+    # name the flag is that tool's (`tool schema --help` lists its params).
+    def self.help_request(argv)
+      command, *rest = argv
+      return argv if command.nil? || command.start_with?("-") || command == "help"
+
+      at = rest.index { |arg| HELP_FLAGS.include?(arg) } or return argv
+      return argv if command == "tool" && named_tool?(rest.first(at))
+
+      [ "help", command ]
+    end
+
+    # Whether these words after `tool` hold a tool name: a word that is
+    # neither a switch nor the value a switch before it takes.
+    def self.named_tool?(words)
+      types = switch_types
+      value_next = false
+      words.each do |word|
+        if value_next
+          value_next = false
+        elsif word.start_with?("-")
+          type = types[word.split("=", 2).first]
+          value_next = !word.include?("=") && !type.nil? && type != :boolean
+        else
+          return true
+        end
+      end
+      false
+    end
+
+    # Thor names the command by its method in an argument error, and
+    # `inspect` is defined as inspect_app; the name a user types is the
+    # first word of the command's usage.
+    def self.handle_argument_error(command, error, args, arity)
+      super(command.dup.tap { |public_name| public_name.name = command.usage.split.first }, error, args, arity)
+    end
+
     # Thor reads a leading switch as "no command given" and falls back to
     # `help`, which answers `rails-ai-context --app-path /x doctor` with usage
     # and exit 0. Move every switch this binary declares
     # (global or per-command) behind the command name; anything else is left
     # where it is, so `--help`, `--version` and an unknown switch keep their
     # own answers.
-    def self.normalize_argv(argv)
-      declared = class_options.values + commands.each_value.flat_map { |c| c.options.values }
-      switches = declared.each_with_object({}) do |option, table|
-        ([ option.switch_name ] + Array(option.aliases)).each { |name| table[name] = option.type }
-      end
-
+    def self.reorder_switches(argv)
+      switches = switch_types
       globals = []
       rest = argv.dup
       while (token = rest.first) && token.start_with?("-")
@@ -119,7 +218,7 @@ class RailsAiContextCLI < Thor
     map %w[--version -v] => :version
 
     class_option :app_path, type: :string,
-      desc: "Path to the Rails app root (default: current directory)"
+      desc: "Path to the Rails app root (default: the app the current directory is in, or the one app below it)"
     class_option :environment, type: :string,
       desc: "RAILS_ENV to run under (default: the ambient RAILS_ENV or development)"
 
@@ -173,11 +272,32 @@ class RailsAiContextCLI < Thor
       exit 1 if runner.error
     end
 
+    # What Server#start takes; the gem's server cannot be loaded to ask it
+    # before the app boots. streamable_http is http's other name there.
+    SERVE_TRANSPORTS = %w[stdio http streamable_http].freeze
+
     desc "serve", "Start MCP server (stdio transport)"
     option :transport, type: :string, default: "stdio", desc: "Transport: stdio or http"
     option :port, type: :numeric, desc: "HTTP port (only for http transport; default: config http_port, else 6029)"
     option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
     def serve
+      # Checked before the boot, which can take a minute, and in the words
+      # the option is typed in rather than as Ruby symbols.
+      unless SERVE_TRANSPORTS.include?(options[:transport])
+        $stderr.puts "Error: Unknown transport '#{options[:transport]}'. Use stdio or http."
+        exit 1
+      end
+
+      # A stdio client is waiting for the answer to `initialize` and gives up
+      # after about 30 seconds; BootManager::STDIO_TIMEOUT says why the boot
+      # gets less than that.
+      if options[:transport] == "stdio"
+        entry_boot
+        ::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)
 
       transport = options[:transport].to_sym
@@ -190,6 +310,13 @@ class RailsAiContextCLI < Thor
     desc "context", "Generate AI context files"
     option :format, type: :string, default: nil, desc: "Format: claude, cursor, copilot, opencode, codex, json, all (default: from config)"
     option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
+    # For the installer, which writes the MCP configs itself just before it
+    # runs this at an engine's root.
+    option :mcp_refresh, type: :boolean, default: true, hide: true
+    # For doctor, which runs this at an engine's root into a copy of the
+    # context files to see which a run would rewrite: the files go there,
+    # and nothing else is touched - no MCP config, no legacy file.
+    option :output_dir, type: :string, hide: true
     def context
       # A repo you have just cloned is the case an agent most needs these files
       # for, and it is the case least likely to boot. Every command that reads
@@ -206,7 +333,8 @@ class RailsAiContextCLI < Thor
       else
         cleanup_tools = ::RailsAiContext.configuration.ai_tools
       end
-      ::RailsAiContext::LegacyCleanup.prompt_legacy_files(cleanup_tools, root: Dir.pwd)
+      output_dir = options[:output_dir]
+      ::RailsAiContext::LegacyCleanup.prompt_legacy_files(cleanup_tools, root: Dir.pwd, place: display_place) unless output_dir
 
       # An explicit --format names a file, so it is written either way. With
       # no format and an MCP-only install there is nothing to write, and the
@@ -218,6 +346,13 @@ class RailsAiContextCLI < Thor
         return
       end
 
+      # `rails ai:context` brings the selected tools' MCP configs up to date
+      # on every run, in the form the install takes now. So does this, or an
+      # app taken out of its bundle got context files naming the binary
+      # beside configs that still start `bundle exec`.
+      refresh_mcp_configs if options[:format].nil? && options[:mcp_refresh] && !output_dir
+      ::RailsAiContext.configuration.output_dir = File.expand_path(output_dir) if output_dir
+
       $stderr.puts "Introspecting Rails app..."
 
       # An explicit --format overrides the recorded selection.
@@ -244,18 +379,43 @@ class RailsAiContextCLI < Thor
     desc "watch", "Watch for changes and auto-regenerate context files"
     option :no_boot, type: :boolean, default: false, desc: "Skip booting the app; serve static analysis only"
     def watch
+      reach_installed_gem("listen")
       boot_rails!(command: "watch", allow_static: true)
-      ::RailsAiContext::Watcher.new.start
+      ::RailsAiContext::Watcher.new(place: display_place).start
     end
 
     desc "doctor", "Run diagnostic checks and report AI readiness score"
     option :strict, type: :boolean, default: false, desc: "Exit 1 when any check fails (CI gate)"
+    # Declared so the flag every other command takes is refused in words,
+    # not with Thor's "was called with arguments"; hidden from the help.
+    option :no_boot, type: :boolean, default: false, hide: true
     def doctor
+      if options[:no_boot]
+        $stderr.puts "Error: doctor diagnoses the app's boot, so it cannot skip it. Run it without --no-boot."
+        exit 1
+      end
+
+      # The live reload check asks for `listen` as serve would find it.
+      reach_installed_gem("listen")
+      # An engine's root boots no app of its own, so doctor diagnoses the
+      # dummy app its bin/rails boots, and reads the install at the root.
+      resolution = resolve_app_root!
+      # Where this was typed, a folder inside the app included, where each
+      # command a fix gives runs. A run handed to the app's bundle started at
+      # the app's root, and is told.
+      typed = STARTING_ENV[TYPED_IN_ENV] || resolution.cwd
+      if (dummy = app_root.dummy_app(Dir.pwd))
+        # Named from the root found, when that was typed inside it.
+        root = resolution.root
+        shown_from = root && (typed == root || typed.start_with?("#{root}/")) ? root : typed
+        $stderr.puts "[rails-ai-context] an engine's root boots no app: diagnosing its dummy app at #{app_root.display(dummy, shown_from)}/"
+        Dir.chdir(dummy)
+      end
       # Diagnosing a boot failure needs the app, so doctor never serves the
       # static tier; it does read a source-only tree, to name what is missing.
       boot_rails!(command: "doctor", allow_source_only: true,
                   boot_failure_hint: "  doctor needs a bootable app; fix the boot error above first.")
-      result = ::RailsAiContext::Doctor.new.run
+      result = ::RailsAiContext::Doctor.new(from: typed).run
       # The report is the command's product - it belongs on stdout so
       # `doctor > report.txt` captures it. stderr stays for errors only.
       puts ::RailsAiContext::Doctor.report_lines(result)
@@ -274,45 +434,47 @@ class RailsAiContextCLI < Thor
     option :mcp_only, type: :boolean, default: false,
       desc: "Write the MCP config and nothing else: no CLAUDE.md, AGENTS.md, rules files or .ai-context.json"
     def init
-      unless entry_boot.app_present?(Dir.pwd, allow_source_only: true)
-        $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
-        $stderr.puts "Run this command from your Rails app root directory."
-        exit 1
-      end
+      resolution = resolve_app_root!(workspace: true, hand_off: false)
+      return init_workspace(resolution.base, resolution.below) if resolution.workspace?
+
+      refuse_no_app! unless entry_boot.app_present?(Dir.pwd, allow_source_only: true)
 
       require_install_files!
+      program = ::RailsAiContext::Install::Program
 
-      # --- Read previous selection (before prompts) ---
+      # --- Every question first, the previous selection read before them ---
       previous_tools = read_previous_ai_tools
-
-      # --- Prompts (no Rails needed) ---
-      ai_tools = prompt_ai_tools
+      ai_tools = prompt_ai_tools(current: previous_tools)
       setup = prompt_setup
       tool_mode = setup.tool_mode
       context_files = setup.context_files
-
-      # --- Cleanup removed tools ---
-      cleanup_removed_tools(previous_tools, ai_tools) if previous_tools&.any?
-
-      # --- One-time v5.0.0 legacy UI-pattern files cleanup prompt ---
-      ::RailsAiContext::LegacyCleanup.prompt_legacy_files(ai_tools, root: Dir.pwd) if context_files
-
-      # --- Record the selection (YAML, plus the initializer line) ---
+      dropped = program.ask_removed_tools(program_surface, previous: previous_tools, selected: ai_tools)
+      unwired = tool_mode == :cli ? program.ask_mcp_removal(program_surface, root: Dir.pwd) : []
+      # One-time v5.0.0 legacy UI-pattern files cleanup prompt
+      ::RailsAiContext::LegacyCleanup.prompt_legacy_files(ai_tools, root: Dir.pwd, place: display_place) if context_files
+
+      # --- Boot, then write ---
+      # Nothing is written before the app's bundle is set up: the MCP configs
+      # and the cleanup read and write JSON, and done first they loaded this
+      # gem's newest json, which the app's pinned copy then loaded over. A
+      # boot that fails falls back to the static tier rather than abandoning
+      # the setup, since setup is exactly what you run on a repo you have
+      # just cloned. An MCP-only setup needs nothing from the app, so it boots
+      # nothing; nor does a run whose app bundles its own copy of the gem,
+      # which writes the context files in a child of its own.
+      bundled = bundled_copy_for_context if context_files
+      boot_rails!(command: "init", allow_static: true) if context_files && !bundled
+
+      program.remove_tools(program_surface, dropped, selected: ai_tools, previous: previous_tools, root: Dir.pwd)
+      program.remove_mcp_entries(program_surface, unwired, root: Dir.pwd)
       record_selection(ai_tools, tool_mode, context_files)
-
-      # --- Write per-tool MCP config files (MCP mode only) ---
       write_mcp_configs(ai_tools, tool_mode)
-
-      # --- Add .ai-context.json to .gitignore ---
       add_to_gitignore(context_files)
 
-      # --- Boot Rails, load config, generate context ---
-      # The config files are already on disk by now, so failing here leaves the
-      # app half set up and calls the whole thing a failure. Setup is exactly
-      # what you run on a repo you have just cloned.
-      boot_rails!(command: "init", allow_static: true)
-
-      if context_files
+      if bundled
+        generate_bundled_context(bundled)
+      elsif context_files
+        configure_answers!(ai_tools, tool_mode, context_files)
         $stderr.puts ""
         $stderr.puts "Generating AI context files..."
         print_context_result(::RailsAiContext.generate_context(format: ai_tools))
@@ -342,7 +504,9 @@ class RailsAiContextCLI < Thor
       boot_rails!(command: "facts", allow_static: true)
 
       context = ::RailsAiContext.introspect
-      puts ::RailsAiContext::FactsFormatter.render(context, inspect_hint: "rails-ai-context inspect")
+      puts ::RailsAiContext::FactsFormatter.render(
+        context, full_json: "Run `#{own_command('inspect')}` for the full introspection as JSON."
+      )
     end
 
     desc "version", "Print version"
@@ -361,12 +525,59 @@ class RailsAiContextCLI < Thor
         lambda { |prompt|
           $stderr.print "#{prompt} "
           $stdin.gets&.strip
-        }
+        },
+        display_place
       )
     end
 
-    def prompt_ai_tools
-      ::RailsAiContext::Install::Program.select_ai_tools(program_surface)
+    # The root this run works in as the person who typed the command names
+    # it, when they typed it outside that root (`init --app-path X` in X's
+    # parent, a workspace named from elsewhere): the files it reports are
+    # named from there, `X/.mcp.json`, since a bare `.mcp.json` reads as one
+    # in the directory they are in. A typed --app-path is used as typed, the
+    # way the commands it prints repeat it. Nil when they stand in the root
+    # or below.
+    #
+    # A folder of apps is the root of the run that sets it up, even when it
+    # holds one app, which the resolution names as its root: the folder's
+    # own files were named as that app's.
+    def display_place
+      result = @app_root_result or return nil
+      root = @workspace_dir || result.root || result.base
+      cwd = result.cwd
+      return nil if root.nil? || cwd.nil? || cwd.start_with?("#{root}/")
+      return inherited_place if cwd == root
+
+      typed = @app_path_override || options[:app_path]
+      result.explicit && typed ? typed.delete_suffix("/") : app_root.display(root, cwd)
+    end
+
+    # The place a folder's init gave this run, a child it started at one of
+    # its apps; nil for any other.
+    def inherited_place
+      place = ENV[PLACE_ENV]
+      place unless place.nil? || place.empty? || @workspace_dir
+    end
+
+    # How the person who typed the command names a root this run writes
+    # under: the run's own as display_place says, a workspace's app from
+    # where they stand.
+    def place_for(root)
+      root == (@workspace_dir || Dir.pwd) ? display_place : app_root.display(root, Dir.pwd)
+    end
+
+    def prompt_ai_tools(current: nil)
+      ::RailsAiContext::Install::Program.select_ai_tools(program_surface, current: current)
+    end
+
+    # The answers, over the configuration the boot loaded from the files as
+    # they stood before this run: the context files come out in the mode
+    # just chosen, not the one the app had.
+    def configure_answers!(ai_tools, tool_mode, context_files)
+      config = ::RailsAiContext.configuration
+      config.ai_tools = ai_tools
+      config.tool_mode = tool_mode
+      config.context_files = context_files
     end
 
     def prompt_setup
@@ -377,42 +588,257 @@ class RailsAiContextCLI < Thor
       ::RailsAiContext::Install::Program.select_setup(program_surface)
     end
 
-    def read_previous_ai_tools
-      ::RailsAiContext::Install::SelectionRecord.read(root: Dir.pwd)
+    def read_previous_ai_tools(root: Dir.pwd)
+      ::RailsAiContext::Install::SelectionRecord.read(root: root)
     end
 
-    def cleanup_removed_tools(previous, current)
+    def cleanup_removed_tools(previous, current, root: Dir.pwd, app_roots: [ root ])
       ::RailsAiContext::Install::Program.cleanup_removed_tools(
-        program_surface, previous: previous, selected: current, root: Dir.pwd
+        program_surface, previous: previous, selected: current, root: root, app_roots: app_roots
       )
     end
 
-    def add_to_gitignore(context_files = true)
-      ::RailsAiContext::Install::Program.mark_gitignore(program_surface, root: Dir.pwd,
-                                                       context_files: context_files)
+    # A workspace's apps each have a .gitignore, and so may the folder.
+    def add_to_gitignore(context_files = true, root: Dir.pwd)
+      surface = program_surface.dup.tap { |copy| copy.place = place_for(root) }
+      ::RailsAiContext::Install::Program.mark_gitignore(surface, root: root, context_files: context_files)
     end
 
-    def record_selection(ai_tools, tool_mode, context_files = true)
+    def record_selection(ai_tools, tool_mode, context_files = true, root: Dir.pwd)
       result = ::RailsAiContext::Install::SelectionRecord.write(
-        ai_tools, root: Dir.pwd,
+        ai_tools, root: root,
         extra_yaml: { "tool_mode" => tool_mode.to_s, "context_files" => context_files }
       )
       record = ::RailsAiContext::Install::SelectionRecord
-      conflicts = [
-        record.conflict_message(:context_files, record.write_context_files(context_files, root: Dir.pwd)),
-        record.conflict_message(:tool_mode, record.write_tool_mode(tool_mode, root: Dir.pwd))
-      ].compact
+      place = place_for(root)
+      lines = { context_files: record.write_context_files(context_files, root: root),
+                tool_mode: record.write_tool_mode(tool_mode, root: root) }
+      conflicts = lines.filter_map { |key, status| record.conflict_message(key, status, place: place) }
+      # The initializer is reported once, whichever of its three lines moved:
+      # a mode switch that rewrote it said nothing.
+      if lines.values.any? { |status| %i[updated inserted].include?(status) } && %i[unchanged absent].include?(result[:initializer])
+        result = result.merge(initializer: :updated)
+      end
 
-      (record.messages(result) + conflicts).each do |level, text|
+      (record.messages(result, place: place) + conflicts).each do |level, text|
         $stderr.puts(level == :warn ? "Warning: #{text}" : text)
       end
     end
 
-    def write_mcp_configs(ai_tools, tool_mode)
-      require_relative "../lib/rails_ai_context/mcp_config_generator"
-      ::RailsAiContext::Install::Program.write_mcp_configs(
-        program_surface, tools: ai_tools, tool_mode: tool_mode, root: Dir.pwd
-      )
+    # Only for a selection the app recorded: with none, `rails ai:context`
+    # asks first, and this asks nothing, so it writes no config either.
+    def refresh_mcp_configs
+      config = ::RailsAiContext.configuration
+      return unless config.tool_mode == :mcp && config.ai_tools&.any?
+
+      tools = ::RailsAiContext::Install::Program.own_config_tools(config.ai_tools, root: Dir.pwd)
+      write_mcp_configs(tools, :mcp) if tools.any?
+    end
+
+    # The install form is the app's own: under bundle exec the process's
+    # bundle can be another app's (`init --app-path ../b` run from a).
+    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
+        ::RailsAiContext::Install::Program.write_mcp_configs(
+          program_surface, tools: ai_tools, tool_mode: tool_mode, root: root, servers: servers, standalone: standalone
+        )
+      end
+    end
+
+    # Codex's config copies PATH and the gem variables out of this process
+    # for the server Codex starts, so they are copied as the binary was
+    # started. The app's boot sets up its bundle in this process, putting
+    # GEM_HOME at the bundle's path and the bundle's bin directory first on
+    # PATH, which no shell running the binary outside that bundle has.
+    def in_starting_env
+      now = ENV.to_h
+      ENV.replace(STARTING_ENV)
+      yield
+    ensure
+      ENV.replace(now) if now
+    end
+
+    # A folder of apps, set up as a whole. The AI tools are chosen once; each
+    # app gets its own .rails-ai-context.yml and context files, since its
+    # server reads them from its own root; and this folder's MCP configs get
+    # one server per app, since a client reads them from the folder it opened
+    # and from nowhere below it.
+    def init_workspace(dir, roots)
+      # Before anything is said: the folder's own files are named from it.
+      @workspace_dir = dir
+      require_install_files!
+      apps = ::RailsAiContext::Install::Workspace.apps(dir, roots)
+
+      $stderr.puts "#{dir} is no Rails app; it holds #{apps.size == 1 ? 'one' : apps.size} below it. Setting up:"
+      apps.each { |app| $stderr.puts "  #{app.path}/" }
+      warn_ruby_mismatch(apps)
+
+      # Before the prompts, as in an app: what each app recorded last time.
+      previous = apps.flat_map { |app| read_previous_ai_tools(root: app.root) || [] }.uniq
+
+      ai_tools = prompt_ai_tools(current: previous)
+      setup = prompt_setup
+      tool_mode = setup.tool_mode
+      context_files = setup.context_files
+
+      cleanup_removed_tools(previous, ai_tools, root: dir, app_roots: apps.map(&:root)) if previous.any?
+      if tool_mode == :cli
+        program = ::RailsAiContext::Install::Program
+        program.remove_mcp_entries(program_surface, program.ask_mcp_removal(program_surface, root: dir), root: dir)
+      end
+
+      apps.each do |app|
+        $stderr.puts ""
+        $stderr.puts "#{app.path}/:"
+        record_selection(ai_tools, tool_mode, context_files, root: app.root)
+        add_to_gitignore(context_files, root: app.root)
+      end
+
+      # JSON and TOML hold UTF-8 alone, so an app whose folder is named in
+      # another encoding cannot be named there: left out, the others' entries
+      # are still written, where its name failed the whole file.
+      configured, unnamed = apps.partition do |app|
+        [ app.server.app_path, app.server.gemfile ].compact.all? { |path| path.dup.force_encoding(Encoding::UTF_8).valid_encoding? }
+      end
+      unnamed.each do |app|
+        $stderr.puts ""
+        $stderr.puts "Warning: #{app.path}/ is left out of this folder's MCP configs: its folder name is not UTF-8, which " \
+                     "JSON and TOML require. Rename it, or run `rails-ai-context init` inside it for a config of its own."
+      end
+
+      $stderr.puts ""
+      write_mcp_configs(ai_tools, tool_mode, root: dir, servers: configured.map(&:server))
+      # 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)
+
+      if context_files
+        failed = apps.reject { |app| generate_app_context(app) }
+      else
+        failed = []
+        $stderr.puts ""
+        $stderr.puts "MCP-only setup: no context files written."
+      end
+
+      show_workspace_instructions(dir, apps, ai_tools, tool_mode, context_files, configured: configured)
+      return if failed.empty?
+
+      $stderr.puts "Error: no context files for #{failed.map { |app| "#{app.path}/" }.join(', ')} - see the output above. " \
+                   "Retry with `#{app_root.command_line([ "rails-ai-context", "--app-path", app_root.option_path(app_root.display(failed.first.root, Dir.pwd)), "context" ])}`."
+      exit 1
+    end
+
+    # A client opened here starts every app's server under the Ruby this
+    # folder resolves to, and the context files below are generated the same
+    # way; an app that declares another may not boot under it.
+    def warn_ruby_mismatch(apps)
+      running = RUBY_VERSION.split(".")
+      apps.each do |app|
+        declared = ::RailsAiContext::GemLock.for(app.root).ruby_version.to_s[/\A\d+(?:\.\d+){1,2}/] or next
+        next if declared.split(".") == running.first(declared.count(".") + 1)
+
+        $stderr.puts "Warning: #{app.path}/ declares Ruby #{declared}; this folder runs #{RUBY_VERSION}."
+        $stderr.puts "  Its server here runs under #{RUBY_VERSION} too, so it may answer from source alone, and a " \
+                     "bundle exec entry may not start. `rails-ai-context init` inside #{app.path}/ gives it a config of its own."
+      end
+    end
+
+    # One process boots one app, so each app's context files come from a
+    # child running the install that app's server runs: its bundle's copy of
+    # the gem for an in-Gemfile app, this copy for a standalone one. The
+    # child prompts for its own legacy files, so this process does not, and
+    # names them, as every file it reports, from where this one was run.
+    def generate_app_context(app)
+      $stderr.puts ""
+      $stderr.puts "Generating AI context files for #{app.path}/..."
+
+      flags = []
+      flags << "--no-boot" if options[:no_boot]
+      flags.push("--environment", options[:environment]) if options[:environment]
+      if app.standalone
+        env, command, bundled = own_binary
+        command = [ *command, "context", *flags ]
+      else
+        env = { "BUNDLE_GEMFILE" => app.gemfile }
+        command = [ "bundle", "exec", "rails-ai-context", "context", *flags ]
+      end
+      env = env.merge(PLACE_ENV => app_root.display(app.root, Dir.pwd))
+
+      # Otherwise a parent run under bundle exec hands the child the
+      # environment it was started with, the user's own Bundler settings
+      # included, not its bundle.
+      run = -> { system(env, *command, chdir: app.root) }
+      original = !bundled && defined?(::Bundler) && ::Bundler.respond_to?(:with_original_env)
+      ok = original ? ::Bundler.with_original_env(&run) : run.call
+      $stderr.puts "Error: could not run `#{command.first}` - is it installed and on PATH?" if ok.nil?
+      ok == true
+    end
+
+    # This copy of the gem, at this version, as a child runs it.
+    #
+    # Inside a bundle (a checkout's, or a folder's own Gemfile that lists the
+    # gem) the child keeps this process's environment: its dependencies may
+    # be installed nowhere else, as under a vendored BUNDLE_PATH. The bundle's
+    # Gemfile is pinned, since the child starts in another directory.
+    # Otherwise it is the installed spec, activated the way its RubyGems
+    # wrapper does it (a wrapper found on PATH may load another version), or
+    # this file with its own lib, as a checkout runs it.
+    #
+    # @return [Array(Hash, Array<String>, Boolean)] the child's environment,
+    #   its command, and whether it keeps this process's bundle
+    def own_binary
+      from_lib = [ RbConfig.ruby, "-I", File.expand_path("../lib", __dir__), EXE_PATH ]
+      if ENV["BUNDLE_BIN_PATH"] && defined?(::Bundler) && ::Bundler.respond_to?(:default_gemfile)
+        return [ { "BUNDLE_GEMFILE" => ::Bundler.default_gemfile.to_s }, from_lib, true ]
+      end
+
+      spec = PREBOOT_GEM_SPECS["rails-ai-context"]
+      return [ {}, from_lib, false ] unless spec
+
+      [ {}, [ RbConfig.ruby, "-e", 'load Gem.activate_bin_path("rails-ai-context", "rails-ai-context", ARGV.shift)',
+              "= #{spec.version}" ], false ]
+    end
+
+    def show_workspace_instructions(dir, apps, ai_tools, tool_mode, context_files, configured: apps)
+      $stderr.puts ""
+      $stderr.puts "=" * 50
+      $stderr.puts " rails-ai-context initialized for #{apps.size == 1 ? '1 app' : "#{apps.size} apps"}"
+      $stderr.puts "=" * 50
+      $stderr.puts ""
+      $stderr.puts "Your setup:"
+      where = dir == Dir.pwd ? "here" : "in #{app_root.display(dir, Dir.pwd).delete_suffix('/')}/"
+      ::RailsAiContext::Install::AiTool.all.each do |tool|
+        next unless ai_tools.include?(tool.key)
+
+        # 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
+        $stderr.puts "  #{tool.name.ljust(16)} -> #{files}"
+      end
+      if tool_mode == :mcp && configured.any?
+        $stderr.puts ""
+        $stderr.puts "MCP servers, one per app:"
+        width = configured.map { |app| app.server_name.size }.max
+        configured.each do |app|
+          how = if app.standalone then ""
+          elsif app.server.gemfile then " (bundle exec, BUNDLE_GEMFILE=#{app.server.gemfile})"
+          else " (bundle exec)"
+          end
+          $stderr.puts "  #{app.server_name.ljust(width)} -> #{app.path}/#{how}"
+        end
+      end
+      example = configured.first || apps.first
+      first = app_root.command_line([ app_root.option_path(app_root.display(example.root, Dir.pwd)) ])
+      $stderr.puts ""
+      $stderr.puts "Commands, from here:"
+      $stderr.puts "  rails-ai-context --app-path #{first} context    # Regenerate that app's context files" if context_files
+      $stderr.puts "  rails-ai-context --app-path #{first} tool NAME  # Run a tool against it"
+      $stderr.puts "  rails-ai-context --app-path #{first} doctor     # Check its AI readiness"
+      $stderr.puts ""
+      $stderr.puts "Config: .rails-ai-context.yml in each app (edit anytime, no restart needed)"
+      $stderr.puts "Opening one app on its own? Run `rails-ai-context init` inside it."
+      $stderr.puts ""
     end
 
     def show_standalone_instructions(ai_tools, tool_mode, context_files = true)
@@ -424,20 +850,27 @@ 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 : 'MCP config only'}"
+        $stderr.puts "  #{tool.name.ljust(16)} -> #{context_files ? tool.files_label(mcp: tool_mode == :mcp) : 'MCP config only'}"
       end
       unless context_files
         $stderr.puts ""
         $stderr.puts "  Left alone on purpose: CLAUDE.md, AGENTS.md, the rules directories and .ai-context.json."
       end
+      # Set up through --app-path from elsewhere, the commands name the app
+      # the same way, or they would read the folder they are run in.
+      result = @app_root_result
+      typed = @app_path_override || options[:app_path]
+      binary = "rails-ai-context"
+      binary = app_root.command_line([ "rails-ai-context", "--app-path", app_root.option_path(typed) ]) if result&.explicit && typed && result.root != result.cwd
       $stderr.puts ""
       $stderr.puts "Commands:"
-      $stderr.puts "  rails-ai-context context    # Regenerate context files" if context_files
-      $stderr.puts "  rails-ai-context tool NAME  # Run any of the #{RailsAiContext::CountPhrase.call(builtin_tool_count, "tool")}"
+      $stderr.puts "  #{binary} context    # Regenerate context files" if context_files
+      tools = served_tool_count
+      $stderr.puts "  #{binary} tool NAME  # Run any of the #{RailsAiContext::CountPhrase.call(tools, "tool")}"
       if tool_mode == :mcp
-        $stderr.puts "  rails-ai-context serve      # Start MCP server"
+        $stderr.puts "  #{binary} serve      # Start MCP server"
       end
-      $stderr.puts "  rails-ai-context doctor     # Check AI readiness"
+      $stderr.puts "  #{binary} doctor     # Check AI readiness"
       $stderr.puts ""
       if tool_mode == :mcp
         $stderr.puts "MCP auto-discovery:"
@@ -448,17 +881,27 @@ class RailsAiContextCLI < Thor
         $stderr.puts "  AI agents can run `rails-ai-context tool schema table=users` directly."
       end
       $stderr.puts ""
-      $stderr.puts "Config: .rails-ai-context.yml (edit anytime, no restart needed)"
+      config = display_place ? File.join(display_place, ".rails-ai-context.yml") : ".rails-ai-context.yml"
+      $stderr.puts "Config: #{config} (edit anytime, no restart needed)"
       $stderr.puts ""
     end
 
-    def builtin_tool_count
-      ::RailsAiContext::Server.builtin_tools.size
+    # What the server serves, skip_tools and custom_tools applied. An
+    # MCP-only setup boots nothing, so the gem is loaded here for the count,
+    # once every file is written. Without a boot the custom tools, app
+    # classes, cannot load, so each entry counts as one.
+    def served_tool_count
+      return ::RailsAiContext::Server.exposed_tools.size if defined?(::RailsAiContext::Server)
+
+      entry_boot.require_gem_without_app!
+      ::RailsAiContext::Configuration.auto_load!(Dir.pwd)
+      config = ::RailsAiContext.configuration
+      ::RailsAiContext::Server.active_tools(config).size + config.custom_tools.size
     end
 
     def print_context_result(result)
       style = ::RailsAiContext::ContextFileReport.style(:plain)
-      ::RailsAiContext::ContextFileReport.each_line(result, style) do |_bucket, text|
+      ::RailsAiContext::ContextFileReport.each_line(result, style, root: Dir.pwd, place: display_place) do |_bucket, text|
         $stderr.puts "  #{text}"
       end
     end
@@ -470,9 +913,21 @@ class RailsAiContextCLI < Thor
     # otherwise load the gem standalone and list from that. Only execution
     # (running a specific tool) genuinely needs a live app.
     def print_tool_list(no_boot: false)
-      if !no_boot && entry_boot.app_present?(Dir.pwd) && try_boot_for_list
-        puts ::RailsAiContext::CLI::ToolRunner.tool_list
-        return
+      @no_boot = true if no_boot
+      # No app is no refusal here: the app-less listing is the answer.
+      resolve_app_root!(required: false)
+      if entry_boot.app_present?(Dir.pwd, allow_source_only: true)
+        outcome = enter_app(command: "tool", allow_static: true, no_boot: no_boot, allow_source_only: true)
+        unless outcome.tier == :absent
+          # The list still comes; a boot failure's whole report, meant for a
+          # command that stops on it, would read as this command failing.
+          if outcome.kind == :boot_failed
+            $stderr.puts "[rails-ai-context] App boot failed (#{outcome.reason}); " \
+                         "tools answer from source, and custom tools may be missing from this list."
+          end
+          puts ::RailsAiContext::CLI::ToolRunner.tool_list
+          return
+        end
       end
 
       begin
@@ -480,8 +935,7 @@ class RailsAiContextCLI < Thor
         # Boot is what normally loads .rails-ai-context.yml, so without it the
         # listing took the gem's defaults and advertised tools the app has
         # configured off - which the very next call then refuses by name.
-        # The app under analysis, which --app-path may have moved.
-        ::RailsAiContext::Configuration.auto_load!(File.expand_path(@app_path_override || options[:app_path] || Dir.pwd))
+        ::RailsAiContext::Configuration.auto_load!(Dir.pwd)
         puts ::RailsAiContext::CLI::ToolRunner.tool_list
         puts ""
         puts "Run inside a Rails app to execute tools - static source analysis works even when the app can't boot (see --no-boot)."
@@ -491,26 +945,13 @@ class RailsAiContextCLI < Thor
         if entry_boot.app_present?(Dir.pwd, allow_source_only: true)
           $stderr.puts "Error: the tool list needs this gem loaded, and it failed: #{e.message}"
         else
-          $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
-          $stderr.puts "Run this command from your Rails app root directory."
           $stderr.puts "  (gem also failed to load standalone: #{e.message})" if ENV["DEBUG"]
+          refuse_no_app!
         end
         exit 1
       end
     end
 
-    # Attempts the normal boot path, catching the `exit 1` boot_rails! raises
-    # on a missing app or a failed boot (both come through as SystemExit).
-    # Returns true only when the app booted successfully; other `tool`
-    # subcommands don't have a fallback so they call boot_rails! directly and
-    # let that exit propagate.
-    def try_boot_for_list
-      boot_rails!(command: "tool")
-      true
-    rescue SystemExit
-      false
-    end
-
     # Pull a value-taking flag (--flag VALUE or --flag=VALUE) out of the
     # pass-through args that stop_on_unknown_option! leaves after the tool
     # name. Returns the value, or nil when the flag isn't present.
@@ -532,16 +973,24 @@ class RailsAiContextCLI < Thor
     # than being recognised by name.
     def boot_rails!(command:, allow_static: false, no_boot: false, allow_source_only: allow_static,
                     boot_failure_hint: nil)
-      app_path_opt = @app_path_override || options[:app_path]
+      outcome = enter_app(command: command, allow_static: allow_static, no_boot: no_boot,
+                          allow_source_only: allow_source_only)
+      outcome.messages.each { |line| $stderr.puts line }
+      return unless outcome.tier == :absent
+
+      $stderr.puts boot_failure_hint if boot_failure_hint && outcome.reason
+      $stderr.puts "  #{@app_above_hint}" if @app_above_hint && !outcome.reason
+      exit 1
+    end
+
+    # 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:)
+      # 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
+      resolve_app_root!
       environment_opt = @environment_override || options[:environment]
-      app_root = File.expand_path(app_path_opt || Dir.pwd)
-      if app_path_opt && !Dir.exist?(app_root)
-        $stderr.puts "Error: No such directory: #{app_root}"
-        exit 1
-      end
-      # Relative paths inside the app (log/, tmp/, sqlite files) assume the
-      # process cwd is the app root, so honor --app-path by moving there.
-      Dir.chdir(app_root) if app_path_opt
       # Apps read RAILS_ENV in config/boot.rb, before anything the gem can
       # rescue, so the default is only reachable if it is set here.
       # The chain is Rails' own (`Rails.env`): RAILS_ENV, then RACK_ENV, then
@@ -551,15 +1000,195 @@ class RailsAiContextCLI < Thor
 
       # A command that can serve the static tier reads a source-only tree
       # instead of refusing it.
-      outcome = 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)
-      outcome.messages.each { |line| $stderr.puts line }
-      return unless outcome.tier == :absent
+      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)
+    end
 
-      $stderr.puts boot_failure_hint if boot_failure_hint && outcome.reason
+    # Which app this command reads, decided once and before anything reads
+    # Dir.pwd, then made the process cwd: relative paths inside the app (log/,
+    # tmp/, sqlite files, every install helper's root) assume it. Without
+    # this, init wrote half its files where it was run and half into
+    # --app-path, and `tool --list --app-path X` never booted X.
+    #
+    # `required: false` leaves the current directory in place when there is
+    # no single app, for the one command that answers without one.
+    # `workspace: true` is init's: a folder of apps is set up as a whole, so
+    # that answer comes back with the process left where it stands.
+    # `hand_off: false` is init's too: it asks its questions in this copy.
+    def resolve_app_root!(required: true, workspace: false, hand_off: true)
+      return @app_root_result if defined?(@app_root_result)
+
+      cwd = Dir.pwd
+      result = @app_root_result = app_root.resolve(cwd: cwd, app_path: @app_path_override || options[:app_path])
+      return result if workspace && result.workspace?
+
+      if result.explicit
+        unless Dir.exist?(result.root)
+          $stderr.puts "Error: No such directory: #{result.root}"
+          hint = app_root.relative_path_hint(@app_path_override || options[:app_path], cwd)
+          $stderr.puts "  #{hint}" if hint
+          exit 1
+        end
+        if result.below.any? && required
+          app_root.several_apps(result, cwd, ARGV).each { |line| $stderr.puts line }
+          exit 1
+        end
+        @app_above_hint = app_root.app_above_hint(result.root, cwd) unless entry_boot.app_present?(result.root, allow_source_only: true)
+      elsif result.root.nil?
+        return result unless required && result.below.any?
+
+        app_root.several_apps(result, cwd, ARGV).each { |line| $stderr.puts line }
+        exit 1
+      end
+
+      # Bundler reads a relative BUNDLE_GEMFILE (a workspace entry names an
+      # app's Gemfile that way) against the cwd. bundle exec hands its child an
+      # absolute one, a direct run does not, so it is pinned before the cwd
+      # moves, for this process's boot and every child it starts.
+      gemfile = ENV["BUNDLE_GEMFILE"]
+      ENV["BUNDLE_GEMFILE"] = File.expand_path(gemfile, cwd) if gemfile && !gemfile.empty?
+      Dir.chdir(result.root) unless result.root == cwd
+      # stderr only: stdout is the protocol channel for serve.
+      $stderr.puts app_root.notice(result, cwd) if result.walked
+      # Which bundle an app boots against matters only where there is one.
+      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
+      result
+    end
+
+    # The app's bundle carries its own copy of the gem: the command runs as
+    # `bundle exec rails-ai-context` would run it, from where it was typed,
+    # so one copy answers - the one the app's MCP configs start. When bundle
+    # cannot be started this copy carries on.
+    #
+    # Only a run that boots the app hands off, since booting runs the app's
+    # bundle anyway. One that promises to run nothing of the app's -
+    # --no-boot, an MCP-only init - keeps to this copy: bundle exec would
+    # evaluate the app's Gemfile and start whatever copy of the gem the app
+    # names, on a repo just cloned code nobody has read. Nor does a bundle
+    # not installed yet, where bundle exec would only fail and this copy
+    # answers from source.
+    #
+    # A root found by walking from where the command was typed is where the
+    # command runs from: this copy reads every relative argument from there,
+    # and a released copy does not walk at all.
+    def hand_off_to_bundle!(root, cwd)
+      return if options[:no_boot] || @no_boot || options[:mcp_only]
+
+      handoff = app_root.bundled_handoff(root) or return
+      return unless app_root.bundle_ready?(handoff.env, root)
+
+      bundle = Gem.bin_path("bundler", "bundle")
+      $stderr.puts "[rails-ai-context] This app's bundle has rails-ai-context #{handoff.version}; " \
+                   "running that copy, as bundle exec does."
+      exec(handoff.env.merge(TYPED_IN_ENV => cwd), RbConfig.ruby, bundle, "exec", "rails-ai-context", *ORIGINAL_ARGV,
+           chdir: @app_root_result&.walked ? root : cwd)
+    rescue Gem::Exception, SystemCallError
+      nil
+    end
+
+    # init asks its questions in this copy and hands only the context files
+    # to the app's bundled copy, once they are asked for: an MCP-only setup
+    # then runs nothing of the app's, flag or answer.
+    def bundled_copy_for_context
+      return nil if options[:no_boot]
+
+      handoff = app_root.bundled_handoff(Dir.pwd) or return nil
+      app_root.bundle_ready?(handoff.env, Dir.pwd) ? handoff : nil
+    end
+
+    def generate_bundled_context(handoff)
+      $stderr.puts ""
+      $stderr.puts "This app's bundle has rails-ai-context #{handoff.version}; generating the context files with that copy, " \
+                   "as bundle exec does..."
+      bundle = Gem.bin_path("bundler", "bundle")
+      flags = options[:environment] ? [ "--environment", options[:environment] ] : []
+      # This run has just written the MCP configs, Codex's from the
+      # environment the binary was started in; a `context` that refreshed
+      # them would write that one again from the bundle's.
+      flags << "--no-mcp-refresh" if refresh_flag_known?(handoff.version)
+      # The child names its files as display_place does here: X/CLAUDE.md for `init --app-path X`.
+      env = display_place ? handoff.env.merge(PLACE_ENV => display_place) : handoff.env
+      ok = system(env, RbConfig.ruby, bundle, "exec", "rails-ai-context", "context", *flags, chdir: Dir.pwd)
+      return if ok
+
+      $stderr.puts "Error: the bundled copy could not write the context files - see the output above. " \
+                   "Retry with `#{own_command('context')}`."
+      exit 1
+    end
+
+    def refresh_flag_known?(version)
+      Gem::Version.new(version.to_s) >= Gem::Version.new(MCP_REFRESH_FLAG_SINCE)
+    rescue ArgumentError
+      false
+    end
+
+    # Another command for this app as this one was typed: from where it was
+    # typed, with the --app-path it named, under bundle exec when it ran so.
+    # A run the binary handed to the app's bundle was typed without it, and
+    # typed again it is handed over again. Read from the environment the
+    # binary was started in: the app's boot runs bundler/setup, which sets
+    # BUNDLE_BIN_PATH in a standalone run too.
+    def own_command(*args)
+      result = @app_root_result
+      typed = @app_path_override || options[:app_path]
+      typed_bundled = STARTING_ENV["BUNDLE_BIN_PATH"] && !STARTING_ENV[app_root::HANDOFF_ENV]
+      words = typed_bundled ? %w[bundle exec rails-ai-context] : %w[rails-ai-context]
+      words += [ "--app-path", app_root.option_path(typed) ] if result&.explicit && typed && result.root != result.cwd
+      app_root.command_line([ *words, *args ])
+    end
+
+    def doctor_command
+      own_command("doctor")
+    end
+
+    # The root as an error names it: a typed --app-path as typed, the way the
+    # hint under it does, where Dir.pwd spells it through any symlink
+    # (/private/var on macOS).
+    def shown_root
+      result = @app_root_result
+      result&.explicit ? result.root : Dir.pwd
+    end
+
+    def refuse_no_app!
+      $stderr.puts "Error: No Rails app found in #{shown_root}"
+      $stderr.puts entry_boot::NO_APP_HINT
+      $stderr.puts "  #{@app_above_hint}" if @app_above_hint
       exit 1
     end
 
+    # Stdlib only, so it is safe to load before the app boots.
+    def app_root
+      entry_boot
+      require_relative "../lib/rails_ai_context/cli/app_root"
+      ::RailsAiContext::CLI::AppRoot
+    end
+
+    # A gem this binary uses when it is there - `listen`, for watch and for
+    # serve's live reload - is no dependency of it, so the binstub never
+    # activated it, and the app's bundle hides every gem the app does not
+    # lock: a standalone install could not see a listen installed beside it.
+    # It is reached the way this gem's own dependencies are, found among the
+    # installed gems before the boot and put back behind the app's bundle
+    # after it, so a copy the app locks still wins. Under bundle exec the
+    # bundle decides.
+    def reach_installed_gem(name)
+      return if ENV["BUNDLE_BIN_PATH"]
+
+      found = [ Gem::Specification.find_by_name(name) ]
+      found.each do |spec|
+        spec.runtime_dependencies.each { |dep| found << dep.to_spec unless found.any? { |had| had.name == dep.name } }
+      end
+      # A default gem loads from Ruby's own directories already, and the
+      # binstub's stash leaves them out the same way.
+      found.reject!(&:default_gem?)
+      found.each { |spec| spec.full_require_paths.each { |path| $LOAD_PATH << path unless $LOAD_PATH.include?(path) } }
+      entry_boot.preboot_gem_specs = found.to_h { |spec| [ spec.name, spec ] }.merge(entry_boot.preboot_gem_specs)
+    rescue Gem::LoadError
+      nil
+    end
+
     # Stdlib only, so it is safe to load before the app boots.
     def entry_boot
       @entry_boot ||= begin
@@ -583,7 +1212,7 @@ class RailsAiContextCLI < Thor
     def require_install_files!
       %w[
         gem_lock install/ai_tool install/selection_record install/cleanup
-        install/surface install/program mcp_config_generator legacy_cleanup
+        install/surface install/program mcp_config_generator install/workspace legacy_cleanup
       ].each { |file| require_relative "../lib/rails_ai_context/#{file}" }
 
       # Both are defined in the entry file, which is the thing that must not