rails-ai-context 5.32.2 → 5.34.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.
@@ -56,7 +66,7 @@ The other half of the same problem is the reverse trip. Once a name is the decla
 
 ## Table name
 
-The table a model reads. Rails builds it as `table_name_prefix` + the demodulized class name, pluralized unless `pluralize_table_names` is off, + `table_name_suffix`, unless the class assigns one itself or is an STI child, which reads its parent's. The static tier answers the same order from source: an explicit `self.table_name =`, else the table of the model it inherits from, else the prefix and suffix the enclosing modules declare around the file's own basename. That basename is pluralized unless the class, then its superclass chain, then the app sets `pluralize_table_names = false`. The app-wide affixes and pluralize setting come from `ActiveRecordSettings`, which reads config/application.rb, the environment file, the initializers and `on_load(:active_record)` blocks. Never the underscored constant - that turns `Admin::ActionLog` into `admin/action_logs` and `OAuthClientConfig` into `o_auth_client_configs`, neither of which is a table.
+The table a model reads. Rails builds it as `table_name_prefix` + the demodulized class name, pluralized unless `pluralize_table_names` is off, + `table_name_suffix`, unless the class assigns one itself or is an STI child, which reads its parent's. The static tier answers the same order from source: an explicit `self.table_name =`, else the table of the model it inherits from, else the prefix and suffix the enclosing modules declare around the file's own basename. That basename is pluralized unless the class, then its superclass chain, then the app sets `pluralize_table_names = false`. A class on a parent the app does not define (`Tag < ActsAsTaggableOn::Tag`) reads the parent's table, which the static tier takes from the schema: the table it holds among the parent's names and the class's own. The app-wide affixes and pluralize setting come from `ActiveRecordSettings`, which reads config/application.rb, the environment file, the initializers and `on_load(:active_record)` blocks. Never the underscored constant as an answer - that turns `Admin::ActionLog` into `admin/action_logs` and `OAuthClientConfig` into `o_auth_client_configs`, neither of which is a table; a gem parent's underscored name is only a candidate the schema must hold.
 
 `TableName` reads the five declarations of one class body (`table_name`, `table_name_prefix`, `table_name_suffix`, `pluralize_table_names` and `primary_key`) and holds the two derivations; walking the namespace and the superclass chain belongs to the caller, because only it has the other files. A reader that starts from a model name instead of a file asks `TableName.for_model_name`, which takes the table the model tier already recorded before falling back to the convention. A module prefix declared outside the model directories is still invisible, an engine's in `lib/**/engine.rb` aside, so the answer stays [STATIC].
 
@@ -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

@@ -4,9 +4,9 @@
 
 *Give your AI coding assistant ground truth about your Rails app*
 
-[![Gem Version](https://img.shields.io/gem/v/rails-ai-context?style=flat-square&color=brightgreen)](https://rubygems.org/gems/rails-ai-context)
-[![Downloads](https://img.shields.io/gem/dt/rails-ai-context?style=flat-square&color=blue)](https://rubygems.org/gems/rails-ai-context)
-[![CI](https://img.shields.io/github/actions/workflow/status/crisnahine/rails-ai-context/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/crisnahine/rails-ai-context/actions)
+[![Gem Version](https://img.shields.io/gem/v/rails-ai-context?style=flat-square&color=brightgreen&cacheSeconds=21600)](https://rubygems.org/gems/rails-ai-context)
+[![Downloads](https://img.shields.io/gem/dt/rails-ai-context?style=flat-square&color=blue&cacheSeconds=21600)](https://rubygems.org/gems/rails-ai-context)
+[![CI](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/crisnahine/rails-ai-context/actions/workflows/ci.yml)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green?style=flat-square)](https://registry.modelcontextprotocol.io)
 [![Ruby](https://img.shields.io/badge/Ruby-3.1_to_4.0-CC342D?style=flat-square&logo=ruby&logoColor=white)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.0_to_8.1-CC0000?style=flat-square&logo=rubyonrails&logoColor=white)](https://github.com/crisnahine/rails-ai-context)
@@ -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,35 @@ 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.
       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/config/routes.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 RailsAiContext::Engine.routes.draw do
-  # The engine is not namespace-isolated, so the controller must be
-  # referenced by its full path or Rails resolves a top-level McpController.
-  match "/", to: "rails_ai_context/mcp#handle", via: :all
+  # The class, not "rails_ai_context/mcp", which the router camelizes with the app's inflections.
+  match "/", to: RailsAiContext::McpController.action(:handle), via: :all
 end

data/docs/ARCHITECTURE.md

@@ -26,7 +26,7 @@ graph TD
         subgraph engine["Introspection Engine"]
             direction LR
             I["Introspectors\n40 modules\nPresets\nCached"]
-            AST["AST Engine\nPrism\n44 listeners\nConfidence tags"]
+            AST["AST Engine\nPrism\n45 listeners\nConfidence tags"]
             H["Hydration Layer\nSchema hints\ninjected into\ntool responses"]
         end
 
@@ -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