rails-ai-context 5.32.2 → 5.34.0

data/docs/INTROSPECTORS.md

@@ -181,10 +181,10 @@ It runs a single-pass Dispatcher that walks the AST once and feeds events to all
 |:---------|:---------------|
 | AssociationsListener | `belongs_to`, `has_many`, `has_one`, `has_and_belongs_to_many`, the polymorphic `belongs_to` of `delegated_type`, the `belongs_to` of `acts_as_tenant` (tenant defaults to `:account`), under the options of an enclosing `with_options` block |
 | ValidationsListener | `validates`, `validates_*_of`, custom `validate :method`, under the options of an enclosing `with_options` block |
-| ScopesListener | `scope :name, -> { ... }`, `lambda { ... }` and the block form |
+| ScopesListener | `scope :name, -> { ... }`, `lambda { ... }` and the block form; a scope declared in an `each` over a literal list, inline or a constant the file assigns (`KINDS.each { \|k\| scope k, -> { ... } }`), as one scope per element, tagged `[INFERRED]` |
 | EnumsListener | Rails 7+ and legacy enum syntax, prefix/suffix options |
-| CallbacksListener | All AR callback types including `around_*`, `after_touch`, `after_initialize` and `after_find`; `after_commit` with `on:` resolution; a callback object as the source wrote it (`Normalizer`, `Normalizer.new`), a block as `[inline_block]`; `if:`/`unless:` kept as the source wrote them, and the options of an enclosing `with_options` block |
-| MacrosListener | (each attribute macro and `has_secure_password` with its keyword options as written, under `written`) `encrypts`, `normalizes`, `delegate`, `has_secure_password`, `serialize`, `store`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `generates_token_for`, `attribute`, `alias_attribute`, `store_accessor`, `self.ignored_columns`, `has_secure_token`, `accepts_nested_attributes_for`, `attr_readonly`, `query_constraints`, `connects_to` as written (a child carries its base's, with the base's name under `declared_in`), the class settings `self.inheritance_column`/`store_full_sti_class`/`strict_loading_by_default`/`implicit_order_column`/`locking_column =` as written, an `aasm` block's states, initial state, events and transitions, and model gems' class macros (`GEM_MACROS`: `has_paper_trail`, `friendly_id`, `mount_uploader`, `monetize`, `pg_search_scope`, `acts_as_list` and others) as written, without their block |
+| CallbacksListener | All AR callback types including `around_*`, `after_touch`, `after_initialize` and `after_find`; `after_commit` with `on:` resolution; a callback object as the source wrote it (`Normalizer`, `Normalizer.new`), a block as `[inline_block]` with its declaration as written; `if:`/`unless:` kept as the source wrote them, and the options of an enclosing `with_options` block; the commit callbacks turbo-rails' `broadcasts`, `broadcasts_to`, `broadcasts_refreshes` and `broadcasts_refreshes_to` declare, each with the method it runs; `before_`/`after_`/`around_<event>` on a chain `define_model_callbacks` makes, kept when the same file defines it (honouring `only:`), and for a chain a library defines elsewhere (Paperclip's `before_<attachment>_validate`, `after_post_process`) only when the model walk asks, so the booted tier keeps the ones whose chain the model's `__callbacks` holds |
+| MacrosListener | (each attribute macro and `has_secure_password` with its keyword options as written, under `written`) `encrypts`, `normalizes`, `delegate`, `has_secure_password`, `serialize`, `store`, `has_one_attached`, `has_many_attached`, `has_rich_text`, `generates_token_for`, `attribute`, `alias_attribute`, `store_accessor`, `self.ignored_columns`, `has_secure_token`, `accepts_nested_attributes_for`, `attr_readonly`, `query_constraints`, the turbo-rails broadcast macros (`broadcasts`, `broadcasts_to`, `broadcasts_refreshes`, `broadcasts_refreshes_to`), `connects_to` as written (a child carries its base's, with the base's name under `declared_in`), the class settings `self.inheritance_column`/`store_full_sti_class`/`strict_loading_by_default`/`implicit_order_column`/`locking_column =` as written, an `aasm` block's states, initial state, events and transitions, and model gems' class macros (`GEM_MACROS`: `has_paper_trail`, `friendly_id`, `mount_uploader`, `monetize`, `pg_search_scope`, `acts_as_list` and others) as written, without their block (Paperclip's `has_attached_file` by its name and attachment only) |
 | MethodsListener | `def`/`def self.`, visibility tracking, parameter extraction, `class << self`, the methods `delegate` and Forwardable's `def_delegators`/`def_delegator` define (public unless `private: true`, and with no `end_location`, since a delegation has no body), and the methods `alias`, `alias_method`, `attr_*`, `define_method` with a literal name, `class_attribute` and `cattr_*`/`mattr_*` define (an alias keeps its original's visibility and parameters; Active Support's accessors are public on the class and, unless an option turns them off, on instances); each `def` carries `offset`/`end_offset`, which `SourceIntrospector.outside_defs` pairs against a call's `offset` to tell a call on the same line as a def from one inside it; a `Struct.new`/`Class.new`/`Module.new`/`Data.define` block assigned to a constant is that constant's body, and a `def self.x` in `included do` is marked `class_methods_block` like a `def x` in `class_methods do`; `include_initialize: true` adds the constructor a caller reports on its own |
 | MixinsListener | `include`, `prepend`, `extend`, `singleton_class.include` and `singleton_class.prepend` (`singleton_class.extend` is not read), flagging the ones that reach the ancestor chain, as reflection reports them. GitLab's `prepend_mod_with("Note")`, `include_mod_with`, `extend_mod_with` and their `_mod` forms record `EE::Note` and `JH::Note` flagged `edition`; `ConcernMembership.owned_by` keeps one only where the app has its file, and credits `Note.prepend X` to Note |
 
@@ -194,6 +194,7 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 
 | Listener | What it detects |
 |:---------|:---------------|
+| ForeignEvalsListener | A class body's blocks evaluated on another receiver (`translation_class.class_eval do`, `other.instance_eval do`), outside any `def`, with every outermost call inside by the line it starts on, an `if`/`unless` condition left out. The model walk passes it beside the default listeners (`ModelIntrospector::MODEL_LISTENERS`) and moves what the blocks declare to "Declared on another class" |
 | GenericMacroListener | Any receiver-less macro you name: `GenericMacroListener.new(:devise, :rate_limit)`; `any_receiver: true` also counts `base.macro`, as a mixin's `self.included(base)` hook writes it. Returns args, values (with a source-slice fallback), options, option values and option nodes, `proc_lines` (the line each block, `->`, `lambda {}`, `proc {}` or `Proc.new {}` argument opens on, as `Proc#source_location` gives it), plus the nesting: `parent_offset` is the offset of the target macro call whose block this one sits in, paired against each call's own `offset` rather than its line |
 | ConditionalMacroListener | GenericMacroListener plus `condition`, the `if`/`unless`/`case` branches the call sits under (`BranchConditions`), as `if Rails.env.test?`. Controller filters read it through FilterMacroListener, so `before_action :x if Rails.env.test?` is listed with its condition |
 | FilterMacroListener | ConditionalMacroListener plus `callbacks`, what each positional argument adds, named at its node: `[:name, x]` for a symbol, string or class, `[:object, Klass]` for an instance (`Class` for an anonymous class), `[:lambda]` for `-> {}` or `lambda {}`, `[:block]` for a proc, `[:unread, source]` for anything else. Used by `ControllerFilters`, so the static tier names each callback as the booted tier does |
@@ -217,7 +218,7 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 | SchemaDslListener | `schema.rb`: `create_table`, `t.string`, `t.column`, `t.index`, `add_foreign_key`, `create_enum`, `create_schema`, `create_view`, `create_virtual_table`, the `ActiveRecord::Schema[x.y]` version stamp (a nil one for the unstamped `Schema.define` of Rails before 7.0), and the comment the dumper writes for a table it could not describe. Names drop `public.` unless `raw_names:` is set, which SchemaReader uses to name them against the search path |
 | MigrationDslListener | Migration DSL: `create_table`, `add_column`, `add_index`, `add_reference`, and friends |
 | MigrationReplayListener | What a replay needs beside the DSL: `def down`, `down`/`revert` blocks, and `t.timestamps` |
-| RoutesDslListener | `config/routes.rb`, resolving namespace/scope/resources nesting into flat routes (a `controller:` with a leading slash is absolute, as in Rails); routing concerns (`concern` definitions replayed at each `concerns:` site), `with_options` defaults merged under each inner call, `match ... via:` (or the `via:` of an enclosing `scope`) as one route answering each verb it names (`GET|POST`, and `ANY` for `via: :all`, as the booted table has it), the controller a `scope(controller:)` or a route's own `controller:` names (with Rails' `a/b` shorthand when no action is given), and the `as:`, `param:`, `module:`, `path:` and `only:`/`except:` options. A block drawn through an app class (`ApiRouteSet::V1.draw(self) do`) takes the path and `as:` prefixes that class's `self.prefix` and `mapper_prefix` return as literals, or a literal prefix argument; a class whose prefix is not a literal, and that class's own `resources`, are counted as unexpanded. Routes drawn into an engine's table (`Spree::Core::Engine.routes.draw`) sit under the engine's namespace and carry `engine:`, which the route introspector files under that engine's mount, apart from the app's count. A file pulled in by `draw` is walked inside the scope its `draw` sits in, once per scope that draws it, so `draw :api` under `namespace :api` and `scope module: :v1` routes to `api/v1/...` at `/api/...` |
+| RoutesDslListener | `config/routes.rb`, resolving namespace/scope/resources nesting into flat routes (a `controller:` with a leading slash is absolute, as in Rails); routing concerns (`concern` definitions replayed at each `concerns:` site), `with_options` defaults merged under each inner call, `match ... via:` (or the `via:` of an enclosing `scope`) as one route answering each verb it names (`GET|POST`, and `ANY` for `via: :all`, as the booted table has it), the controller a `scope(controller:)` or a route's own `controller:` names (with Rails' `a/b` shorthand when no action is given), and the `as:`, `param:`, `module:`, `path:` and `only:`/`except:` options. A block drawn through an app class (`ApiRouteSet::V1.draw(self) do`) takes the path and `as:` prefixes that class's `self.prefix` and `mapper_prefix` return as literals, or a literal prefix argument; a class whose prefix is not a literal, and that class's own `resources`, are counted as unexpanded. Routes drawn into an engine's table (`Spree::Core::Engine.routes.draw`) sit under the engine's namespace and carry `engine:`, which the route introspector files under that engine's mount, apart from the app's count. A file pulled in by `draw` is walked inside the scope its `draw` sits in, once per scope that draws it, so `draw :api` under `namespace :api` and `scope module: :v1` routes to `api/v1/...` at `/api/...`. A resource's `nested do` block draws under the parent's nested path, as a direct child would. A block from any other method draws in place only for `constraints`, `defaults`, Devise's `devise_scope`/`as`/`authenticate`/`authenticated`/`unauthenticated` and route_translator's `localized`; any other block that holds routes (an app's `api_v1 do`, versionist's `api_version`) may scope them in a way the walk cannot see, so its routes are left out and the block is counted once as unexpanded |
 | MountListener | `mount Sidekiq::Web, at: "/sidekiq"`, the hash form, and a Rack app attached with `match "/metrics", to: MetricsApp` - `mount` is that call with a name derived. Paths carry the enclosing `namespace`/`scope` prefix; a scope whose own name is an expression yields no path rather than an unprefixed one, and `scope path: nil` adds no segment. A mounted app built by a call on a constant (`Flipper::UI.app(Flipper)`) is named by that call, arguments off. A mount under `if`/`unless`/`case` carries that `condition` |
 | GemfileDslListener | `gem "name", "version"`, `group :development do ... end` and `eval_gemfile "path"` (a literal or `File.expand_path("x", __dir__)`) with the groups around it; `ruby "3.3.6"` with its `engine:` and `engine_version:`; an `:unknown_gems` entry for `gemspec` and for a `gem` or `eval_gemfile` whose argument is not a literal |
 | RakeTaskDslListener | `namespace` (with the span its block covers), `desc`, `task`, `multitask` in `.rake` files |
@@ -317,7 +318,7 @@ Thread-safe parse cache using `Concurrent::Map`:
 - A file whose stat (mtime, size, inode) matches the last read answers without reading or hashing it, but only once that file was already two seconds older than the read, so a same-size rewrite within one mtime tick is still read
 - Bounded at 500 parses; a recorded stat is dropped with its parse
 - Shared by all AST-based introspectors
-- Cleared on `reset_all_caches!` (triggered by live reload)
+- Cleared on `reset_all_caches!` (when a server sees the files change: live reload, or the check at each call)
 
 ### RunCache
 
@@ -329,13 +330,14 @@ Answers kept for one introspection run and dropped when it ends: the file list f
 
 Introspection results are cached at three levels:
 
-1. **Introspection cache** - Full context hash, invalidated by TTL (`config.cache_ttl`, default: 60s) and fingerprint change
+1. **Introspection cache** - Full context hash, invalidated by TTL (`config.cache_ttl`, default: 60s) and, in a server, as soon as the fingerprint changes
 2. **AST cache** - Per-file parse results, invalidated by file content change (SHA256), with a stat shortcut for a file older than the read
 3. **Run cache** - File lists, stats and directory answers for one introspection run, dropped when it ends
 
-The **Fingerprinter** computes a composite SHA256 from all watched directories (`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). When the fingerprint changes, the introspection cache is invalidated even if TTL hasn't expired.
+The **Fingerprinter** reads one set of files: all watched directories (`app/`, `config/`, `db/`, `lib/`, `rakelib/`, `test/`, `spec/`), the Gemfile and `Gemfile.lock` (or `gems.rb` and `gems.locked`), `package.json`, `tsconfig.json`, `config.ru` and the Rakefile. When one of them changes, a server drops the introspection cache even if the TTL hasn't expired, and in the booted tier reloads the app's code first, so what reflection reads (an association, an enum) is current too, wherever the app can reload. Under `RAILS_ENV=test`, or in production with eager loading, `config.enable_reloading` is off and Rails keeps the code it booted with: what reflection reads stays as of boot (validations and callbacks are read off the source, so they still follow the edit), and once a file under the app's autoload paths changes, every answer ends with a note naming it and asking for a restart.
 
-**Live Reload** watches these directories and calls `reset_all_caches!` when changes are detected, then notifies connected MCP clients via `notify_resources_list_changed`.
+- **Every server** - stdio, HTTP, or the endpoints mounted inside the app - checks before each tool call and resource read, so an answer sees every edit made before the call began. `Fingerprinter::Snapshot` stats each watched directory and file and lists a directory again only when its stat moved: about a millisecond on a small app, about 30 ms at 10,000 files. Only a check that began after a call arrived stands in for that call's own, so calls one after another each check and calls made at once wait for one check together. Inside a request the app serves, Rails' own reloader has already reloaded the code.
+- **Live Reload** (the `listen` gem: the app's bundle's, or for the standalone binary one installed beside it) watches these directories and notifies connected MCP clients via `notify_resources_list_changed`. It loads none of the app's code and drops no cache: a change reaches it after the 1.5-second debounce, and by then the call that followed the edit has checked the files itself.
 
 ---
 

data/docs/QUICKSTART.md

@@ -32,7 +32,7 @@ that is `--mcp-only`.
 Three more prompts appear only when they apply:
 
 - **Remove their generated files?** - on a re-run that drops a tool you picked before. Default: keep them. A yes removes only what the gem generated, never a rule file or a line you wrote.
-- **Install a pre-commit hook that validates Rails references?** - in a git repo that has no pre-commit hook yet. Default: no.
+- **Install a pre-commit hook that checks staged Ruby, ERB and JavaScript files for syntax errors?** - in a git repo that has no pre-commit hook yet. Default: no.
 - **Delete them?** - in a terminal, when rule files left over from before v5.0.0 are found. Default: no.
 
 `--defaults` skips every prompt and takes each default: all five tools, keep the files, MCP config + context files, no hook, keep legacy files. Every step is listed in [What the install generator does](GUIDE.md#what-the-install-generator-does).
@@ -77,7 +77,7 @@ The install generator created:
 ## Verify it works
 
 ```bash
-# Check AI readiness (25 diagnostic checks)
+# Check AI readiness
 rails ai:doctor          # In-Gemfile
 rails-ai-context doctor  # Standalone
 
@@ -119,7 +119,7 @@ rails 'ai:tool[conventions]'
 | `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any tool |
 | `rails ai:tool` | `rails-ai-context tool --list` | List all tools |
 | `rails ai:doctor` | `rails-ai-context doctor` | Diagnostics |
-| `rails ai:watch` | `rails-ai-context watch` | Auto-regenerate on change |
+| `rails ai:watch` | `rails-ai-context watch` | Auto-regenerate on change (needs `listen`: in the Gemfile, or `gem install listen` standalone) |
 | `rails ai:context` | `rails-ai-context context` | Regenerate context files |
 
 ---

data/docs/RECIPES.md

@@ -367,7 +367,7 @@ The gem wraps its generated content in section markers:
 <!-- END rails-ai-context -->
 ```
 
-Add your custom rules **outside** these markers - they're preserved on regeneration.
+Add your custom rules **outside** these markers - they're preserved on regeneration. A hand-written `app/models/AGENTS.md` or `app/controllers/AGENTS.md` is kept the same way: your text stays, and the gem's listing goes between the markers above it.
 
 **Step 3: Remove manual maintenance**
 

data/docs/SECURITY.md

@@ -11,7 +11,7 @@
 ---
 
 > [!CAUTION]
-> This gem is designed for **development environments**. The query tool is disabled in production by default. Sensitive files are blocked. All 45 tools are read-only.
+> This gem is designed for **development environments**. The query tool, and MCP over HTTP from inside the app, are disabled in production by default. Sensitive files are blocked. All 45 tools are read-only.
 
 ## Design principles
 
@@ -50,14 +50,29 @@ flowchart LR
 Before any query reaches the database:
 
 - Strips comments: block (`/* */`), line (`--`), and on MySQL `#`. A comment marker inside a quoted string or identifier is data and stays. The query that runs is this stripped text, never the raw input, so nothing the checks did not read reaches the database
-- **Blocks write keywords**: INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE, SET, COPY, MERGE, REPLACE
+- **Blocks write keywords**: INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE, SET, COPY, MERGE, REPLACE. The keyword check (and the `SELECT … INTO` table-creation check) reads **quote-masked text**, so a keyword inside a string literal is data: `… WHERE notes LIKE '%update%'` and `… = 'put into box'` are reads, not writes. `REPLACE` is matched only as the statement; the string function `replace(col, a, b)` every database has (a `REPLACE` immediately followed by `(`) is allowed. `SHOW CREATE TABLE` / `SHOW CREATE VIEW` are allowed despite the `CREATE` (see below)
 - **Blocks lock clauses**: FOR UPDATE, FOR SHARE, FOR NO KEY UPDATE
 - **Blocks dangerous SHOW**: GRANTS, PROCESSLIST, BINLOG, SLAVE, MASTER, REPLICAS
-- **Blocks SELECT INTO**: prevents table creation via SELECT, and `INTO OUTFILE` / `INTO DUMPFILE` writes to disk
+- **Blocks SELECT INTO**: prevents table creation via SELECT. `INTO OUTFILE` / `INTO DUMPFILE` disk writes, and the file/network functions above, stay matched on the **raw (unmasked) text** - no read-only transaction stops a server-side file write, so these are never read as data
 - **Blocks file and network functions**: `pg_read_file`, `pg_read_binary_file`, `pg_ls_dir`, `pg_stat_file`, `lo_import`, `lo_export`, `dblink*`, `LOAD DATA`, `LOAD_FILE`, `load_extension` and their relatives, checked before and after comment stripping
-- **Blocks multi-statements**: multiple semicolons
-- **Blocks injection patterns**: OR 1=1, OR true, OR ''='', UNION SELECT
-- **Allows only**: SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, DESC
+- **Blocks session-effecting / administrative functions**: a read-only transaction does not stop these, and their effect lingers on the pooled connection. PostgreSQL: `pg_terminate_backend`, `pg_cancel_backend`, `pg_reload_conf`, `pg_stat_reset*`, `pg_switch_wal`, `pg_create_restore_point`, replication-slot and -origin functions, `pg_logical_emit_message`, `pg_advisory_lock*`, `set_config`, `pg_notify`, `txid_current` and their relatives; MySQL: `GET_LOCK`, `RELEASE_LOCK`, `RELEASE_ALL_LOCKS`, `IS_FREE_LOCK`, `IS_USED_LOCK`. This name list is the first layer; on PostgreSQL the plan's VOLATILE-function check (below) closes the rest of the family
+- **Blocks column-alias lists**: a CTE or FROM-item list such as `t(a, b, c)` renames the columns a wildcard returns, which would carry sensitive columns out under harmless names. A type modifier (`numeric(10,2)`, `varchar(255)`), a record-function list (`AS t(a int, b text)`) and a single-column alias are left alone. A list whose body is a `VALUES` clause (`(VALUES (1,'a')) AS v(id, name)`, `WITH v(id, name) AS (VALUES …)`) renames no table column - `VALUES` has none - so it is allowed; the body is identified by balancing parentheses on quote-masked text, so one inside a literal does not move its bounds, and a sensitive name written inside the `VALUES` rows is still caught by the textual check. A FROM-item table-alias list is always a rename and is refused
+- **Blocks multi-statements**: multiple semicolons, read on quote-masked text so a `;` inside a string literal or a `DO $$ … ; … $$` block body is not mistaken for a second statement (a `DO` block is then refused plainly as a disallowed statement, not for the wrong reason)
+- **Blocks injection patterns**: OR 1=1, OR true, OR ''=''
+- **Refuses any UNION**: a UNION takes its column names from its first SELECT, so another table's rows - a wildcard's columns included - would come out under those names, past the redaction that reads names. Every spelling is refused (`UNION`, `UNION ALL`, `UNION DISTINCT`, a parenthesised `UNION (SELECT ...)`), recursive CTEs with it; `INTERSECT` and `EXCEPT` return only their first SELECT's rows and stay. On PostgreSQL a "union" inside a string literal is data
+- **Blocks sensitive column references**: see Layer 4 - a query whose text names a sensitive column, directly or through an alias or expression, is refused before execution
+- **Allows only**: SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, DESC. `SHOW CREATE TABLE` and `SHOW CREATE VIEW` are allowed so schema can be inspected; every other `SHOW CREATE` (`USER`, whose output includes credential hashes, `DATABASE`, `FUNCTION`, …) keeps its `CREATE` and is refused. A returned definition is passed through secret redaction before it is shown, so a credential embedded in it - a FEDERATED table's `CONNECTION='mysql://user:pass@host/db'` - comes back as `mysql://[FILTERED]@host/db`
+
+### Layer 1b - PostgreSQL semantic analysis (planning only)
+
+The textual layer cannot see a whole-row serialisation (`SELECT row_to_json(u.*) FROM users u`) or an admin function introduced through a view, because no sensitive column name appears in the query. On PostgreSQL, before the query runs, the tool plans it with `EXPLAIN (VERBOSE, FORMAT JSON)` inside the same read-only transaction - planning only, nothing executes, not even a VOLATILE function (the planner does not fold one). The plan is refused when it:
+
+- holds a **whole-row reference** (`alias.*`) to a relation that has a sensitive column - this closes `row_to_json(u)`, `to_json(u)`, `u::text`, `array_agg(u)`, `json_agg(u)`, `hstore(u)`, `concat(u.*)`, `string_agg(u::text, …)`, a bare `SELECT u`, and the same through a view, subquery or CTE;
+- **uses a sensitive column** anywhere but as a plain pass-through output - a `ROW(u.*)` the planner expanded into named columns, or a `WHERE` / `ORDER BY` oracle;
+- **launders a sensitive column** through an intermediate the plan's top node does not name - a `MATERIALIZED` CTE, a subquery scan, or a set operation (`INTERSECT` / `EXCEPT`) - so its value would reach a result column that the output-provenance redaction (Layer 4) cannot pin. These are refused rather than redacted;
+- names any **VOLATILE function** (`pg_proc.provolatile = 'v'`) outside a short read-only allowlist. `pg_proc` marks a function VOLATILE when its answer may change within one statement, which is as true of a reader of live server state as of a writer, so VOLATILE alone does not mean "changes state". The allowlist holds only built-in C functions that write nothing: value generators (`random`, `clock_timestamp`, `gen_random_uuid`, `timeofday`, `uuid_generate_v4`, and `pg_sleep*`, which the statement timeout bounds); the size readers (`pg_total_relation_size`, `pg_relation_size`, `pg_table_size`, `pg_indexes_size`, `pg_database_size`, `pg_tablespace_size`); the lock-table snapshot readers (`pg_lock_status` - what the `pg_locks` view reads - `pg_blocking_pids`, `pg_safe_snapshot_blocking_pids`); and the recovery / WAL-position readers (`pg_is_in_recovery`, `pg_is_wal_replay_paused`, `pg_get_wal_replay_pause_state`, `pg_current_wal_lsn` and the other `pg_current_wal_*` / `pg_last_wal_*` / `pg_last_xact_replay_timestamp` readers). `pg_stat_activity` reads through `pg_stat_get_activity`, which is STABLE, so it was never refused. Anything else VOLATILE is not run, and the refusal says plainly that the function is VOLATILE and not on the read-only list - not that it changes state. This is how the admin-function family is closed robustly, rather than by an ever-growing name list.
+
+A whole-row read of a relation with no sensitive column (`row_to_json(posts.*)`) is allowed. Before these checks scan a plan expression, its string constants are masked (PostgreSQL's deparser always doubles quotes and never emits an `E''` string, so a constant is matched exactly), so a sensitive word inside a `'%key%'::text` filter or a literal argument is not mistaken for a column or a function.
 
 ### Layer 2 - Database-level read-only
 
@@ -67,6 +82,7 @@ After validation, the query runs inside a transaction:
 |:---------|:----------|
 | PostgreSQL | `SET TRANSACTION READ ONLY` + `SET LOCAL statement_timeout` |
 | MySQL | `SET TRANSACTION READ ONLY` + `MAX_EXECUTION_TIME` hint |
+| MariaDB | `SET TRANSACTION READ ONLY` + `SET STATEMENT max_statement_time = <seconds> FOR <query>` (MariaDB ignores MySQL's hint, so a long query would otherwise run unbounded) |
 | SQLite | A read-only connection in a child process, killed at timeout |
 
 On PostgreSQL and MySQL the query executes inside a transaction, then rolls back (even if it could write, it can't). Any other adapter has no database-level guard: the query runs with Layer 1 validation and the row limit only.
@@ -88,16 +104,30 @@ lock in WAL mode does not block it.
 
 - Default: 100 rows
 - Configurable: `config.query_row_limit` (hard cap: 1000)
-- Applied as a `LIMIT` clause appended to the query. A `LIMIT` or `FETCH FIRST` that ends the query is lowered to the cap, and one inside a subquery is left as written
-- The rows that come back are cut to the cap too, so the answer holds it whatever the database made of the text
+- Applied as a `LIMIT` clause appended to the query, which fetches **one row past the cap** (`cap + 1`): a `LIMIT` or `FETCH FIRST` that ends the query is rewritten to `min(n, cap + 1)`, and one inside a subquery is left as written
+- The rows that come back are cut to the cap, so the answer holds it whatever the database made of the text
+- The note that rows were held back is added **only when more than the cap came back** - the extra row proves the cap actually cut the answer - then the extra row is dropped. A result that exactly fills the cap (every row fit) gets no note, which fixes the old "N rows shown; the query returned at least this many" appearing when nothing was held back. The note reads `100 rows shown; the query returned more (the row limit of 100; pass limit: up to 1000 to see more)` and rides every format; in CSV it sits after a blank line, outside the comma block, so a parser still reads clean rows
 
 ### Layer 4 - Sensitive column rejection
 
-A query that names a sensitive column is **rejected before execution**, not redacted after it:
+A query that names a sensitive column is **rejected before execution**, not redacted after it. One rule decides what is sensitive, used by the pre-execution refusal, the PostgreSQL plan check and result redaction alike. A column is sensitive when it is:
+
+- in `config.query_redacted_columns`, or the fixed built-in list;
+- an `encrypts` column of one of your models;
+- a name the heuristic catches: it ends in `password`, `secret`, `token`, `key`, `digest` or `hash`, or contains `password`, `secret` or `token`
+
+minus anything in `config.query_allowed_columns`.
+
+**Default redacted patterns:** `password_digest`, `encrypted_password`, `password_hash`, `reset_password_token`, `confirmation_token`, `unlock_token`, `otp_secret`, `session_data`, `secret_key`, `api_key`, `api_secret`, `access_token`, `refresh_token`, `jti`. Those are the defaults of `config.query_redacted_columns`. The fixed built-in list adds `password_reset_token`, `remember_token`, `secret` and `private_key`.
 
-**Default redacted patterns:** `password_digest`, `encrypted_password`, `password_hash`, `reset_password_token`, `confirmation_token`, `unlock_token`, `otp_secret`, `session_data`, `secret_key`, `api_key`, `api_secret`, `access_token`, `refresh_token`, `jti`
+The pre-execution refusal matches on two things, case-insensitive and word-bounded:
 
-Those are the defaults of `config.query_redacted_columns`. A fixed built-in list is checked as well, which adds `password_reset_token`, `remember_token`, `secret` and `private_key`. Matching is by name, case-insensitive and word-bounded, against both lists. `SELECT password_digest AS pd FROM users` is blocked outright: post-execution redaction reads the column names the database returns, which the caller controls through aliases and expressions, so it cannot be relied on.
+- **the fixed names above**, on every adapter whether or not they are real columns, so the check holds even with no connection;
+- **every real column of your schema that the rule flags** - read from the live connection, falling back to the cached schema. This catches an app-specific column the heuristic flags (`api_token`, `auth_token`) through any alias or expression, not only an exact configured name. Rails' own bookkeeping tables (`ar_internal_metadata`, `schema_migrations`) are left out: their columns are never secrets, and `ar_internal_metadata.key` ends in "key", so counting it refused every query whose text held the word "key".
+
+So `SELECT password_digest AS pd FROM users`, `SELECT upper(api_token) FROM users` and `SELECT (SELECT api_token FROM users LIMIT 1) AS leaked` are all refused: post-execution redaction reads the output column names, which the caller controls through aliases and expressions, so it cannot be relied on. A table or alias that merely contains a sensitive word (a `tokens` table) does not trip the check - only a real column name does. `SELECT *` stays allowed, and its sensitive columns are redacted in the result.
+
+A sensitive word inside a **string literal** - a `LIKE '%secret%'` pattern, a JSON key `->>'token'` - is data, not a column reference. On PostgreSQL the check runs on literal-masked text, and the plan layer (Layer 1b) then has to vouch: a query that passed only because a name sat inside a literal runs only when its plan was obtained and cleared every check, so a masker fooled by a quote trick (`standard_conforming_strings` off, an `E''` string) can never be the only gate - if planning fails, the raw-text refusal stands. On MySQL, MariaDB and SQLite the match stays on raw text with no masking, because a quote's meaning there depends on server modes (`NO_BACKSLASH_ESCAPES`, `ANSI_QUOTES`) or a dotted single-quoted name is an identifier (`t.'col'`).
 
 If one of your own columns merely looks sensitive (an `oauth_applications.secret`, say), exempt it by name:
 
@@ -105,13 +135,11 @@ If one of your own columns merely looks sensitive (an `oauth_applications.secret
 config.query_allowed_columns = %w[secret]
 ```
 
-Results are redacted as well: a returned column comes back as `[FILTERED]` when
-its name is in `config.query_redacted_columns`, contains `password`, `secret` or
-`token`, or ends in `key`, `digest` or `hash`. `SHOW`, `DESCRIBE` and `EXPLAIN`
-output is not redacted.
+Results are redacted as well: a returned column comes back as `[FILTERED]` when the sensitivity rule flags its **output name**, and on PostgreSQL when its origin is a sensitive base column - either by **provenance** (`PG::Result#ftable` / `#ftablecol`, mapped to the base column) or by the **plan's top-node `Output`**, whose i-th expression is result column i. The plan path catches a view (or inlined CTE/subquery/join) that renamed a sensitive column to a harmless name: `CREATE VIEW user_tokens AS SELECT id, api_token AS t FROM users; SELECT t FROM user_tokens` returns `t` as `[FILTERED]`. `SHOW`, `DESCRIBE` and `EXPLAIN` output skips column-name redaction; the one exception is `SHOW CREATE TABLE` / `SHOW CREATE VIEW`, whose definition text is run through the shared secret redaction so a credential embedded in it is filtered.
 
 The exemption covers the results too: an allowed name comes back unredacted. A
-column declared with `encrypts` stays `[FILTERED]` either way.
+column declared with `encrypts` stays `[FILTERED]` either way - an encrypted-at-rest
+attribute is never meant to be read back raw.
 
 ### Environment guard
 
@@ -177,7 +205,43 @@ root = File.realpath(Rails.root.to_s)
 raise unless real_path == root || real_path.start_with?(root + File::SEPARATOR)
 ```
 
-The VFS (`rails-ai-context://views/{path}`) applies the same protection for view template reads.
+A path may also resolve into a directory the app links in from its own git repository, as
+described under "Links in and out of the app" below. The VFS
+(`rails-ai-context://views/{path}`) applies the same protection for view template reads.
+
+### Links in and out of the app
+
+A symlink inside the app is followed when it leads into the app root, or into the engine its
+`test/dummy` runs in, and a directory link is also followed when it leads anywhere inside the
+git work tree that holds the app. A monorepo's shared package linked into `packs/` or
+`app/javascript/controllers` is read as the app's own, under the path the app gives it
+(`packs/billing/app/models/invoice.rb`). A file reached through such a directory is read only
+when its real path stays inside the app or inside that directory. Outside a git repository
+nothing marks where the project ends, so only links that stay inside the app root are
+followed. A link to anywhere else, a home directory included, is not followed: the file is
+neither listed nor read. A link that resolves nowhere is not listed either.
+
+The walks over app code follow a linked-in directory where Rails does: the trees Zeitwerk
+autoloads (models, controllers, jobs, mailers, channels, helpers, components, concerns,
+policies and the rest of `app/`, packs and in-repo engines included), the view resolver's
+templates and layouts, and the JavaScript roots a bundler reads. A file Rails finds with a
+glob of its own is found the way that glob finds it, entering no linked directory below where
+it starts: initializers, locale and environment files, migrations, seeds, rake tasks, test
+files and mailer previews. Among those, a linked file is read only when it stays inside the
+app.
+
+A tool handed a path that leads out of the app refuses it, and so does a tool that resolves a
+name to one file - a log, a partial, a concern - when that file leads out; see "How a refusal
+is reported" below. A tool that answers from what the walks found, such as
+`rails_get_stimulus`, never lists a file a link carries out, and asked for that controller by
+name answers that it is not there. A path into a linked-in directory is accepted wherever a
+path is (`packs/billing/app/models/invoice.rb`), and the sensitive patterns are matched
+against the file's name inside that directory as well as the app's. `rails_search_code`
+searches the linked-in directories too.
+
+Booted, a class Rails loaded through a link out of the app is still described from what
+reflection answers, such as a job's queue name; only its file goes unread.
+`rails_security_scan` hands the app to Brakeman, which reads it by its own rules.
 
 ### Frontend roots outside the app
 
@@ -215,8 +279,18 @@ and contains the app root.
 ### How a refusal is reported
 
 A path refused on policy - outside the app, a traversal, a sensitive file - comes back as an
-error result: `isError: true` over MCP, exit 1 from the CLI. A path that is simply not there
-is an ordinary answer and exits 0, so a script can tell the two apart.
+error result: `isError: true` over MCP, exit 1 from the CLI, and the text starts with
+`Path not allowed: <path>`, followed by `(sensitive file)` when the name is the reason. A
+path that is simply not there is an ordinary answer and exits 0, so a script can tell the two
+apart. `rails_validate`, which answers for several files at once, says `Path not allowed` on
+the refused file's own line; a file it cannot validate, refused or missing, fails the
+validation, so that answer is an error result either way.
+
+The same holds for a name a tool turns into a file: a log (`rails_read_logs file:`), a partial
+(`rails_get_partial_interface partial:`) or a concern (`rails_get_concern name:`) whose file
+links out of the app is refused, not reported missing. A list of what a tool can read, such
+as the available logs or partials, leaves out every entry it would refuse. `rails_diagnose` still diagnoses the error it is given when the `file:` it is
+pointed at is refused, says so, and returns the whole answer as an error result.
 
 ---
 
@@ -233,6 +307,11 @@ Open3.capture3("rg", "--no-heading", "--", pattern, directory)
 
 File type parameters accept only alphanumeric characters.
 
+An argument git would read as an option never reaches it: `rails_review_changes`
+resolves its `ref` to a commit first (`git rev-parse --verify <ref>^{commit}`)
+and hands git that commit's SHA. A ref that starts with a dash is refused, so
+`--output=<path>` cannot make `git diff` write a file.
+
 ---
 
 ## Regex injection prevention
@@ -268,8 +347,9 @@ Everything that leaves your app through this gem - log lines, query rows, enviro
 What gets redacted:
 
 - Passwords, tokens, secrets and API keys, wherever they are named
+- The same in the app's own source a tool or resource shows: a method body, a template, a test file, a scan's code line, a change's diff (where a file on `sensitive_patterns` shows none of its lines)
 - Credentials embedded in URIs (`redis://user:pass@host`)
-- Email addresses in log lines
+- Email addresses in log lines, in any script (`jürgen@example.com`, `anna@münchen.de`)
 - Values assigned to secret-named settings in initializers
 
 ### Markers
@@ -316,13 +396,17 @@ The `rails_migration_advisor` tool validates input:
 
 ## MCP HTTP transport
 
-When using HTTP transport (Rack middleware or McpController):
+No HTTP entry point authenticates a client: every tool answers whoever reaches the endpoint.
+
+**Inside the app** - the mounted engine and `auto_mount` - the endpoint is on your app's own web server, so it is as reachable as the app is. In every environment but development and test - production, and a staging app the network reaches the same way - both refuse every request with a 403 and a JSON-RPC error that says how to opt in, and log the refusal once. `config.allow_http_in_production = true` lets them answer there. Set it only with the endpoint behind your app's authentication, such as a routes constraint around the mount. `auto_mount` answers before routing, so nothing in the app can guard it, and doctor's "MCP HTTP endpoint" check fails that pair. With the option on and the engine, it warns.
+
+Both answer the hosts the app's `config.hosts` allows, judged by Rails' own HostAuthorization with its `host_authorization` exclusions, as every other route of the app is: `myapp.localhost` and any IP address in development, the app's own names in production, every host when `config.hosts` is empty. A host it does not allow, such as a DNS rebinding attacker's domain, gets 403 "Forbidden: Invalid Host header", and a browser's request from another origin gets 403 "Forbidden: Invalid Origin header". The MCP SDK's own check, which answers only `127.0.0.1`, `::1` and `localhost`, is off for these two.
+
+**The standalone server** - `rails-ai-context serve --transport http` and `rails ai:serve_http` - is its own process and binds `127.0.0.1` by default. `http_bind` can open it to the network, still with no authentication. The MCP SDK answers only requests whose `Host` header is `127.0.0.1`, `::1` or `localhost`, which stops a DNS rebinding attack from a browser but not a client that sends `Host: localhost` itself; a client that addresses the machine by IP or name gets 403 "Invalid Host header". So a non-loopback bind suits a container whose port is published to the host, where the client still connects to `localhost`. The server says so on stderr when it starts. On an MCP SDK too old to check the `Host` header, every tool answers whoever reaches the port.
 
-- **Default bind**: `127.0.0.1` (localhost only - not exposed to network)
-- **`auto_mount` is `false` by default** - must be explicitly enabled
-- **Doctor checks** fail if `auto_mount` is true in production, and report it as enabled elsewhere
+`auto_mount` is `false` by default, and the engine exists only where you mount it. Mount it guarded, `if defined?(RailsAiContext::Engine)`, so the routes file still loads where the gem is not installed.
 
-The McpController uses thread-safe transport initialization with mutex synchronization.
+The engine builds one transport per process, under a mutex, outside the controller class, and the app's code reloader never replaces that class, so a session lasts across edits in development.
 
 ---
 

data/docs/SETUP.md

@@ -18,6 +18,7 @@
 - [GitHub Copilot](#github-copilot)
 - [OpenCode](#opencode)
 - [Codex CLI](#codex-cli)
+- [A folder of apps](#a-folder-of-apps)
 - [Verify MCP is connected](#verify-mcp-is-connected)
 - [HTTP Transport](#http-transport-alternative)
 - [Regenerating context files](#regenerating-context-files)
@@ -55,10 +56,10 @@ rails generate rails_ai_context:install  # Select "Claude Code"
 This creates:
 - `.mcp.json` - MCP auto-discovery config (auto-detected on project open)
 - `CLAUDE.md` - Root context file
-- `.claude/rules/rails-schema.md` - Schema rules (loaded when editing the schema dump or `db/migrate/` files)
+- `.claude/rules/rails-schema.md` - Schema rules (loaded when editing a schema dump or a migration of any of the app's databases)
 - `.claude/rules/rails-models.md` - Model rules (loaded when editing `app/models/`)
 - `.claude/rules/rails-context.md` - General context rules (always loaded)
-- `.claude/rules/rails-mcp-tools.md` - Tool reference (always loaded)
+- `.claude/rules/rails-mcp-tools.md` - Tool reference: detail levels and the table of every tool (always loaded; the protocol, workflows and rules are in CLAUDE.md, so they are not loaded twice, and here only when `generate_root_files` is off)
 - `.claude/rules/rails-components.md` - Component rules (loaded when editing `app/components/` or `app/views/components/`, written only when the app has view components)
 
 Keeping your own `CLAUDE.md`? Add `--mcp-only` and only `.mcp.json` is
@@ -82,6 +83,8 @@ If you need to configure manually, create `.mcp.json`:
 
 This is what the generator writes for an in-Gemfile install. A standalone install has no `bundle exec`: the command is `rails-ai-context` and the args are `["serve"]`. The same goes for the other tools below.
 
+On Windows the command is `cmd` and `"/c"` goes ahead of the args (`["/c", "bundle", "exec", "rails-ai-context", "serve"]`): a gem's executables there are batch files, which a client that starts its server without a shell does not run. The generator writes that form on Windows, and `doctor` names an entry written for the other platform; see [GUIDE.md](GUIDE.md#mcp-server-setup) for teams on both.
+
 ### Split rules with `paths:` frontmatter
 
 Claude Code loads `.claude/rules/` files conditionally based on YAML frontmatter:
@@ -155,7 +158,7 @@ This creates:
 - `.github/instructions/rails-models.instructions.md` - Model rules
 - `.github/instructions/rails-controllers.instructions.md` - Controller rules
 - `.github/instructions/rails-context.instructions.md` - Context rules
-- `.github/instructions/rails-mcp-tools.instructions.md` - Tool reference
+- `.github/instructions/rails-mcp-tools.instructions.md` - Tool reference: detail levels and the table of every tool (the protocol and workflows are in copilot-instructions.md, and here only when `generate_root_files` is off)
 
 ### Manual MCP config
 
@@ -256,7 +259,20 @@ Codex CLI `env_clear()`s the process before spawning MCP servers. Without the en
 rails ai:doctor  # Includes check_codex_env_staleness
 ```
 
-If you change Ruby versions, re-run the install generator to update the env snapshot.
+doctor fails a snapshot whose `PATH` no longer reaches the server's command (the Ruby it names was upgraded or removed; rbenv and asdf save a `PATH` and nothing else), and warns about a saved `GEM_HOME` that is gone, or a directory on a saved `GEM_PATH` that is gone and that your shell's `GEM_PATH` no longer names (RubyGems passes over a missing one, so one the shell still names is no change of Ruby). If you change Ruby versions, re-run the install generator (`rails-ai-context init` for a standalone install, in the folder of apps for a workspace's config) to update the env snapshot.
+
+---
+
+## A folder of apps
+
+When your AI tool opens a folder that holds several apps (`work/shop`, `work/admin`), run `rails-ai-context init` in that folder. Each AI tool reads its MCP config from the folder it opened, so the folder's configs get one server per app, and each app keeps its own `.rails-ai-context.yml` and context files:
+
+| AI tool | Entry for `work/shop` |
+|---------|-----------------------|
+| Claude Code, Codex CLI, OpenCode | `rails-ai-context serve --app-path shop`, with `RAILS_AI_CONTEXT_SERVER_NAME=shop-rails-ai-context` |
+| Cursor, GitHub Copilot (VS Code) | the same, with `--app-path ${workspaceFolder}/shop` |
+
+Claude Code, Codex and OpenCode start a server in the folder they were launched in, so start them in `work/`. Cursor and VS Code expand `${workspaceFolder}` to the folder their config sits in. An in-Gemfile app's entry runs `bundle exec` with `BUNDLE_GEMFILE` naming the Gemfile that app's bundle reads (its own, or a monorepo's shared one), spelled the same way. `RAILS_AI_CONTEXT_SERVER_NAME` makes each server announce its app first: VS Code names every tool after that name and keeps 13 characters of it. The full shape is in the [CLI reference](CLI.md#init-standalone-only), and [ADR-0005](adr/0005-workspace-mcp-entries.md) records why.
 
 ---
 
@@ -266,10 +282,16 @@ Instead of stdio, you can mount the MCP server inside your Rails app:
 
 ```ruby
 # config/routes.rb
-mount RailsAiContext::Engine, at: "/mcp"
+mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
 ```
 
-Each connected MCP client that opens the server-push channel (a long-lived SSE `GET /mcp`) holds one server thread for the life of the connection. With Puma's default small thread pool, a handful of connected clients can exhaust it - fine for development, but raise the thread count (or prefer the standalone `rails-ai-context serve --transport http` process) if several clients or other traffic share the app.
+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.
+
+The mounted engine answers the server-push channel (a long-lived SSE `GET /mcp`) with 405, which the MCP spec allows a server that sends no server-initiated messages: live reload, the one thing that sends them, runs only in the standalone `rails-ai-context serve --transport http` process. Clients carry on over POST, a connected client holds a server thread only while one of its requests runs, and `rails server` stops without waiting for clients to disconnect.
+
+The engine runs each call on the thread Rails serves the request on and sends the answer whole, so calls keep being answered while the app reloads code after an edit. What a tool sends during a call reaches the client with the answer: 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 with a message saying why. stdio and the standalone HTTP server (`rails-ai-context serve --transport http`) deliver both as they are sent. For the same reason the engine answers `subscriptions/listen`, whose notification stream it cannot keep open, as a method it does not have.
+
+With a migration pending in development, Rails answers every request to the app with its pending-migration page, and the mounted engine is one of those routes: it sits behind the app's whole middleware stack, `ActiveRecord::Migration::CheckPending` included, and cannot skip it without also skipping the cookies and session an authentication constraint around the mount needs. `auto_mount` answers ahead of that check, so its tools, which report the pending migration, keep working; so do stdio and the standalone server.
 
 Then point your AI tool's MCP config to the HTTP endpoint instead of a command:
 
@@ -285,6 +307,8 @@ Then point your AI tool's MCP config to the HTTP endpoint instead of a command:
 
 Benefits: inherits Rails routing, authentication, and middleware stack. No separate process needed.
 
+Running the install again keeps an entry like this one, under the gem's own name, in place of the command entry it would write, and says so.
+
 ---
 
 ## Verify MCP is connected

data/docs/STANDALONE.md

@@ -27,13 +27,15 @@ Interactive setup asks:
 1. Which AI tools? (Claude, Cursor, Copilot, OpenCode, Codex, or all; an empty answer selects all five)
 2. What should it write? (MCP config + context files, context files only for CLI mode, or MCP config only)
 
-On a re-run that drops a tool, it also asks whether to remove that tool's files. Unlike the install generator, `init` has no pre-commit hook prompt and no `--defaults` flag. The steps are listed in [What the install generator does](GUIDE.md#what-the-install-generator-does).
+On a re-run it shows the tools selected last time. A re-run that drops a tool also asks whether to remove that tool's files, and one that switches to CLI mode whether to take the gem's entries out of the MCP configs, since CLI mode starts no MCP server. Every question comes before the app boots and anything is written; an MCP-only setup does not boot the app at all. Unlike the install generator, `init` has no pre-commit hook prompt and no `--defaults` flag. The steps are listed in [What the install generator does](GUIDE.md#what-the-install-generator-does).
 
 Creates:
 - `.rails-ai-context.yml` - YAML configuration
 - MCP config files for selected AI tools
 - Context files for selected AI tools
 
+Run it from a subdirectory and it sets up the app above. Run it in a folder that holds several apps - the folder you open your editor at - and it sets them all up at once: each app gets its own `.rails-ai-context.yml` and context files, and the folder's MCP configs get one server per app. See [`init`](CLI.md#init-standalone-only) in the CLI reference.
+
 It does not create `config/initializers/rails_ai_context.rb`.
 
 ## Usage
@@ -49,11 +51,14 @@ rails-ai-context watch              # Auto-regenerate on changes
 rails-ai-context version            # Show version
 ```
 
+`watch` needs the `listen` gem, and `serve`'s live reload uses it when it is there. Both use the app's when its bundle locks one, and otherwise one installed beside this gem: `gem install listen`, no Gemfile change. Without it, `serve` still answers from the current files: each tool call checks them first.
+
 ## How standalone mode works
 
-1. **Loads only its boot shim** before the app - the binary requires the two files it needs to boot Rails, then `config/environment.rb`, and requires the gem itself only after the boot returns
+1. **Loads only its boot shim** before the app - the binary requires the two files it needs to boot Rails, then `config/environment.rb`, and requires the gem itself only after the boot returns. Nothing it loads first is a gem an app pins: it reads the Gemfile and `config/boot.rb` with Ruby's own Ripper, not the prism gem, and loads json only once the app's bundle is set up
 2. **Restores `$LOAD_PATH`** entries that `Bundler.setup` strips (since the gem isn't in the Gemfile). The gem's own dependencies come off the load path for the duration of the boot, so every gem the app locks resolves to the app's pin, and go back behind it afterwards
 3. **YAML config** - uses `.rails-ai-context.yml` instead of a Ruby initializer
+4. **Steps aside for the app's own copy** - in an app whose bundle carries its own rails-ai-context (another installed version, or a `path:` copy), a command that boots the app runs through that copy, as `bundle exec rails-ai-context` would, and says so on stderr. That is the copy the app's MCP configs start, and two copies in one process would each load half the gem. The bundle is the one `BUNDLE_GEMFILE` names when you set it (a dual boot's `Gemfile.next`), and a command typed in a subdirectory runs from the app root it found. `init` asks its questions itself and has that copy write only the context files; an MCP-only setup, chosen with `--mcp-only` or at the prompt, runs nothing of the app's. So does `--no-boot`: bundle exec would evaluate the app's Gemfile and start whatever copy the app names, which on a repo just cloned is code nobody has read. A bundle not installed yet (`bundle check` fails) is left alone too: its boot fails, and the static tier answers. A copy installed only under a vendored bundle path or from git is not seen from outside the bundle, so there the installed copy runs
 
 This means you get the same 45 tools, same MCP server, same context generation - without touching the project's Gemfile.
 
@@ -94,6 +99,8 @@ skip_tools:
   - rails_security_scan
 ```
 
+`init`, `rails ai:context` and the install generator own three keys of this file - `ai_tools`, `tool_mode` and `context_files` - and rewrite one only when its value changes, where it stands. Your comments and every other key stay as you wrote them.
+
 ### YAML limitations
 
 One config option is Ruby-only and can't be set via YAML:
@@ -165,7 +172,7 @@ ruby -v                       # Right Ruby version?
 
 The file is read from the app root, once, at boot. Check:
 
-1. You are in the app root, or passed `--app-path`.
+1. You are inside the app, or passed `--app-path`. A command run from a subdirectory reads the config of the app root it walks up to, and names it on stderr.
 2. The key is one the gem knows. An unknown key warns on stderr and is ignored; `custom_tools` is initializer-only.
 3. The file is readable and parses. A directory at that path, an unreadable file or broken YAML warns on stderr and keeps the defaults.