woods 2.0.0.beta4 → 2.0.1

data/docs/CONFIGURATION_REFERENCE.md

@@ -210,7 +210,7 @@ config.vector_store_options = {
 
 Woods uses an HNSW index over pgvector's `vector` representation, which supports
 **1–2,000 dimensions** ([pgvector's HNSW limits](https://github.com/pgvector/pgvector#hnsw)).
-Unreleased after `2.0.0.beta3`: the adapter rejects wider dimensions before any
+Included in Woods `2.0.0`: the adapter rejects wider dimensions before any
 SQL, and `woods:pgvector` rejects invalid widths before writing a migration.
 There is no automatic vector truncation or half-precision conversion.
 
@@ -282,7 +282,7 @@ in the promoted dump; the index MCP server loads that snapshot at startup or
 reload. Incremental embedding publishes changes to paths, dependencies, and
 other unit metadata even when unchanged source needs no new embedding. A run
 with no content or metadata changes keeps the existing dump and retention
-window. Unreleased after `2.0.0.beta3`: a full `Indexer#index_all` run replaces
+window. Included in Woods `2.0.0`: a full `Indexer#index_all` run replaces
 the published corpus even when a custom caller reuses in-memory vector and
 metadata stores. Deleted units, including metadata-only records, are removed;
 an empty full rebuild publishes an empty dump. Failed embedding leaves the
@@ -291,6 +291,13 @@ unchanged. This is a reasonable default for hosts that don't bundle `sqlite3`.
 
 ## Retrieval cache options
 
+The 2.0.1 maintenance patch scopes retrieval contexts to one retriever instance.
+Reload retires only that instance's namespace, including results still in flight;
+already-running requests may finish against the previous corpus. Restarting starts
+a fresh context namespace. Retired entries expire under their configured TTL or
+backend eviction; disabling both can retain unused entries indefinitely. Embedding
+caches remain separate and are not cleared by context invalidation.
+
 The optional cache wraps both embedding-provider calls and assembled retrieval
 contexts. It is disabled by default and is separate from the Index Server's
 tool-result `_meta` cache hint.
@@ -451,7 +458,7 @@ A malformed record invalidates the entire snapshot, rather than exposing partial
 history. Legacy bare identifier keys, omitted/null unit collections, and optional per-unit hash
 fields remain supported; timestamp strings are not restricted to a new format.
 Unit history limits count matching unit records, not the most recent snapshots
-searched (JSON fallback correction unreleased after `2.0.0.beta3`). A unit
+searched (JSON fallback correction included in Woods `2.0.0`). A unit
 missing from newer snapshots can still have retained history.
 Snapshot lists and unit history omit unusable files; direct lookup returns no
 snapshot, and a diff with an unavailable snapshot returns empty added, modified,
@@ -682,7 +689,7 @@ deployment guide including defense layers.
 | `console_mcp_enabled` | Boolean | `false` | Master switch. When `false`, stdio exits and the mounted Console middleware passes requests through to Rails. |
 | `console_mcp_http_enabled` | Boolean | `true` | HTTP transport switch; effective only while the master switch is on. Set `false` for stdio-only use without HTTP token validation or an active HTTP endpoint. Read at request time. |
 | `console_mcp_token` | String | `ENV['WOODS_CONSOLE_MCP_TOKEN']` or `nil` | Bearer token required on every enabled Console HTTP request. With both Console flags enabled, production boot raises on a missing token; other environments warn and requests fail closed with 401. A configured token shorter than 32 characters raises at boot while HTTP is enabled. Explicit stdio-only configurations skip HTTP token validation. Generate with `SecureRandom.hex(32)`. |
-| `console_mcp_allowed_origins` | Array\<String\> | `%w[http://localhost http://127.0.0.1 http://[::1]]` | `OriginGuard` allowlist. Port is stripped before comparison, so `http://localhost` matches any localhost port. Override for tunneled / internal-dashboard access. |
+| `console_mcp_allowed_origins` | Array\<String\> | `%w[http://localhost http://127.0.0.1 http://[::1]]` | `OriginGuard` allowlist shared with SDK dispatch. Portless entries permit same-authority requests; cross-origin ports must be listed explicitly. Default HTTP(S) ports normalize to their omitted form. Invalid entries fail at boot. |
 | `console_mcp_path` | String | `/mcp/console` | URL path the Rack middleware responds on. |
 | `console_embedded_read_tools` | Boolean | `false` | Register `console_sql` and `console_query` in supported stdio and Rack modes. |
 | `console_blocked_tables` | Array\<String\> | `Woods::DEFAULT_CONSOLE_BLOCKED_TABLES` | TableGate denylist (case-insensitive). Bare names match every schema; qualified names (`schema.table`) match exactly. |
@@ -704,7 +711,7 @@ These variables are read by the gem and its MCP servers at runtime. They complem
 |----------|---------|---------|
 | `WOODS_RETRIEVAL_MODE` | `semantic` | Explicit packaged MCP retrieval mode: `semantic` or `lexical`. Lexical reads extraction unit JSON without provider autodetection, credentials or vector artifacts. |
 | `WOODS_DIR` | unset | MCP extraction-index path, after a positional argument and before `WOODS_OUTPUT`. See precedence below. |
-| `WOODS_OUTPUT` | unset | MCP index-path fallback when neither a positional path nor `WOODS_DIR` is set; unreleased after `2.0.0.beta3`. |
+| `WOODS_OUTPUT` | unset | MCP index-path fallback when neither a positional path nor `WOODS_DIR` is set; included in Woods `2.0.0`. |
 | `WOODS_REQUIRE_INDEX` | unset | Set to `"1"` to fail closed: the server refuses to boot (raises `MissingArtifact`) unless a real index (`woods.json`) is present. By default an extract-only host boots in pattern/structural mode without it. Explicit lexical mode requires a valid published extraction index, not `woods.json`. |
 | `WOODS_ALLOW_AUTODETECT` | unset | **Deprecated no-op.** Auto-detect is now the default; accepted for backward compatibility only. |
 | `WOODS_SEARCH_MAX_SCAN` | `500` | Cap on unit files loaded during a phase-2 (metadata/source_code) `search`. Hitting the cap sets `partial: true` in the response. |
@@ -720,7 +727,7 @@ These variables are read by the gem and its MCP servers at runtime. They complem
 | `WOODS_QDRANT_URL`, `WOODS_QDRANT_COLLECTION`, `WOODS_QDRANT_API_KEY` | n/a | Override/require Qdrant connection settings when a pgvector/Qdrant-backed index is served outside its host application (no `Woods.configuration` available). |
 | `WOODS_PG_URL` | n/a | Required when a pgvector-backed index is served outside its host application. |
 
-**MCP index path precedence (unreleased after `2.0.0.beta3`):** positional
+**MCP index path precedence (included in Woods `2.0.0`):** positional
 argument → `WOODS_DIR` → `WOODS_OUTPUT` → current directory for `woods-mcp`
 and `woods-mcp-http`. `woods-mcp-start` still requires one of the first three;
 it never silently selects the current directory. An explicitly empty
@@ -771,10 +778,24 @@ existing index before deciding another extraction is needed.
 | `WOODS_WATCH_CATCH_UP` | `1` (enabled) | Set to `"0"` to skip generation-watermark catch-up on daemon start. |
 | `WOODS_WATCH_TRUST_FOREIGN_HOST` | unset (disabled) | Set to `"1"` in each task/MCP reader to trust a foreign daemon's heartbeat for up to 15 minutes, without a local pid check. See [cross-host liveness](WATCH_DAEMON.md#cross-host-liveness) for clock bounds, degraded coverage, and startup limitations. |
 
+### Managed watcher startup
+
+**Included in Woods `2.0.0`.** `woods-watch` wraps the raw task for native
+Foreman/Puma lifecycle management. `--root PATH` selects the application working
+directory; `--boot-timeout SECONDS` defaults to `300` and bounds boot/handshake,
+not extraction. Explicit child argv follows `--`. Output-directory precedence
+remains `WOODS_OUTPUT`, then `Woods.configuration.output_dir`.
+
+Managed mode requires `WOODS_WATCH_IDLE_TIMEOUT` to be unset, preserves one owner,
+and never takes over a conflicting daemon. The optional Puma adapter only starts
+in its finalized development environment. See [startup and installation](WATCH_DAEMON.md#managed-development-startup)
+for the generator's explicit modes, portable receipt, update/removal, and the
+separate supervision status. Raw task settings above remain compatible.
+
 ### Opt-in plugin refresh hooks
 
 These settings control the plugin shell worker. Check installed
-`woods:hook_refresh` support first; the task is unreleased after 2.0.0.beta2.
+`woods:hook_refresh` support first; the task is included in Woods `2.0.0`.
 See [hook coverage and retry](WATCH_DAEMON.md#hooks-for-agent-sessions) and
 [optional context limits](WATCH_DAEMON.md#optional-bounded-context-hints).
 
@@ -807,26 +828,23 @@ tasks for manual refreshes; hook transport is not a general shell execution API.
 | `GITHUB_BASE_REF` | unset (GitHub Actions) | Build the diff range `origin/<ref>...HEAD` for `woods:incremental`; an unfetched ref makes the range unresolvable, same exit behavior. |
 | `RAILS_ENV` | `development` | Rails environment the rake tasks boot in. |
 | `WOODS_PROFILE` | unset | Set to `"1"` to log disjoint `[Woods] [profile] <phase> in N.NNs` durations, including git enrichment, reconciliation, payload sync, pointer publication (`publish`) and retention (`payload prune`). Separate `[profile total]` lines report whole extraction wall time, including unprofiled setup and failed runs; never add these totals to phase durations. Excludes process/Rails boot before extraction. Off by default. |
-| `WOODS_GIT_DIR` | unset | Absolute path to the canonical git directory. Wins over the repository Woods would otherwise find, at all three of its git call sites: per-unit `commit_count`/`change_frequency` (enrichment), `manifest.json`'s `git_branch`/`git_sha` (provenance), and the `woods:incremental` diff range. All three build their command line with `Woods::GitCommand.argv`. |
+| `WOODS_GIT_DIR` | unset | Absolute path passed directly to Git's `--git-dir`, selecting that directory's `HEAD`. For a linked worktree use its `worktrees/<id>` directory inside the complete shared Git layout. Wins over the repository Woods would otherwise find, at all three of its git call sites: per-unit `commit_count`/`change_frequency` (enrichment), `manifest.json`'s `git_branch`/`git_sha` (provenance), and the `woods:incremental` diff range. All three build their command line with `Woods::GitCommand.argv`. |
 | `GIT_BRANCH`, `GIT_SHA` | unset | Provenance for a checkout with no `.git` at all (a source tarball, a Docker `COPY` that excludes it). Ignored when a `.git` is present but unresolvable, so a stale build arg cannot mask a worktree. |
 
-**`GIT_DIR` alone is not enough for a linked git worktree.** Woods runs git as a
-subprocess, so git's own `GIT_DIR` and `GIT_COMMON_DIR` are honored wherever git
-honors them. But pointing `GIT_DIR` at a worktree's *private* git directory only
-moves the failure: that directory reaches the shared object store through a
-relative `commondir` pointer, which still resolves outside a container mount,
-and `GIT_COMMON_DIR` does not override it. `git rev-parse --git-dir` then
-succeeds while no ref resolves.
-
-Woods refuses to enrich in that state rather than writing `commit_count: 0` and
-`change_frequency: "new"` on every unit: the git keys are omitted, provenance is
-`"unknown"`, and one warning names the cause. Point `WOODS_GIT_DIR` at the
-canonical git directory (the one a worktree's `gitdir:` pointer ultimately leads
-to) and mount it:
-
-```bash
-WOODS_GIT_DIR=/canonical-git bundle exec rake woods:extract
-```
+For linked worktrees in containers, preserve access to the complete shared
+Git directory and the worktree-specific HEAD. A same-path mount that resolves
+the existing `.git` pointer needs no override. For a relocated complete layout,
+set `WOODS_GIT_DIR=/mounted-common/worktrees/<id>`, deriving `<id>` from Git's
+worktree metadata rather than the branch name. Selecting `/mounted-common`
+itself selects the primary checkout's HEAD and can produce incorrect history,
+provenance, and incremental paths. See the canonical
+[worktree mount and verification steps](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
+
+Git subprocesses inherit Git's own environment variables, so inspect existing
+`GIT_DIR` and `GIT_COMMON_DIR` settings when resolving layout problems.
+If HEAD cannot be resolved, enrichment omits the Git keys and provenance is
+`"unknown"` for a present but unresolvable `.git`; one warning names the cause.
+After correcting the layout, run a full extraction to refresh retained metadata.
 
 ### Exporters
 
@@ -846,11 +864,10 @@ The `woods-mcp` bootstrapper emits a one-line STDERR banner at startup indicatin
 
 ## Git enrichment history
 
-Current source requires **Git 2.31 or newer** for optional per-unit git
+Woods 2.0 requires **Git 2.31 or newer** for optional per-unit git
 metadata. Extraction still succeeds when git is unavailable or history cannot
 be read completely. Git enrichment is omitted in either case; a failed or
 incomplete streamed history read logs a warning.
-This requirement and the history policy below are unreleased after 2.0.0.beta2.
 
 Per-unit enrichment also requires a non-shallow repository. A shallow checkout
 or a failed repository-depth probe omits enrichment with one warning per

data/docs/CONSOLE_MCP_SETUP.md

@@ -48,7 +48,7 @@ its token, allowed origins and TLS as described in [Option C](#option-c-http-rac
 
 The rake task does two things before starting the MCP server:
 
-1. **Captures stdout before Rails boots.** Rails boot emits OpenTelemetry warnings, gem notices, and other output to stdout. An MCP client cannot parse these as JSON-RPC, they break the protocol. The rake task redirects stdout → stderr immediately, saves the real stdout fd, and restores it after boot completes.
+1. **Captures stdout before Rails boots.** Rails boot emits OpenTelemetry warnings, gem notices, and other output to stdout. An MCP client cannot parse these as JSON-RPC. The rake task saves the protocol output and redirects application stdout to stderr. In the runtime isolation fix (included in Woods `2.0.0`), that redirection remains active throughout the server's lifetime; only the MCP transport writes to the saved protocol pipe. Rails loggers, `puts`, and writes to standard output during queries stay on stderr.
 2. **Calls `Rails.application.eager_load!`** to load all application models. Without eager loading, only the models that happen to be autoloaded before the first query appear in the registry.
 
 ### MCP client configuration
@@ -83,7 +83,7 @@ rake woods:console
   │    ├─ Rails.application.eager_load!
   │    ├─ build model registry from ActiveRecord::Base.descendants
   │    ├─ Server.build_embedded(model_validator:, safe_context:, ...)
-  │    └─ MCP::Server::Transports::StdioTransport.new(server).open
+  │    └─ Woods::Console::StdioTransport.new(server, output: protocol_out).open
   │
   └─ MCP server responds to tool calls via stdin/stdout
 ```
@@ -201,7 +201,7 @@ request. Missing or incorrect tokens receive `401 Unauthorized`.
 The HTTP authentication scheme is ASCII case-insensitive (`Bearer`, `bearer`,
 or `BEARER`); the token remains case-sensitive and must match exactly after one
 space. This applies to both Console HTTP and `woods-mcp-http`. Case-insensitive
-scheme support is unreleased after `2.0.0.beta3`; use the canonical `Bearer`
+scheme support is included in Woods `2.0.0`; use the canonical `Bearer`
 spelling in client configuration for compatibility with earlier releases.
 
 For non-loopback access, `console_mcp_allowed_origins` must include the public
@@ -209,7 +209,10 @@ Rails/MCP host. If a browser-based client sends an `Origin` header from a
 different host, include that exact origin too. This allow-list controls both
 DNS-rebinding Host checks and browser CORS; keep Rails' own `config.hosts`, TLS,
 and proxy rules aligned with it. Server-to-server clients normally omit
-`Origin`, but their request `Host` must still be allowed.
+`Origin`, but a present request `Host` must still be allowed. Supporting security
+revisions deliberately allow configured non-loopback Hosts through the SDK too;
+2.0.0 could refuse them at that inner layer despite the Woods allowlist. This
+widening is limited to the configured authorities and retains bearer auth.
 
 Do not mount `Woods::Console::RackMiddleware` by itself. The Railtie composes
 `OriginGuard`, `BearerAuth`, and the Console middleware in the supported order.
@@ -636,6 +639,9 @@ Redaction is defense-in-depth, prefer not storing plaintext secrets in database
 
 ### `console_redacted_key_values`
 
+See [read policy compatibility](#read-policy-compatibility) for SQL column-list
+restrictions, conservative typed masking, exact key spelling and binary columns.
+
 Column-name redaction falls short when credentials are stored in a **key-value (EAV)** table, e.g. a Stripe Connect `authorizations` row of `{key: "stripe_access_token", value: "sk_live_..."}`. The column holding the secret is called `value`, which is generic: adding `value` to `console_redacted_columns` would over-redact every unrelated row in the table.
 
 `console_redacted_key_values` takes one or more patterns that describe "when a row has `key_column` set to one of these names, redact its `value_column`":
@@ -700,7 +706,7 @@ these controls, in order:
 
 1. `SqlValidator` rejects DML/DDL (`INSERT`/`UPDATE`/`DELETE`/`MERGE`/`DROP`/`TRUNCATE`/`ALTER`/`CREATE`/`REPLACE`), row-lock clauses (`FOR UPDATE`, `FOR SHARE`, `LOCK IN SHARE MODE`), writable CTEs (every `AS (...)` body, not just the first), `UNION`/`INTO`/`COPY`, multi-statement and comment-hidden injections, and most administrative keywords (`DO`, `SET`, `LISTEN`, `NOTIFY`, `CALL`, `LOAD`, `VACUUM`, `PREPARE`, transaction control, `EXPLAIN ANALYZE`) at the string level. Enforces a read-only **function allowlist** (`ALLOWED_FUNCTIONS`), anything not on it is rejected by name, quoted forms (`"pg_terminate_backend"(…)`) included. Only `SELECT`, `WITH…SELECT`, and plain `EXPLAIN` pass.
 2. `TableGate` refuses any SQL, model, or join that touches a `console_blocked_tables` entry.
-3. `SafeContext` wraps every request in a rolled-back transaction with a short statement timeout. **It does NOT cover async side effects**: ActiveJob `perform_later`, ActionMailer `deliver_later`, direct HTTP egress, `Thread.new`-spawned work, `after_rollback` callbacks, and writes through a different shard all execute as live. Treat the Console MCP as an admin-trust boundary, not a sandbox.
+3. `SafeContext` wraps every request in a rolled-back transaction with an adapter-dependent statement timeout. **It does NOT cover async side effects**: ActiveJob `perform_later`, ActionMailer `deliver_later`, direct HTTP egress, `Thread.new`-spawned work, `after_rollback` callbacks, and writes through a different shard all execute as live. Treat the Console MCP as an admin-trust boundary, not a sandbox.
 4. `CredentialScanner` + column/EAV redaction scrub results.
 
 Keep the flag off when the host requires a narrower database capability.
@@ -718,7 +724,7 @@ supported transport (stdio, Docker/SSH launcher, and HTTP).
 | 1 | Blocked tables | `console_blocked_tables` | Tool dispatch, before executor | Reject any tool call that touches a named table (model, table, or sql arg) |
 | 2 | Credential scanner | `console_disabled_scanner_patterns` (`[:all]` to disable entirely) | After executor, before render | Content-shape redaction of credential-shaped strings anywhere in the response tree |
 | 3 | Column + EAV redaction | `console_redacted_columns`, `console_redacted_key_values` | After executor, before Layer 2 | Identity-based redaction by column name and by key/value row shape |
-| 4 | SqlValidator + SafeContext | built-in | Inside executor | SQL deny-list for `console_sql`; transaction-rollback for every request |
+| 4 | SqlValidator + SafeContext | built-in | Inside executor | SQL validation and function allowlist for `console_sql`; transaction rollback for every request |
 
 Layers 0–3 are configured via `Woods.configure`. Layer 4 is always on and has no knobs. Observability hooks, `console.table_gate.rejected` for Layer 1, `console.credential_scan.hits` for Layer 2, emit structured log lines via `Woods::Observability::StructuredLogger` so operators can audit enforcement without scraping MCP wire traffic.
 
@@ -754,13 +760,20 @@ boundary remain necessary.
 
 ### Statement timeout
 
-Each transaction sets a statement timeout before any query runs. The default is **5000ms** (5 seconds). Timeout enforcement is adapter-specific:
+SafeContext attempts a **5000ms** (5-second) timeout. Support depends on the
+adapter and server; an unsupported setting is skipped and logged when a Rails
+logger is available.
 
 | Adapter | Mechanism | Scope |
 |---------|-----------|-------|
-| PostgreSQL | `SET statement_timeout = '5000ms'` | All statement types |
-| MySQL | `SET max_execution_time = 5000` (session scope; the prior value is restored after the transaction) | SELECT only (MySQL limitation) |
-| Other | Best-effort (skipped gracefully) | n/a |
+| PostgreSQL | `SET LOCAL statement_timeout = '5000ms'` | Transaction-local; discarded on rollback |
+| MySQL | `SET max_execution_time = 5000` | SELECT only; previous session value restored in `ensure` |
+| MariaDB | `SET max_statement_time = 5.0` | Seconds; previous session value restored in `ensure` |
+| SQLite / unrecognized family | No supported per-statement timeout | Do not rely on a query time limit |
+
+Rollback remains active when a timeout setting is unsupported. Recognition of a
+MySQL-family adapter alone does not establish that its server supports the
+corresponding timeout variable.
 
 ### SQL validation (tier 4 `console_sql`)
 
@@ -771,7 +784,7 @@ Validation runs **once**, inside the executor, with the dialect of the live adap
 
 - **Allowed prefixes:** `SELECT`, `WITH...SELECT`, and plain `EXPLAIN`. `EXPLAIN ANALYZE` is rejected, it executes the query rather than just planning it (both the whitespace and `EXPLAIN (ANALYZE, …)` option-list spellings).
 - **Rejected prefixes:** `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `DROP`, `ALTER`, `TRUNCATE`, `CREATE`, `GRANT`, `REVOKE`
-- **Rejected anywhere in query:** `UNION`, `INTO`, `COPY`; row-lock clauses (`FOR UPDATE`, `FOR NO KEY UPDATE`, `FOR SHARE`, `FOR KEY SHARE`, `FOR UPDATE NOWAIT`/`SKIP LOCKED`, MySQL `LOCK IN SHARE MODE`) — these take live row locks even inside the rolled-back transaction. The lock check is adapter-aware: `console_sql` validates with the active adapter's dialect, including MySQL double-quoted strings/backtick identifiers and PostgreSQL quoted identifiers/E-strings. Unknown adapters conservatively scan all supported normalizations. Every view is scanned under both MySQL executable-comment (`/*!...*/`) semantics, so `#` comments and version-guarded comments cannot split a clause apart.
+- **Rejected anywhere in query:** `UNION`, `INTO`, `COPY`; row-lock clauses (`FOR UPDATE`, `FOR NO KEY UPDATE`, `FOR SHARE`, `FOR KEY SHARE`, `FOR UPDATE NOWAIT`/`SKIP LOCKED`, MySQL `LOCK IN SHARE MODE`) — these take live row locks even inside the rolled-back transaction. The lock check is adapter-aware: `console_sql` validates with the active adapter's dialect, including MySQL double-quoted strings/backtick identifiers and PostgreSQL quoted identifiers/E-strings. Direct validator calls without a dialect conservatively scan all supported normalizations; packaged `console_sql` refuses unrecognized adapter families. Every view is scanned under both MySQL executable-comment (`/*!...*/`) semantics, so `#` comments and version-guarded comments cannot split a clause apart.
 - **Function allowlist (the authoritative function control):** every function-call-shaped identifier must appear in `ALLOWED_FUNCTIONS`, a conservative set of pure read-only functions (aggregates, window functions, string/number/date/JSON readers) kept portable across MySQL, PostgreSQL, and SQLite. Anything else is rejected by name, quoted forms (`"pg_terminate_backend"(…)`) included. This is an allowlist because a denylist cannot enumerate every side-effecting function (`nextval`, `pg_advisory_lock`, `pg_terminate_backend`, …). A legacy `DANGEROUS_FUNCTIONS` denylist (`pg_sleep`, `lo_import`, `lo_export`, `pg_read_file`, `pg_write_file`, `load_file`, `sleep`, `benchmark`) still runs first as belt-and-suspenders.
 - **Rejected patterns:** multiple statements (semicolons), writable CTEs (every `AS (...)` body is checked, so a writable CTE in any WITH position is refused — `WITH a AS (SELECT 1), b AS (DELETE FROM users RETURNING *) SELECT * FROM b`), a CTE list attached to top-level DML (`WITH a AS (SELECT 1) DELETE FROM users RETURNING *`), comment-hidden injections
 
@@ -799,13 +812,15 @@ to enforce their narrower parameterized scope grammar.
 - **HTTP:** Check that the Rails server is running and listening on the expected port. An unauthenticated `curl http://localhost:3000/mcp/console` should return `401` when the enabled middleware and bearer-auth guard are mounted. A request with the configured bearer token proceeds to MCP protocol handling.
 - **All modes:** Run `bundle exec rake woods:console` directly in a terminal. It should hang (waiting for MCP protocol input) rather than exit immediately. If it exits, check the error output.
 
-### Rails boot noise breaks MCP protocol
+<a id="rails-boot-noise-breaks-mcp-protocol"></a>
+
+### Rails logs break MCP protocol
 
-The rake task redirects stdout to stderr before Rails boots specifically to prevent this. If you see JSON parse errors from the MCP client, check:
+Prefer `bundle exec rake woods:console`: it captures output before the Rails environment boots. Direct `rails runner` invocation can redirect output only after Rails has booted; it cannot recover an already contaminated protocol stream.
 
-1. You are using `bundle exec rake woods:console`, not `rails runner exe/woods-console` directly (the runner path handles this too, but via a different mechanism).
-2. No `puts` or `print` calls run at boot in your initializers before the task can capture stdout.
-3. Try running `bundle exec rake woods:console 2>/dev/null` to isolate, the MCP protocol output goes to stdout, Rails noise goes to stderr.
+The runtime isolation fix is included in Woods `2.0.0`. Earlier builds restore stdout after boot, so a logger that writes there can interleave SQL or application logs with MCP responses. On those builds, configure the Console process's application logger to write to stderr or a file. Discarding stderr does not fix logs written to stdout.
+
+With a build containing the fix, application output remains on stderr during tool calls. If protocol contamination persists, inspect wrapper scripts and output emitted before the rake task starts; reserve stdout for MCP and retain stderr for diagnosis. Do not disable Console redaction or credential scanning to troubleshoot transport logging.
 
 ### Models not visible to `console_status`
 
@@ -900,3 +915,67 @@ These corrections require `2.0.0.beta4` or a reviewed development revision that
 contains them. Confirm that a patched release is available before selecting it.
 On affected versions, disable Console where these policies are required; Index MCP
 can stay enabled because it reads the published code index separately.
+
+
+## Maintenance policy corrections
+
+The 2.0.1 maintenance patch applies authentication and origin policy to each
+Console HTTP mount. Keep the normal Railtie setup: these additional checks do not
+make an unreviewed manual mount the recommended installation path. Configure
+allowed origins before boot and restart after changes; malformed entries fail
+once at boot with the offending entry identified.
+
+Protected collection values are masked as complete cells. EAV key policy checks
+both stored and cast keys, including in predicates and ordering. Raw SQL refuses
+ambiguous protected source identity, protected whole-row projections, positional
+ordering that could expose protected values, and unsupported result types.
+Explicit unaliased scalar columns and the structured tools are the recovery path.
+
+SQL dialect detection follows adapter ancestry before adapter names. PostgreSQL
+subclasses, Mysql2, MariaDB, Trilogy and SQLite use their applicable policies.
+Genuinely unknown families are refused only by raw `console_sql`; this restriction
+does not disable structured Tier-1 tools. Existing tool opt-ins remain unchanged.
+
+PostgreSQL Unicode-escaped identifiers are refused by `console_sql` before
+execution. Use ordinary identifiers or standard quoted identifiers instead;
+structured query tools are unaffected by this syntax restriction.
+
+### Read policy compatibility
+
+These rules describe the security-patch source; verify the installed revision
+and loaded gem path until its release is published.
+
+- **Column alias lists:** when either `console_redacted_columns` or
+  `console_redacted_key_values` is nonempty, `console_sql` refuses relation
+  and CTE column alias lists before execution, including lists on base tables,
+  derived tables, parenthesized `VALUES` sources and table functions. This applies
+  even when the selected names are not protected and independently of function
+  validation. Ordinary relation
+  aliases, CTEs without column lists and allowed scalar functions remain subject
+  to the normal SQL policy. Use explicit, unaliased protected columns or a
+  structured Console tool.
+- **Conservative typed masking:** EAV type lookup matches the final source-table
+  name case-insensitively and includes every matching registered model, even
+  across schemas. Any matching type can cause masking. This deliberately may
+  mask extra values when table names differ only by case or share that final
+  name; qualifying the table does not narrow that type set.
+- **Exact sensitive values:** `sensitive_keys` compares the stored and cast key
+  values with exact case after string conversion. Configure their actual raw or
+  cast spelling. `CredentialIndex` also matches credential substrings with exact
+  case; it does not decode hexadecimal binary output such as PostgreSQL `bytea`.
+  Binary cells have no general text-scanning guarantee: non-UTF-8 data can fail
+  JSON normalization before scanning. Put binary secret columns in
+  `console_redacted_columns` so they are masked before serialization.
+- **Adapter boundary:** raw `console_sql` requires PostgreSQL, MySQL-family
+  (including Mysql2, MariaDB and Trilogy), or SQLite classification. Compatible
+  subclasses are recognized by ancestry. Unknown families receive a validation
+  refusal for raw SQL; structured tools remain available under their normal
+  gates. See [statement timeouts](#statement-timeout) for adapter limits.
+- **SQL functions and select entries:** 2.x enforces a read-only function
+  allowlist; 1.6.x retains a function denylist. For `console_query`, provide one
+  expression per `select` array entry. 2.x refuses comma-combined entries that
+  1.6.4 splits before validation. Execution and typed redaction use the same
+  validated projection on all patched lines.
+- **Association counts:** polymorphic `belongs_to` counts remain unsupported
+  on this maintenance line and fail closed with a generic execution error.
+  The 2.1 functional correction is not included in this backport.

data/docs/DOCKER_SETUP.md

@@ -87,9 +87,24 @@ docker compose exec app bundle exec rake woods:extract_framework
 
 Run the watcher as its own development service or process-manager entry, not as a one-off terminal command. Docker Desktop bind mounts may not deliver reliable native filesystem events; set `WOODS_WATCH_POLL=1` for polling when needed. The watcher updates structural generations automatically, while semantic vectors still require `woods:embed_incremental`.
 
+Use the application's actual Rails task entrypoint. If its root `Rakefile` wraps
+Compose, the container may need `bundle exec rails woods:watch`. Keep the raw
+task under one external restart owner: `restart: unless-stopped` recovers after
+Docker restarts while respecting an intentional stop; `on-failure` covers failed
+process exits but not Docker restart. Leave idle TTL unset for continuous work.
+
+Validate `docker compose config`: explicit YAML anchor keys can replace inherited
+mounts/environment, and short `depends_on` does not establish database readiness.
+Preserve the existing source/bundle mounts and use the application's healthcheck
+convention. With Grove, include the watcher in the applicable shared or isolated
+services list and align source/index mounts to the selected worktree. Follow
+[Docker and Grove verification](AUTOMATIC_MAINTENANCE.md#docker-verify-the-resolved-service)
+instead of copying a generic service that loses required settings.
+
 When host-side tasks or one-off containers read the daemon's shared index,
 `WOODS_WATCH_TRUST_FOREIGN_HOST=1` lets those readers trust its recent heartbeat.
 Set it in each reader process; Docker does not forward host variables by default.
+Ordinary Index MCP reads do not need this trust or the extraction writer lock.
 See [cross-host liveness](WATCH_DAEMON.md#cross-host-liveness) for the 15-minute
 crash-detection bound and single-supervisor requirement.
 

data/docs/EVALUATION.md

@@ -90,8 +90,8 @@ bundle exec ruby -Ilib bench/evaluation/runner.rb
   strategy selection also fail. The baseline format is developer-only and is
   **not** the `EVAL_BASELINE_FILE` aggregate-threshold format.
 
-B-190/B-191 recapture on Ruby 4.0.6 (five warmed pipeline repetitions per query; Ruby 3.3.1
-and 3.4.10 replay the same answers):
+B-190/B-191 baseline, with the #549 output-label refresh captured on Ruby 4.0.6
+(five warmed pipeline repetitions per query):
 
 | Strategy | Queries | Precision@5 | Recall | MRR | Mean actual context tokens |
 |---|---:|---:|---:|---:|---:|
@@ -99,8 +99,14 @@ and 3.4.10 replay the same answers):
 | Vector | 4 | 0.313 | 0.375 | 0.625 | 1,041.2 |
 | Graph | 8 | 0.813 | 0.519 | 1.000 | 1,041.1 |
 | Hybrid | 4 | 0.750 | 0.396 | 1.000 | 1,058.8 |
-| Direct with type filtering | 4 | 0.375 | 0.750 | 0.625 | 551.0 |
-| Within-type vector fallback | 4 | 0.400 | 1.000 | 1.000 | 1,250.8 |
+| Direct with type filtering | 4 | 0.375 | 0.750 | 0.625 | 552.0 |
+| Within-type vector fallback | 4 | 0.400 | 1.000 | 1.000 | 1,251.8 |
+
+The clearer `Retrieval metadata records` heading adds one exact `cl100k_base`
+token to each of the eight direct/fallback contexts. The other 20 contexts,
+retrieved identifiers and order, annotations, and quality metrics are unchanged.
+The refresh reuses captured vectors and the pinned `tiktoken 0.11.0` tokenizer;
+it performs no new model inference.
 
 Precision@5 divides relevant hits by the actual returned slice size (up to five),
 not always by five. Recall divides retrieved relevant units by all annotated

data/docs/EXTRACTOR_REFERENCE.md

@@ -32,6 +32,14 @@ Extractors discover code one of two ways:
 
 Some extractors combine both (e.g., `JobExtractor` scans directories first, then supplements with `ApplicationJob.descendants`).
 
+Discovery is not exhaustive. A standalone module under `app/models` that is
+called through singleton methods is not discovered by the model/PORO paths;
+conventional concerns and app modules included by live models have separate
+concern discovery. This gap is tracked in [#552](https://github.com/lost-in-the/woods/issues/552).
+Separately, dependency scanning does not capture every method-body constant
+reference ([#475](https://github.com/lost-in-the/woods/issues/475)). A missing unit
+or edge is not proof of unused code; cross-check the application source.
+
 ### Identifier naming (source-derived units)
 
 File-based extractors derive an identifier in three steps, first match wins:
@@ -746,11 +754,15 @@ History is limited to commits reachable from `HEAD` in the past 365 days,
 including merged branch history. Unmerged branches, remote refs, and tool
 checkpoint refs do not contribute. Commands run against the application root;
 when `WOODS_GIT_DIR` is set, `HEAD` belongs to that explicitly selected git
-directory, which may differ from a linked worktree's HEAD.
+directory. For a linked worktree, select its `worktrees/<id>` directory within
+the complete shared Git layout; selecting the shared root instead uses the
+primary checkout's HEAD. See the [worktree mount guide](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
 
 After upgrading from a version that included all refs, run a full
 `woods:extract` to replace previously published git metadata. Incremental
-extraction refreshes only the units it rewrites.
+extraction refreshes only the units it rewrites. A commit alone does not
+necessarily trigger the source-file watcher; run full extraction when current
+Git history is required.
 
 | Field | Description |
 |-------|-------------|

data/docs/FAQ.md

@@ -134,7 +134,7 @@ When a model includes a concern, the behavior defined in that concern is part of
 
 ### How do I update the index after code changes?
 
-Use incremental mode, which re-extracts only files that have changed since the last run:
+Use incremental mode to dispatch a selected batch of changed paths:
 
 ```bash
 bundle exec rake woods:incremental
@@ -143,7 +143,12 @@ bundle exec rake woods:incremental
 docker compose exec app bundle exec rake woods:incremental
 ```
 
-Incremental mode is ideal for CI pipelines and local development workflows. It is typically 5-10× faster than a full extraction. Nine unit types, `route`, `middleware`, `engine`, `scheduled_job`, `state_machine`, `factory`, `event`, `database_view`, and `rails_source`, don't map to individual files, so incremental mode re-runs their extractor **wholesale** whenever the relevant trigger path changes (e.g. `config/routes.rb` for routes, `Gemfile.lock` for middleware/engines/rails_source; `rails_source` participates only when `include_framework_sources` is enabled). You never need to run a full extraction just because one of these changed, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for details.
+The default Git range is `HEAD~1`; CI variables, an explicit range, or
+`CHANGED_FILES` can select another batch. Incremental extraction also refreshes
+affected concern consumers and re-runs whole-app extractors when their trigger
+paths change. It can reduce work, but has no universal speedup: Rails boot, graph
+work, and publication still take time. See the [incremental contract](INCREMENTAL_EXTRACTION.md)
+for scope, whole-app triggers, and cases that require a full extraction.
 
 ---
 
@@ -411,7 +416,13 @@ When you run `rake woods:embed`, Woods generates embedding vectors for each extr
 
 ### What is the `codebase_retrieve` tool for?
 
-`codebase_retrieve` is the primary semantic search tool on the Index Server. It accepts a natural-language description of what you're looking for ("find where user email validation happens", "which services send Stripe API calls") and returns the most relevant extracted units as formatted context. It requires embedding configuration, without an embedding provider the tool responds with an error (`isError`, code `:not_configured`) and a remediation hint covering provider setup and the `search` tool for pattern-based matching in the meantime. Token budget is controlled by `config.max_context_tokens` (default: 8000).
+`codebase_retrieve` ranks extracted units for a natural-language query, such as
+"find where user email validation happens". Default semantic mode requires an
+embedding provider and vector store. Explicit lexical mode ranks published
+extraction text without either: set `WOODS_RETRIEVAL_MODE=lexical` in the MCP
+process environment and restart it. There is no automatic fallback between
+modes. See the [retrieval guide](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval)
+for setup, ranking evidence, and the estimated text-budget contract.
 
 ---
 

data/docs/GETTING_STARTED.md

@@ -12,15 +12,15 @@ If an agent will perform the installation, use the safety and handoff checklist
 
 ## 1. Install the gem
 
-Use the [README release table](../README.md) to choose a version, then confirm
-that **exact version is published** on the [RubyGems versions page](https://rubygems.org/gems/woods/versions)
-before editing the Gemfile. A prepared release checkout can update the README
+Choose a version from the [RubyGems versions page](https://rubygems.org/gems/woods/versions)
+and confirm that **exact version is published** before editing the Gemfile.
+A prepared release checkout can update the documentation
 before its gem is published; if the version is absent, choose an available
 version or wait for publication.
 
 If the published 2.x line has only beta or release-candidate versions, use an
-exact pin to the published prerelease, following the README's prerelease
-instructions; `~> 2.0` does not select prereleases. Follow the selected version's
+exact pin to the published prerelease; `~> 2.0` does not select prereleases.
+Follow the selected version's
 tag documentation. The `main` guides may describe features absent from the
 published gem.
 
@@ -148,21 +148,22 @@ Reconnect the MCP server and check `woods_status`. For OpenAI, pgvector, Qdrant,
 
 ### Keep the index current
 
-For automatic maintenance, keep a watcher running beside the Rails development process:
-
-```bash
-bin/rails woods:watch
-```
-
-```text
-# Procfile.dev
-web:   bin/rails server
-woods: bundle exec rake woods:watch
-```
+Enable one watcher through the application's normal development startup. The
+[managed startup guide](WATCH_DAEMON.md#managed-development-startup) covers
+opt-in Puma integration for a simple Rails application, an owned Foreman entry
+for existing Procfile workflows, and external supervision for Docker/Grove.
+The managed launcher and generator are **included in Woods `2.0.0`**;
+check the installed commands before using them. Older packages can run the raw
+`bin/rails woods:watch` task under an external restart-capable supervisor.
 
 On startup it reconciles changes made since the last successful generation. While running it batches file events, reloads Rails code when safe, extracts affected units, and publishes atomically. The Index Server detects the new generation on its next call and reloads automatically. After the initial extraction, ordinary code edits need no manual extraction or MCP restart.
 
-When dependencies, initializers, database configuration, credentials, or schema change, Rails cannot safely reload all captured state. The watcher records a degraded reason and exits with status 75 so the process manager can restart it. Docker bind mounts may require polling; follow [Watch daemon](WATCH_DAEMON.md).
+When dependencies, initializers, database configuration, credentials, or schema
+change, the raw task exits 75 to request a fresh Rails boot. The managed launcher
+handles that restart internally; an external supervisor must handle it for the
+raw task. Do not add the bare task to Foreman. Docker bind mounts may require
+polling. See the [low-interaction workflow](AUTOMATIC_MAINTENANCE.md) for ownership,
+hooks, and the checks that establish automatic maintenance is active.
 
 The watcher maintains the structural index. If semantic retrieval is enabled, also run `bin/rails woods:embed_incremental` to update vectors. Without a resident watcher, run `bin/rails woods:incremental` after changes. Use a full `woods:extract` after major upgrades or when validation reports drift. CI and shared-artifact patterns are covered in [Incremental extraction](INCREMENTAL_EXTRACTION.md).
 

data/docs/INCREMENTAL_EXTRACTION.md

@@ -89,8 +89,13 @@ Recovery choices, in the order they are worth trying:
 3. Run a full `woods:extract` when the range cannot be repaired this run.
 
 The diff itself is rooted at the extracted application (`git -C Rails.root`),
-so it cannot read whatever checkout the process happened to start in — the
-same rooting rule the manifest's git provenance follows.
+independently of the process working directory. An explicit `WOODS_GIT_DIR`
+selects that Git directory's HEAD for both the diff and manifest provenance.
+For a linked worktree, use its worktree-specific directory within the complete
+shared layout; selecting the shared root instead reads the primary checkout's
+HEAD. See [worktree mount verification](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
+Git-only changes may not trigger the source-file watcher; see the
+[watcher limitation](WATCH_DAEMON.md#watcher-backends).
 
 Named, source-defined app modules included by runtime models are tracked as concern units even
 outside `concerns/` directories. Changing their source refreshes their includers,
@@ -100,7 +105,7 @@ to populate these previously missing source mappings.
 
 ## Handled source errors and retry
 
-Unreleased after `2.0.0.beta3`: when an incremental extraction or named refresh
+Included in Woods `2.0.0`: when an incremental extraction or named refresh
 records a handled consumer error (for example malformed locale or schedule
 YAML), it raises `Woods::ExtractionError` before publishing. Empty output from
 that failed consumer does not authorize replacing or deleting its last-good

data/docs/INDEX_LAYOUT.md

@@ -94,8 +94,8 @@ families and `manifest.provenance.mode`; it is not Rails runtime evidence.
 ### Semantic graph validation
 
 `woods:validate` checks raw graph data against the unit indexes and artifacts in
-one pinned published generation. This validation is unreleased after
-`2.0.0.beta2`. It checks the shapes of `nodes`, `edges`, `reverse`, `file_map`,
+one pinned published generation. This validation is included in Woods `2.0.0`.
+It checks the shapes of `nodes`, `edges`, `reverse`, `file_map`,
 `type_index`, and optional `variants`; typed identities must be unique and agree
 with the actual indexed units. Forward sources must exist. Reverse, file, and
 type memberships must match the union of primary and variant contributions.