rails-ai-context 5.32.2 → 5.33.0

data/CONTEXT.md

@@ -30,16 +30,26 @@ Two senses, one per module, and neither is bare "path" in a name.
 
 ## Safe path
 
-A caller-supplied path resolved once, through `SafePath`, before anything reads it. Its refusal order is the contract, not an implementation detail: traversal, sensitive name, realpath, containment, sensitive realpath, file, size. A caller that reorders those checks, or repeats one of them itself, gets a different answer on a symlink or a dotfile than every other tool does, which is the divergence the module exists to end. `BaseTool.safe_glob` is the globbed-path form: realpath, containment and the sensitive-realpath check on each path a pattern yields, with the size cap left to the read that follows.
+A caller-supplied path resolved once, through `SafePath`, before anything reads it. Its refusal order is the contract, not an implementation detail: traversal, sensitive name, realpath, containment (the directory asked about, or a **linked-in** directory on the way to it), sensitive realpath, file, size. A caller that reorders those checks, or repeats one of them itself, gets a different answer on a symlink or a dotfile than every other tool does, which is the divergence the module exists to end. `BaseTool.safe_glob` is the globbed-path form: realpath, containment and the sensitive-realpath check on each path a pattern yields, with the size cap left to the read that follows.
 
 Not the same as a path that merely looks harmless, and not a caller's own containment check - "the tool guards this parameter" means it hands the parameter to `SafePath` and renders whatever refusal comes back.
 
 ## Carried path
 
-A path the payload already holds because the gem's own walk found it - a controller's or a model's `file:`. A controller's is re-read with `SafeFile.read(File.join(root, relative))`, which checks that it is a regular file under the size cap and nothing else; a model's goes through `PortablePath.resolve` first, since it can be a `gem:` path. The reason is the walk: `SourceScan` deliberately keeps the spelling the app uses when the realpath falls outside the root, so a pack or an in-repo engine symlinked out of the root is spelled inside it, and `SafePath`'s realpath containment would refuse the very file the payload just named - the source comes back nil and a section silently empties.
+A path the payload already holds because the gem's own walk found it - a controller's or a model's `file:`. A controller's is re-read with `SafeFile.read(File.join(root, relative))`, which checks that it is a regular file under the size cap and nothing else; a model's goes through `PortablePath.resolve` first, since it can be a `gem:` path. The reason is the walk: it already decided the file is the app's (see **Linked out**), keeping the spelling the app uses when the realpath falls outside the root, and a model's file can be a gem's, which `SafePath` refuses as outside the root - the source would come back nil and a section silently empty.
 
 Not an exception to the **safe path** rule, the other side of it: a caller-supplied path is untrusted and goes through `SafePath`; a carried path was produced by this gem and only needs the cap.
 
+## Linked out
+
+A file the app spells inside its root, or inside the engine its test/dummy runs in, that a symlink takes somewhere neither of those holds nor a **linked-in** directory does: the file is a link, or sits under one. `PathResolver.linked_out?` answers it. A walk that reads what it finds drops such a file before listing it (`FileWalk`, `SourceScan`, `ViewFile.glob` and the introspectors' own globs), and so does a read of the file Ruby says a loaded class came from, so a **carried path** is never one. A link that resolves nowhere is not linked out, since nothing can be read through it, and a walk drops it as no file.
+
+Not the **safe path** check, which refuses a path a caller supplied: this one decides which of the files the gem found itself are the app's. Booted, a class Rails loaded through such a link is still described by reflection; only its file goes unread.
+
+## Linked-in directory
+
+A directory link inside the app that leads somewhere in the git work tree holding the app (`SafePath.link_bound`): a monorepo package linked into `packs/` or `app/javascript/controllers`. Its files are the app's, named the way the app spells them (`packs/billing/app/models/invoice.rb`), because Zeitwerk, the view resolver and the bundlers follow it; a file under it that links further out, past the app and the directory, is **linked out**. Outside any repository the bound is the app root, so nothing outside it is linked in. `SafePath.linked_in` finds the directory on a path's spelling, and `PathResolver.enter_link?` decides whether a walk enters one: never one back up over the directory being walked. The walks that stand for Rails' own globs - initializers, locales, migrations, seeds, rake tasks, test files - enter no linked directory, as those globs do not.
+
 ## Source scan
 
 The one walk over a kind of app source, across every directory `PathResolver` resolves for it: conventional layout, packs, in-repo engines. `SourceScan.paths` stats only, `each` reads the source on top of it, and `classes` names each file by its declared constant. An introspector that globs `app/<kind>` itself is the mistake this entry exists to name: it misses every pack and engine, and it names files by their path rather than by what they declare.
@@ -154,3 +164,17 @@ Two senses on different axes. Qualify it; the bare word does not say which.
 **Standalone install** - how the gem got installed: `gem install rails-ai-context`, driven through its own binary, never in the host app's Gemfile, so the `rails ai:*` rake tasks do not exist. `InstallMode.standalone?` is the decider, and the `standalone:` flag on `McpConfigGenerator` means this - it picks whether the written MCP command is the bare binary or a bundled invocation. `docs/STANDALONE.md` documents this sense only.
 
 **Standalone server** - how MCP is served: the entry point that is its own process, `rails ai:serve_http` starting `Server` with `transport: :http`, serving MCP and nothing else. The middleware and the engine controller answer the same requests from inside the app's web server; the standalone server does not need one running. It says nothing about the install - an in-Gemfile app starts it from a rake task. ADR-0003 and `McpEdge` use this sense.
+
+## App root
+
+The directory a command reads as the app, decided once by `CLI::AppRoot` before anything reads the working directory, and then made the process's working directory. `--app-path` names it outright and is never walked. Otherwise it is the nearest directory at or above the working directory that passes the strict test, as `bin/rails` and Bundler find theirs: `config/application.rb`, `config/environment.rb`, or a `bin/rails` that boots an app or an engine. A working directory that passes only the loose test (source alone, any `app/**/*.rb`: a packwerk pack, an engine kept as code) is the root itself when no app holds it. The walk up never stops at a pack, `$HOME`, `node_modules`, `vendor/bundle` or a gem install.
+
+Not the same as `Rails.root`, which only a booted app has, and not the **workspace** below, which is no app at all.
+
+## Workspace
+
+A folder an editor or agent is opened at that is no app and has no app above it, but holds apps one or two levels down (`config/application.rb` only, so an engine or a pack is not one). `init` sets one 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 the workspace's MCP configs get one server per app, since a client reads them from the folder it opened and from nowhere below. Every other command needs a single app, so it uses the only one or refuses with one `--app-path` command per app.
+
+**Server name** - the key an entry has in a config. An app's own config calls its server `rails-ai-context`; a workspace's calls each one `rails-ai-context-<app folder>` (`Install::Workspace.server_names`), with the whole path where two apps share a folder name, and a hash where the name would be too long for the tools. `McpConfigGenerator::OWN_SERVER_NAME` matches every form, and `own_entry?` claims the ones that run the gem's server, so removal never leaves one behind and never takes an entry somebody else named that way. Not the **announced name**, which the running server gives the tool (`config.server_name`, or, in place of its default, `RAILS_AI_CONTEXT_SERVER_NAME` for one process): a workspace server announces its app first, because VS Code names tools after that and keeps 13 characters of it.
+
+**Workspace entry** - the server entry itself: `--app-path` relative to the workspace, because the file may be committed; spelled from the tool's own name for its config's folder (`${workspaceFolder}`) where it has one, bare where the tool starts servers in the folder it was launched in. For an in-Gemfile app it adds `BUNDLE_GEMFILE` naming the Gemfile the app's bundle reads (its own, else the shared one its `config/boot.rb` names, else the one `bundle exec` run inside the app would find), because `bundle exec` started in the workspace would never find it. ADR-0005 records the per-tool facts this rests on.

data/README.md

@@ -30,7 +30,7 @@
 **rails-ai-context** is a Ruby gem that turns your Rails app into the source of truth for AI coding assistants. Instead of guessing your schema, associations, routes and conventions from training data, the assistant asks your app: 45 read-only tools served over [MCP](https://modelcontextprotocol.io) or run from the CLI, plus generated context files for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI.
 
 > [!TIP]
-> Nothing to add to your Gemfile if you don't want to. `gem install rails-ai-context`, then `rails-ai-context init` inside any Rails app. It also works on an app that won't boot: pass `--no-boot` and the tools answer from the source files. The two that need a live app, `query` and `runtime_info`, say so.
+> Nothing to add to your Gemfile if you don't want to. `gem install rails-ai-context`, then `rails-ai-context init` inside any Rails app, or in a folder of apps to set them all up with one MCP server each. It also works on an app that won't boot: pass `--no-boot` and the tools answer from the source files. The two that need a live app, `query` and `runtime_info`, say so.
 
 ## Why
 
@@ -67,7 +67,7 @@ You catch it, fix it, re-prompt, and something next to it breaks. The tokens are
 - **Three ways in**: MCP over stdio, MCP mounted inside your Rails app over HTTP, or plain CLI in any terminal.
 - **Generated context files** for Claude Code, Cursor, GitHub Copilot, OpenCode and Codex CLI, with the MCP config each tool auto-detects on project open.
 - **Live resources**: `rails://` and `rails-ai-context://` URIs that introspect fresh on every read.
-- **Anti-hallucination rules** shipped in every generated context file, on by default.
+- **Anti-hallucination rules** shipped in each AI tool's main context file, in compact and full mode, on by default.
 - **Static tier**: when the app can't boot, tools answer from `config/routes.rb`, `db/schema.rb`, migrations and source files, and say so.
 - **Works with real app shapes**: packwerk packs, in-repo engines, multi-database schema dumps, Mongoid, API-only apps.
 - **Custom tools**: register your own `MCP::Tool` classes next to the built-in ones and test them with the bundled `TestHelper`.
@@ -78,6 +78,7 @@ You catch it, fix it, re-prompt, and something next to it breaks. The tokens are
 
 - Ruby 3.1 or newer
 - Rails 7.0 or newer
+- Linux, macOS or Windows (see [Operating systems](docs/COMPATIBILITY.md#operating-systems))
 - Optional: `brakeman` for `security_scan`, `listen` for `watch`, `ripgrep` for faster `search_code`
 
 ### Install in the Gemfile
@@ -87,7 +88,7 @@ bundle add rails-ai-context --group development
 rails generate rails_ai_context:install
 ```
 
-The generator asks which AI tools you use and what to write, then creates the context files, the MCP config for each tool, `config/initializers/rails_ai_context.rb` and `.rails-ai-context.yml`. In a git repo with no pre-commit hook it also offers to install one. An empty answer to the tools question selects all five, and `--defaults` takes the default for each question. Re-running it is safe; it keeps what you have and adds what is missing. Every step is in [What the install generator does](docs/GUIDE.md#what-the-install-generator-does).
+The generator asks which AI tools you use and what to write, then creates the context files, the MCP config for each tool, `config/initializers/rails_ai_context.rb` and `.rails-ai-context.yml`. In a git repo with no pre-commit hook it also offers to install one. An empty answer to the tools question selects all five, and `--defaults` takes the default for each question. Re-running it is safe; it keeps what you have and adds what is missing, and in a context file you wrote yourself, such as `CLAUDE.md` or `app/models/AGENTS.md`, it rewrites only the section 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).
 
 Keeping your own `CLAUDE.md` and `AGENTS.md`? `rails generate rails_ai_context:install --mcp-only` writes the MCP config and leaves every context file alone.
 
@@ -129,7 +130,7 @@ bundle exec rails-ai-context serve   # in-Gemfile
 rails-ai-context serve               # standalone
 ```
 
-`rails ai:serve` starts the same server from rake.
+On Windows each config starts it through `cmd /c`, since a gem's executables there are batch files. `rails ai:serve` starts the same server from rake.
 
 ### MCP over HTTP
 
@@ -137,13 +138,16 @@ Mount the server inside your app. It inherits your routing, auth and middleware,
 
 ```ruby
 # config/routes.rb
-mount RailsAiContext::Engine, at: "/mcp"
+mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
 ```
 
+The `if` keeps the routes file loading wherever the gem is not: in production, where Bundler skips the `:development` group, and after the gem is removed. An unguarded mount raises `uninitialized constant RailsAiContext::Engine` there, and the app does not boot.
+
+Outside development and test (production, staging) the endpoint refuses every request with a 403 unless you set `config.allow_http_in_production = true`, since it has no authentication of its own; see [Security](docs/SECURITY.md#mcp-http-transport).
+
 Point the client at `http://localhost:3000/mcp`. There is also a standalone HTTP process: `rails-ai-context serve --transport http --port 6029`.
 
-> [!WARNING]
-> Each connected client that opens the SSE channel holds one server thread for the life of the connection. Fine for development; raise Puma's thread count or use the standalone HTTP process if several clients share the app.
+The mounted engine opens no server-push channel (it answers that `GET` with 405, as the MCP spec allows), so a connected client holds a server thread only while one of its requests runs.
 
 ### CLI
 
@@ -169,7 +173,7 @@ Tool names resolve loosely: `schema`, `get_schema` and `rails_get_schema` all wo
 | `rails ai:watch` | `rails-ai-context watch` | Regenerate on file change |
 | `rails 'ai:preset[NAME]'` | `rails-ai-context preset NAME` | Run a multi-tool preset (`architecture`, `debugging`, `migration`) |
 
-Flags shared by the app-reading commands: `--app-path PATH` to target another directory, `--environment ENV` to set `RAILS_ENV`, and `--no-boot` to skip the boot attempt and answer from source. Full list in the [CLI reference](docs/CLI.md).
+The binary finds the app the way `bin/rails` does, so it runs from any subdirectory, and from a folder holding one app. Flags shared by the app-reading commands: `--app-path PATH` to target another directory, `--environment ENV` to set `RAILS_ENV`, and `--no-boot` to skip the boot attempt and answer from source. Full list in the [CLI reference](docs/CLI.md).
 
 ## Tools
 
@@ -213,7 +217,7 @@ Plus 9 static resources: `rails://schema`, `routes`, `conventions`, `gems`, `con
 
 ## Anti-hallucination rules
 
-Every generated context file (`CLAUDE.md`, `.cursor/rules/`, `.github/instructions/`, `AGENTS.md`) ships with six rules the assistant reads before writing code:
+Each AI tool's main context file (`CLAUDE.md`, `AGENTS.md` for OpenCode and Codex, `.cursorrules` and `.cursor/rules/rails-mcp-tools.mdc` for Cursor, `.github/copilot-instructions.md`) ships with six rules the assistant reads before writing code, in compact and full mode alike. With `generate_root_files` off, `.claude/rules/rails-mcp-tools.md` and `.github/instructions/rails-mcp-tools.instructions.md` carry them instead:
 
 1. Verify before you write. Never reference a column, association, route, helper, method, class, partial or gem that a tool call in this turn did not confirm.
 2. Mark every assumption with `[ASSUMPTION]`. "I'd need to check X first" is a good answer.

data/Rakefile

@@ -14,6 +14,7 @@ RSpec::Core::RakeTask.new(:spec)
 #   bundle exec rake e2e:in_gemfile   # just Path A
 #   bundle exec rake e2e:standalone   # just Path B
 #   bundle exec rake e2e:zero_config  # just Path C
+#   bundle exec rake e2e:workspace    # just Path D: init in a folder of apps
 #   bundle exec rake e2e:mcp          # stdio + HTTP protocol specs
 namespace :e2e do
   RSpec::Core::RakeTask.new(:in_gemfile) do |t|
@@ -31,6 +32,11 @@ namespace :e2e do
     ENV["E2E"] = "1"
   end
 
+  RSpec::Core::RakeTask.new(:workspace) do |t|
+    t.pattern = "spec/e2e/workspace_install_spec.rb"
+    ENV["E2E"] = "1"
+  end
+
   RSpec::Core::RakeTask.new(:mcp) do |t|
     t.pattern = "spec/e2e/mcp_{stdio,http}_protocol_spec.rb"
     ENV["E2E"] = "1"

data/app/controllers/rails_ai_context/mcp_controller.rb

@@ -1,49 +1,93 @@
 # frozen_string_literal: true
 
-require "delegate"
-
 module RailsAiContext
   # Rails controller for serving MCP over Streamable HTTP.
   # Alternative to the Rack middleware - integrates with Rails routing,
   # authentication, and middleware stack.
   #
-  # Mount in routes: mount RailsAiContext::Engine, at: "/mcp"
+  # Mount in routes, guarded so the routes file still loads where the gem is
+  # not (production, with the gem in the development group, or after it is
+  # removed): mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
+  #
+  # Every request is answered whole, on the thread Rails runs it on. The SDK
+  # answers a request inside a session with a body that writes an SSE stream;
+  # this controller runs that body into a buffer and sends the text once the
+  # call is done, as a plain string, which every middleware in the app's
+  # stack passes through (Rails 7's Rack::ETag 500'd on the callable itself).
+  #
+  # It used to stream through ActionController::Live, which runs the action
+  # on a thread of its own, and that deadlocked a development server. The
+  # request's thread holds a share of the code-loading interlock and waits
+  # for the Live thread to answer; the Live thread needs a share of its own
+  # to start; once another request has queued a code reload after an edit,
+  # no new share is granted until the reload runs, and the reload waits for
+  # the request's thread to let go of its share. With several clients
+  # calling while an agent edited, every request hung within seconds, and
+  # SIGTERM waited on them. Live's thread also kept the database connection
+  # a call used, and from Rails 8.0 that thread lives on in a pool, so each
+  # call after an edit waited ten seconds for the reload to give up on it.
+  # On the request's own thread the call needs no second share, the reload
+  # waits for it to finish, and Rails returns its connection when the
+  # request completes.
+  #
+  # The cost: what a tool sends during a call reaches the client with the
+  # answer, not as it is sent. A custom tool's progress or log notifications
+  # arrive together at the end, and a request a tool makes of the client
+  # mid-call (sampling, elicitation, roots) fails at once, since no answer
+  # could reach it before the call is over (McpEdge::AnsweredWhole). This
+  # gem's own tools send neither, and the engine opens no stream of its own
+  # (refuse_server_push).
   class McpController < ActionController::API
-    # Live: the transport answers SSE-mode requests with a Rack 3 streaming
-    # body (a Proc that writes to a stream). Handing that Proc to a plain
-    # controller works only where the response body passes through untouched;
-    # Rails 7.x's response buffer feeds it through Rack::ETag, which 500s on
-    # the callable. Live's stream is exactly the interface the Proc expects
-    # (write/close) and keeps every middleware away from the body on all
-    # supported Rails versions.
-    include ActionController::Live
-
-    # The MCP SDK's SSE writer calls stream.flush after every event, but
-    # Live's buffer writes straight through to the client and defines no
-    # flush - the NoMethodError would 500 the request after the payload was
-    # already delivered and tear down long-lived GET streams.
-    class FlushableStream < SimpleDelegator
-      def flush; end
+    # What the SDK's SSE writer needs of a stream - write, flush, close,
+    # closed? - held in memory until the call is done. A write after close
+    # raises IOError, as a closed socket's does, so the SDK drops a stream
+    # the answer has already left on.
+    class BufferedStream
+      def initialize
+        @chunks = []
+        @closed = false
+      end
+
+      def write(chunk)
+        raise IOError, "closed stream" if @closed
+
+        text = chunk.to_s
+        @chunks << text
+        text.bytesize
+      end
+
+      def flush
+        self
+      end
+
+      def close
+        @closed = true
+        nil
+      end
+
+      def closed?
+        @closed
+      end
+
+      def string
+        @chunks.join
+      end
     end
 
     def handle
+      if (refused = McpEdge.production_refusal || McpEdge.host_refusal(request.env))
+        return answer_rack(refused)
+      end
+      return refuse_server_push if request.get?
+
       Tools::BaseTool.with_session_for(request.env) do
         serve_transport
       end
     rescue => e
-      # Once the response is committed the status and headers are already on
-      # the wire, so a JSON-RPC frame written here cannot reach the client.
-      # Worse, assigning a body swaps the stream out from under the thread
-      # still draining the old one, turning a truncated SSE stream into a
-      # garbled one. The streaming branch's ensure always closes the stream,
-      # and closing commits, so every streaming failure lands here committed.
-      # Hand those to Live, which logs them with a backtrace and tears the
-      # connection down.
-      raise if response.committed?
-
       # A transport failure must still answer in JSON-RPC shape. Without this
       # the exception escapes into a generic Rails 500 (HTML), breaking the
-      # client's JSON-RPC loop.
+      # client's JSON-RPC loop. Nothing has been sent yet, whatever the body
+      # had written, so the frame replaces it whole.
       RailsAiContext.log_warn "[rails-ai-context] MCP request failed: #{e.class}: #{e.message}"
       self.status = 500
       response.headers["Content-Type"] = "application/json"
@@ -52,47 +96,39 @@ module RailsAiContext
 
     private
 
+    # The body is read before the status and headers are set, so a body
+    # that fails leaves nothing of the SDK's answer on the error frame.
     def serve_transport
-      status_code, rack_headers, body = self.class.mcp_transport.handle_request(request)
+      status_code, rack_headers, body = McpEdge.engine_transport.handle_request(request)
+      text = read_body(body)
       self.status = status_code
       apply_transport_headers(rack_headers)
+      self.response_body = text
+    end
+
+    # The SDK's answer as one string: a plain body (initialize, an error, a
+    # notification's 202) joined, and a streaming one - the SSE stream a
+    # request inside a session gets - run here into a buffer. The tool runs
+    # inside it, on this thread, inside this request's session scope. The
+    # buffer is closed once the body returns, as the answer leaves with it.
+    def read_body(body)
       if body.respond_to?(:each)
-        # Plain enumerable body (initialize, errors, JSON mode): join to a
-        # string so Content-Length/ETag semantics stay conventional.
         chunks = []
         body.each { |chunk| chunks << chunk }
-        body.close if body.respond_to?(:close)
-        self.response_body = chunks.join
+        chunks.join
       elsif body.respond_to?(:call)
-        stream = response.stream
-        stream = FlushableStream.new(stream) unless stream.respond_to?(:flush)
+        stream = BufferedStream.new
         begin
           body.call(stream)
-          # A GET opens the server-push channel: the transport registers the
-          # stream and returns, expecting it to outlive this call. Live closes
-          # the response when the action returns, so hold the thread until the
-          # transport's keepalive (or the client) closes the stream. Live also
-          # sends headers only on the first write - the transport writes
-          # nothing until its first keepalive ping, so commit with an SSE
-          # comment up front or clients sit waiting on headers.
-          if request.get?
-            begin
-              stream.write(": connected\n\n")
-            rescue IOError
-              nil
-            end
-            wait_for_stream_close
-          end
         ensure
-          begin
-            response.stream.close
-          rescue StandardError
-            nil
-          end
+          stream.close
         end
+        stream.string
       else
-        self.response_body = body
+        body
       end
+    ensure
+      body.close if body.respond_to?(:close)
     end
 
     # Rack 3 transports name their headers in lowercase, and the MCP SDK
@@ -111,43 +147,37 @@ module RailsAiContext
       end
     end
 
-    def wait_for_stream_close
-      sleep 0.5 until stream_finished?
-    rescue IOError
-      nil
+    # A Rack triple answered whole, for the refusals McpEdge builds.
+    def answer_rack((status, headers, body))
+      self.status = status
+      apply_transport_headers(headers)
+      self.response_body = body.join
     end
 
-    # A client hangup aborts the buffer instead of closing it, so `closed?`
-    # alone leaves this thread parked until the transport's next keepalive
-    # write notices the hangup - up to the keepalive interval per dropped
-    # client. Live's buffer reports the hangup through `connected?`; the plain
-    # buffer used off the streaming path does not define it, so ask first.
-    def stream_finished?
-      stream = response.stream
-      return true if stream.closed?
-
-      stream.respond_to?(:connected?) && !stream.connected?
+    # The engine has nothing to push: live reload, the one thing that sends
+    # a server-initiated message, runs only in the standalone server. Held
+    # open, the GET channel carried keepalive pings and nothing else, cost a
+    # server thread per connected client, and a client that stayed connected
+    # kept `rails server` from stopping. A server without the channel answers
+    # the GET with 405, which clients read as "POST only".
+    def refuse_server_push
+      self.status = 405
+      response.headers["Allow"] = "POST, DELETE"
+      response.headers["Content-Type"] = "application/json"
+      self.response_body = McpEdge.error_frame(McpEdge::INVALID_REQUEST,
+        "Method not allowed: this endpoint opens no server-push stream. Send requests with POST.")
     end
 
     class << self
-      # Class-level memoization - transport persists across requests.
-      # Thread-safe: MCP::Server and transport are stateless for reads.
+      # The transport outlives this class, which the app's reloader replaces
+      # on every edit in development (McpEdge.engine_transport).
       def mcp_transport
-        @transport_mutex.synchronize { @mcp_transport ||= McpEdge.build_transport }
+        McpEdge.engine_transport
       end
 
       def reset_transport!
-        @transport_mutex.synchronize { @mcp_transport = nil }
-      end
-
-      private
-
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@transport_mutex, Mutex.new)
+        McpEdge.reset_engine_transport!
       end
     end
-
-    @transport_mutex = Mutex.new
   end
 end

data/docs/ARCHITECTURE.md

@@ -115,7 +115,7 @@ Five modules answer questions every introspector used to answer for itself:
 
 - **PathResolver** - where a kind of app code lives: `app/<kind>`, packs, and the in-repo code roots read from the tree (a directory holding its own `app/` plus a gemspec, `plugin.rb` or `lib/**/engine.rb`), memoized per root
 - **SourceScan** - one walk over a kind of app source, across every directory `PathResolver` resolves: `paths` stats, `each` reads, `classes` names by the declared constant
-- **EagerLoad** - loads a directory's constants for a booted-tier walk, one file at a time, so an unloadable file costs only itself
+- **EagerLoad** - loads a directory's constants for a booted-tier walk, one file at a time, so an unloadable file costs only itself. A file Prism finds a syntax error in is never required, nor is one whose class body names its constant (a subclass, an includer); each is left out with the reason, which a model's or a controller's answer gives in its place. A tool that looks an app class up by name goes through `EagerLoad.constant`, which loads it as `constantize` would and never requires such a file
 - **GemLock** - which gems the app resolved and at what version, read once per lockfile and matched by exact name across GEM, GIT and PATH
 - **PackageJson** - which npm packages the app depends on, read once per `package.json`: present means named in `dependencies` or `devDependencies`, so an `overrides` pin is not a dependency, and `@tailwindcss/vite` counts as tailwindcss
 
@@ -170,7 +170,7 @@ rails-ai-context://views/posts/show.html.erb → template content
 rails-ai-context://routes/posts        → filtered routes
 ```
 
-Every resolve call introspects fresh - zero stale data.
+Every resolve call introspects afresh, once the server has reloaded the app's code for any edit (see Caching).
 
 ### Hydration Layer (`lib/rails_ai_context/hydrators/`)
 
@@ -213,7 +213,8 @@ Result: controller and view tools automatically include relevant schema informat
 
 Thor-based CLI that works standalone (no Gemfile entry):
 
-- `EntryBoot` - Finds and boots the host Rails app for the standalone binary, or says which tier it fell back to
+- `AppRoot` - Decides which app a command reads before anything reads the working directory: `--app-path` as given, else the working directory, else the nearest app root above it, else the one app below it (several are refused by name, and `init` sets them all up)
+- `EntryBoot` - Boots the app `AppRoot` chose for the standalone binary, or says which tier it fell back to
 - `ToolRunner` - Parses CLI args, resolves tool names, executes tools, formats output
 - Supports `--json` mode for machine-readable output
 - Same 45 tools available as MCP and CLI
@@ -232,7 +233,7 @@ Four cache layers:
 3. **Run cache** (`RunCache`) - thread-local, lives for one `Introspector#call` or `generate_context`: file lists, stats and directory answers every section would otherwise ask again
 4. **Session cache** (`BaseTool.SESSION_CONTEXT`) - Mutex-protected call history, resets on server restart
 
-`LiveReload` watches files and calls `reset_all_caches!` when changes are detected.
+Every server - stdio, HTTP, or the endpoints mounted in the app - checks the files at the start of each tool call and resource read (`BaseTool.refresh_if_files_changed!`, through `Fingerprinter::Snapshot`), reloading the app's code and resetting the caches when they moved, so an answer sees every edit made before its call. That check runs outside the introspection cache's mutex, since a code reload waits for running calls, and a call shares only a check that began after it arrived. `LiveReload` watches the same files and tells clients when they change; it loads no code and drops no cache.
 
 ### Fingerprinter (`lib/rails_ai_context/fingerprinter.rb`)
 
@@ -241,6 +242,7 @@ SHA256-based change detection:
 - Watches: `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`, the Gemfile and Gemfile.lock (or `gems.rb` and `gems.locked`), `package.json`, `tsconfig.json`, `config.ru`, the Rakefile
 - Computes a composite fingerprint from all watched files
 - Used by introspection cache and live reload to detect actual changes
+- `Fingerprinter::Snapshot` answers the same question before every call by stat alone, keeping each directory's listing while the directory's stat holds; a file young enough to have been written twice in one clock tick has its content compared too, and a directory linked in from the app's repository is followed as the readers follow it, its link asked where it leads at every look
 
 ## Key design decisions
 

data/docs/CLI.md

@@ -40,6 +40,10 @@ rails-ai-context serve --transport http --port 6029   # HTTP transport
 | `--port` | `http_port` from config, else `6029` | HTTP listen port |
 | `--no-boot` | off | Skip booting the app; answer from source alone |
 
+Ctrl-C or SIGTERM stops the HTTP server and exits 0. Requests still running get 3 seconds, then Puma's own grace period of 5, before they are cut off, and the process exits within 15 seconds of the signal whatever else is still running.
+
+The server announces itself to the client as `server_name` from config, else `rails-ai-context`. The `RAILS_AI_CONTEXT_SERVER_NAME` environment variable takes the place of that default for one process; a `server_name` the app sets itself still wins. A [workspace](#init-standalone-only) entry sets the variable to put its app first, since VS Code names every tool after the announced name and keeps 13 characters of it.
+
 ### `tool`
 
 Run any of the 45 MCP tools from the terminal.
@@ -67,7 +71,18 @@ Global options may be typed before or after the command name:
 `rails-ai-context --app-path /srv/app doctor` and
 `rails-ai-context doctor --app-path /srv/app` run the same check.
 
-`--app-path` names the Rails root, and defaults to the working directory.
+`--app-path` names the Rails root, taken as given. Left out, every command
+that reads an app finds it the way `bin/rails` and Bundler do: the working
+directory if it is an app, else the nearest app root above it (a directory with
+`config/application.rb`, `config/environment.rb`, or a `bin/rails` that boots an
+app or an engine; never `$HOME`, `node_modules` or a gem install), else the one
+app a level or two below it - looked for everywhere but `/`, `$HOME` and the
+directories above it, which hold too much to search. A walk names the app it chose on stderr, as
+`[rails-ai-context] using app at a/`, so `serve` keeps stdout clean. A folder
+holding several apps is refused with one `--app-path` command per app, and
+`tool --list` there lists the tools without an app. The chosen root is the
+process's working directory for the rest of the run, so `init`, the config and
+every file written land in it.
 `--environment` names the `RAILS_ENV` to boot under. Left out, it resolves the
 way Rails resolves its own environment: the ambient `RAILS_ENV`, then
 `RACK_ENV`, then `development`, reading an empty value as unset. So an app
@@ -114,7 +129,13 @@ from source alone, which is what you want on a repo you have just cloned, on an
 app whose boot is broken, and in CI where booting costs more than the answer.
 
 The same tier is entered automatically when a boot fails, so you get an answer
-either way. Answers that need a running app are marked `[UNAVAILABLE: ...]`
+either way. A boot that hangs (an initializer waiting on a service that is
+down) counts as failed after `RAILS_AI_CONTEXT_BOOT_TIMEOUT` seconds: 20 for
+`serve` over stdio, whose client waits about 30 seconds for its first answer
+and then gives up, and 60 for every other command. Raise it for an app that
+is healthy but slow to boot, and for stdio also raise the client's own limit
+(Claude Code reads `MCP_TIMEOUT`, in milliseconds), or the client stops
+waiting first. Answers that need a running app are marked `[UNAVAILABLE: ...]`
 rather than guessed, and everything else is tagged `[STATIC]` instead of
 `[VERIFIED]`. `docs/COMPATIBILITY.md` lists which of the 40 introspectors answer
 in which tier.
@@ -161,6 +182,8 @@ rails-ai-context context --format claude # Specific format
 |:-------|:--------|:------------|
 | `--format` | all configured | `claude`, `cursor`, `copilot`, `opencode`, `codex`, `json`, `all` |
 
+Without `--format`, `rails ai:context` and `rails-ai-context context` also bring the selected tools' MCP configs up to date, in the command form the install takes now - after `bundle remove rails-ai-context` that is the bare binary. A tool whose config a [workspace](#init-standalone-only) above already serves is left to it. `rails ai:context:<tool>` writes that tool's config along with its files.
+
 The rake tasks `ai:context`, `ai:context:<format>` and `ai:context_for` also read
 `CONTEXT_MODE`: `CONTEXT_MODE=full rails ai:context` overrides `config.context_mode`
 for that run. The standalone binary does not read it.
@@ -176,7 +199,11 @@ rails-ai-context doctor --strict   # exit 1 when any check fails (CI gate)
 rails ai:doctor STRICT=1           # rake equivalent
 ```
 
-Checks include: schema existence, pending migrations, model files, routes, MCP config validity, introspector health, ripgrep availability, Prism gem, Brakeman gem, listen gem, gitignore security, auto_mount security, schema size, view count, and more.
+Checks include: schema existence, pending migrations in every database (and a database that does not exist or does not answer), model files, routes, whether the command each MCP config holds can start, the Codex env snapshot, whether a context run would rewrite the context files, introspector health, ripgrep availability, the Prism and mcp gems, Brakeman gem, listen gem, secret files and .gitignore, auto_mount security, schema size, view count, and more. The [Guide](GUIDE.md#diagnostics) lists every check.
+
+At a mountable engine's root, which boots no app of its own, `bundle exec rails-ai-context doctor` (or `rails-ai-context doctor` for a standalone install) diagnoses the dummy app the engine's `bin/rails` boots - `test/dummy` or `spec/dummy` - and reads the install at the engine's root: its `.rails-ai-context.yml`, MCP configs and context files, the ones an editor opened there uses. `bin/rails app:ai:doctor` reads them there too. Its fixes name the commands that run at the engine's root, such as `bundle exec rails-ai-context context`, and its context check runs that command into a copy of the files to see which it would rewrite.
+
+Every path the report names is named from where the command was typed, and every command a fix gives runs there. Typed in an app's parent folder (`rails-ai-context --app-path shop doctor`), the app's files are named `shop/...`, and a command of the app's goes there first: `rails-ai-context --app-path shop context`, `cd shop && bin/rails db:migrate`, `git -C shop rm --cached config/master.key`. A line for `.gitignore` names the app's own and is written the way that file reads it, from the app's root: Add to shop/.gitignore: `.env.local`. Typed in a folder inside the app (`app/models`), the report names the app's files from its root, as the app names them, while a fix still works where it was typed: `cd ../.. && bin/rails db:migrate`, `git -C ../.. rm --cached .env`, `rails-ai-context --app-path ../.. context`, and Add to ../../.gitignore: `.env`. `rails ai:doctor` reads that folder from the shell's `PWD`, since Rails' `rails` command and rake move up to the app's root before the task runs. Typed at an engine's root, the dummy app's files read `test/dummy/db/schema.rb` and the engine's own `Gemfile.lock` and `app/views`, a command of the engine's runs "at the engine's root" (`bundle install` there needs no folder), and one of the dummy app's goes to `test/dummy` first; typed inside `test/dummy`, the engine's files read `../../Gemfile.lock` and its commands run "in the engine at ../..". A fix that starts with `cd` leaves the shell in that folder, so type the next one from where doctor ran.
 
 ### `watch`
 
@@ -187,7 +214,7 @@ rails ai:watch
 rails-ai-context watch
 ```
 
-Requires the `listen` gem. Watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`.
+Requires the `listen` gem. `rails ai:watch` needs it in the app's Gemfile; the standalone binary uses the app's when its bundle locks one, and otherwise one installed with `gem install listen`. Watches `app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`.
 
 ### `init` (standalone only)
 
@@ -198,7 +225,48 @@ rails-ai-context init
 rails-ai-context init --mcp-only   # MCP config only, no context files
 ```
 
-Asks which AI tools to configure and what to write: MCP config and context files, context files only (CLI mode), or MCP config only. Creates `.rails-ai-context.yml`, the MCP config files (except in CLI mode) and the context files (except with MCP config only). `--mcp-only` skips the second question.
+Asks which AI tools to configure and what to write: MCP config and context files, context files only (CLI mode), or MCP config only. Creates `.rails-ai-context.yml`, the MCP config files (except in CLI mode) and the context files (except with MCP config only). `--mcp-only` skips the second question. Every question - including a re-run's cleanup of dropped tools, and in CLI mode whether to take the gem's entries out of existing MCP configs - is asked before the app boots and anything is written; with MCP config only, the app is not booted at all.
+
+Run inside an app, `init` sets up that app (found the way every command finds it: the [app root](#tool) above a subdirectory, or the one `--app-path` names).
+
+Run in a folder that is no app but holds apps one or two levels down - a **workspace**, the folder an editor or agent is often opened at - it sets the folder up as a whole:
+
+```text
+work/                      <- run `rails-ai-context init` here
+  .mcp.json                   one server per app: rails-ai-context-api, rails-ai-context-web
+  .cursor/mcp.json ...        (every selected AI tool's MCP config, in the folder it reads)
+  api/  .rails-ai-context.yml, CLAUDE.md, ...   each app keeps its own config and context files
+  web/  .rails-ai-context.yml, CLAUDE.md, ...
+```
+
+The AI tools and the setup are asked once. Each app gets its own `.rails-ai-context.yml` and context files, because its server reads them from its own root; a child process generates them with the install that app's server will run. The folder's MCP configs get one server per app, because a client reads its project config from the folder it opened. Each entry is named `rails-ai-context-<app folder>` (the whole path where two apps share a folder name; a short hash where the name would pass 30 characters, since Cursor drops a tool whose server and tool names together pass 60) and points `--app-path` at its app:
+
+```json
+{
+  "mcpServers": {
+    "rails-ai-context-api": {
+      "command": "rails-ai-context",
+      "args": ["serve", "--app-path", "api"],
+      "env": { "RAILS_AI_CONTEXT_SERVER_NAME": "api-rails-ai-context" }
+    },
+    "rails-ai-context-web": {
+      "command": "bundle",
+      "args": ["exec", "rails-ai-context", "serve", "--app-path", "web"],
+      "env": { "BUNDLE_GEMFILE": "web/Gemfile", "RAILS_AI_CONTEXT_SERVER_NAME": "web-rails-ai-context" }
+    }
+  }
+}
+```
+
+- **Paths stay relative**, so a committed file means the same thing on every machine. Claude Code, Codex and OpenCode start a server in the folder they were launched in, so their configs name the app from the workspace (`api`). Cursor and VS Code have a name for the folder their config sits in, `${workspaceFolder}`, so their configs name the app from it (`${workspaceFolder}/api`); Cursor does not promise a working directory.
+- **The command form is each app's own**: the bare binary where the gem is not in the app's Gemfile.lock, `bundle exec` where it is, with `BUNDLE_GEMFILE` naming the Gemfile the app's bundle reads - its own (a linked one by the link's name, so its lockfile stays beside it), else the one its `config/boot.rb` names, as a monorepo's apps share one, else the one `bundle exec` run inside the app would find - since `bundle exec` started in the workspace would look for one there.
+- **`RAILS_AI_CONTEXT_SERVER_NAME` puts the app first** in the name the server announces. VS Code names every tool after that name and keeps 13 characters of it, so without it every app's tools would start `rails-ai-cont`. It is a variable rather than a flag so that an app whose bundle pins an older gem ignores it and starts.
+- A bare `rails-ai-context` entry left in the folder is replaced, since it would serve the folder itself, and so is an entry under a name the gem gives an app in this folder (its folder name or path) when that app's folder is gone, or the app now goes by another name because an app with the same folder name arrived. An entry named `rails-ai-context-...` that runs `rails-ai-context serve` is the gem's: dropping an AI tool removes it from that tool's config. One that runs no command, such as an HTTP entry of your own under either name, is left alone, and so is a second entry you named yourself for an app (`rails-ai-context-api-2` included), one that names its app through a variable the tool expands (`${userHome}`), and one naming an app outside the folder.
+- A config that does not parse as JSON, or holds comments a rewrite would drop, is left as it is, with a warning that names the entry to add by hand. Trailing commas, which VS Code's and OpenCode's take, are read under json 2.9 or later; Claude Code's `.mcp.json` and Cursor's `.cursor/mcp.json` are held to plain JSON, so a comment or trailing comma there is reported as one the client cannot read. An empty one is filled, and a byte order mark at the head of one stays.
+- `--app-path` naming a folder of apps sets that folder up the same way; every other command lists the apps below it.
+- An app whose bundle is not installed yet (a Gemfile and no lockfile) is served by this binary unless its Gemfile names the gem, or pulls gems in from other files (`eval_gemfile`, `gemspec`) that could.
+
+Start the client in the workspace folder. A client started inside one of the apps (Claude Code, Codex and OpenCode still read a config above it) runs each workspace server from there, where the relative path misses; the server says which folder the path was written for. To open an app on its own, run `init` inside it as well. `init` warns when an app declares a Ruby other than the one the workspace runs, since every server it starts runs under that one. `doctor` inside one of the apps finds the workspace's config one or two levels up.
 
 ### `version`
 
@@ -239,7 +307,8 @@ rails 'ai:preset[architecture]'
 ### `tree`
 
 Print a tree of every command. `rails-ai-context help <command>` lists that
-command's options.
+command's options, and so do `rails-ai-context <command> --help` and `-h`
+(after a tool's name, `--help` is that tool's: `tool schema --help`).
 
 ```bash
 rails-ai-context tree
@@ -306,6 +375,10 @@ rails-ai-context tool schema --table users --json
 JSON=1 rails 'ai:tool[schema]' table=users
 ```
 
+stdout then holds the envelope (`tool`, `output`, `error`) and nothing else.
+Whatever the app prints while it boots or while the tool runs - an
+initializer's `puts`, Sidekiq's Redis connection line - goes to stderr.
+
 ---
 
 ## Common workflows