woods 2.0.0.beta3 → 2.0.0.beta4

data/docs/AGENT_GUIDE.md

@@ -129,18 +129,38 @@ Do not infer completeness from a full page or missing metadata. See the
 
 ## Traverse deliberately
 
-`dependencies` means “what this unit uses.” `dependents` means “what uses this unit.” Both default to bounded breadth-first traversal and accept type or relationship filters.
+`dependencies` shows recorded relationships from this unit; `dependents` shows
+recorded relationships to it. Both default to bounded breadth-first traversal and
+accept type or relationship filters. They are not exhaustive source-reference or
+call graphs: selective scanning can miss arbitrary method-body constant references,
+including generic PORO and library targets. No dependents or test-only dependents
+do not establish absence of production callers. Check source before claiming absence.
+The `graph_coverage` notice makes this scope explicit in supporting responses;
+that metadata is unreleased after `2.0.0.beta3`.
 
 Start at depth 1 or 2. A deeper unfiltered traversal can obscure the direct evidence that matters. Common relationship values include associations (`belongs_to`, `has_many`, `has_one`), code references, renders, redirects, form actions, and navigation links.
 
 Both return at most 50 nodes by default and say so with a `Showing N of M (truncated)`
-line. Narrow with `depth`, `types` and `via` before paging with `limit` and
+line for completed walks. Budget-limited answers in supporting versions instead
+say `Showing N of at least M (total unknown: <budget reason>)`. Narrow with `depth`, `types` and `via` before paging with `limit` and
 `offset`: narrowing answers the question, paging only splits the same answer
 across turns. In a multi-database app each row names the unit's database.
 
+On supporting servers, inspect `structuredContent.data` for traversal nodes,
+`graph_coverage`, exactness, budgets and optional explanation witnesses, regardless
+of the text renderer. This packaged stdio/HTTP payload is unreleased after
+`2.0.0.beta3`; check the actual response and use its text when structured data is
+absent. There is no traversal `format` argument. See the
+[response contract](MCP_SERVERS.md#dependency-graph-coverage).
+
 A traversal can also stop at its independent node or edge budget. Treat
 `partial`/`partial_reason` as incomplete graph evidence even on the final page;
-paging cannot recover nodes the walk never reached. Check the connected schema
+paging cannot recover nodes the walk never reached. Supporting responses include
+`total_is_exact: false` for a cutoff and true for a finished walk, independently of
+pagination. This field is unreleased after `2.0.0.beta3`; on older servers inspect
+`partial` directly. `nodes_total` remains the root-inclusive admitted prefix count,
+not the full reachable total when partial. Even an exact count covers only the
+requested root, depth, filters and published graph generation. Check the connected schema
 before using `max_nodes`/`max_edges`, and follow the
 [budget contract](MCP_SERVERS.md#dependency-traversal-budgets).
 
@@ -149,7 +169,9 @@ recorded source-to-target relationships and a shared shortest witness to each
 row. Report `direct` relationships separately from `transitive` inferred impact.
 Follow `parent`/`edge_id` references; `context: true` ancestors are outside the
 current result page. Unknown labels and ambiguous candidate types stay unknown;
-`typed_path_complete: false` does not establish a uniquely typed path. See the
+`typed_path_complete: false` does not establish a uniquely typed path. True means
+only unambiguous witness types, not complete source coverage. Supporting text
+responses label this `witness types unambiguous` (unreleased after `2.0.0.beta3`). See the
 [explanation contract](MCP_SERVERS.md#traversal-explanations).
 
 Use recorded relationship labels as evidence. Do not infer execution or call

data/docs/AGENT_SETUP.md

@@ -40,7 +40,9 @@ If the worktree contains unrelated changes, preserve them. Do not overwrite an e
 
 Use structural-only setup when the user wants code navigation, runtime Rails structure, dependencies, flows, or blast-radius analysis. Fourteen tools register in the normal packaged launch without an embedding provider.
 
-Discuss semantic retrieval only if the user needs natural-language `codebase_retrieve`. The choice depends on whether they prefer local Ollama or hosted OpenAI and which vector store fits their environment. See [Backend matrix](BACKEND_MATRIX.md).
+If the user wants ranked discovery through `codebase_retrieve`, offer [explicit lexical mode](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval) over the published index without a provider or embeddings. Check that the installed version supports it, set `WOODS_RETRIEVAL_MODE=lexical` in the MCP process environment, restart that server, and verify `woods_status.retriever.mode`. Keep structural-only setup as the default unless this mode is requested.
+
+For semantic matching, discuss local Ollama or hosted OpenAI and the appropriate vector store separately; adding a provider still requires authorization. See [Backend matrix](BACKEND_MATRIX.md).
 
 Do not infer permission to configure Console MCP from a request to “set up Woods” or “set up MCP.” The Index Server reads generated code context; the Console Server can read live data.
 
@@ -130,7 +132,7 @@ Reconnect the client and call `woods_status`. Confirm a current generation and n
 
 ### Managed Claude Code configuration
 
-The development command `woods-agent-config` is unreleased after 2.0.0.beta2.
+`woods-agent-config` is available from Woods `2.0.0.beta3`.
 Check `bundle exec woods-agent-config --help` in the selected application bundle;
 use the manual client configuration below when it is absent. The supported
 client format is Claude Code (tested with 2.1.267).
@@ -188,8 +190,16 @@ receipt for future update/removal. Unrelated servers, hooks, settings,
 instruction text, permissions, and line-ending conventions are retained;
 changing JSON may reformat its whitespace.
 
+Unreleased after `2.0.0.beta3`: apply and recovery coordinate on the actual
+managed file paths, including user configuration and shared instruction files.
+Two application roots sharing those files cannot apply overlapping plans at the
+same time. A competing operation reports a conflict; after it finishes, create a
+fresh preview if the saved plan's snapshots changed. Both applications keep
+their own ownership receipts. Do not delete an active coordination lock.
+
 Writes use atomic replacement per file and a private recovery journal beside
-the receipt. The plan summary names the `.lock` and `.pending` runtime paths;
+the receipt. The plan summary names all adjacent `.woods.lock` files, the
+receipt `.lock`, and the `.pending` journal;
 a lock file may remain after completion. Multiple files are not one atomic
 transaction. An ordinary write failure restores original files when safe; an
 interruption or concurrent edit can retain the journal. Resolve reported
@@ -203,11 +213,11 @@ is changed; reduce the selected configuration before applying.
 
 Use a class known to exist in the application:
 
-1. Call `search` to obtain its exact identifier.
-2. Call `lookup` to confirm source and metadata are present.
+1. Call `search` to obtain its exact identifier and type.
+2. Call `lookup` with that identifier and type to confirm source and metadata are present.
 3. Call `dependents` with depth 1 or 2 to confirm graph edges are queryable.
 
-If `codebase_retrieve` reports that semantic search is disabled, that is expected for structural-only setup. Do not configure credentials merely to remove the message.
+If `codebase_retrieve` reports that semantic search is disabled, that is expected for structural-only setup. Do not configure credentials merely to remove the message. If lexical retrieval was requested, verify its mode with `woods_status` and make one `codebase_retrieve` call against the published index.
 
 ## 8. Offer automatic index maintenance
 
@@ -263,7 +273,7 @@ Verified capabilities:
 - Index Server connected: yes/no
 - woods_status current: yes/no
 - search/lookup/dependents checked: yes/no
-- semantic retrieval: disabled/enabled (provider)
+- retrieval: disabled/lexical/semantic (provider when semantic)
 - Console MCP: disabled/enabled (authorization)
 - automatic structural updates: disabled/enabled (process manager)
 
@@ -274,7 +284,7 @@ Never report a capability as enabled solely because its schema exists in source.
 
 ## Copyable prompt for an installation agent
 
-> Install Woods 2.x in this Rails repository using `docs/AGENT_SETUP.md`. Start with read-only preflight and preserve unrelated changes. Default to the structural Index Server; do not enable embeddings, Console MCP, HTTP transport, secrets, or purge overrides without asking me. Inspect generated files before migrating, run extraction and validation in the app's normal execution environment, configure a project-scoped MCP server in the same filesystem context as the application bundle and index, and verify `woods_status`, `search`, `lookup`, and `dependents`. Finish with the runbook's handoff report.
+> Install Woods 2.x in this Rails repository using https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md. Select a published version and follow that version's tag documentation and supported capabilities. Start with read-only preflight and preserve unrelated changes. Default to the structural Index Server; do not enable embeddings, Console MCP, HTTP transport, secrets, or purge overrides without asking me. Inspect generated files before migrating, run extraction and validation in the app's normal execution environment, configure a project-scoped MCP server in the same filesystem context as the application bundle and index, and verify `woods_status`, `search`, `lookup` with the discovered identifier and type, and `dependents`. Finish with the runbook's handoff report.
 
 ## Related guides
 

data/docs/BACKEND_MATRIX.md

@@ -96,6 +96,11 @@ CREATE INDEX IF NOT EXISTS idx_woods_vectors_embedding_hnsw
   ON woods_vectors USING hnsw (embedding vector_cosine_ops);
 ```
 
+**Dimension limit:** Woods uses `vector_cosine_ops` HNSW, limited to 2,000 dimensions.
+The default 3,072-dimensional `text-embedding-3-large` output needs an explicit
+smaller provider output width or another backend. See the
+[pgvector configuration contract](CONFIGURATION_REFERENCE.md#pgvector-postgresql).
+
 **Performance notes:**
 - HNSW: ~5ms search at 10K vectors, ~20ms at 100K. Memory: ~1.5x vector size.
 - For codebase indexing (~1000-5000 units, potentially 5000-20000 chunks), HNSW is appropriate.

data/docs/CONFIGURATION_REFERENCE.md

@@ -208,6 +208,25 @@ 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
+SQL, and `woods:pgvector` rejects invalid widths before writing a migration.
+There is no automatic vector truncation or half-precision conversion.
+
+The default `text-embedding-3-large` output is 3,072 dimensions. With pgvector,
+explicitly request a supported provider output width, for example:
+
+```ruby
+config.embedding_model = 'text-embedding-3-large'
+config.embedding_options = { dimensions: 1536 }
+```
+
+Keep the provider, `vector_store_options[:dimensions]` (when set), and generated
+migration width equal. Changing a stored width requires a compatible new table
+or an intentional index rebuild; changing the setting does not resize old data.
+Use another backend if you need the full 3,072-dimensional output.
+
 Requires the pgvector extension. Run the generator to create migrations:
 
 ```bash
@@ -263,7 +282,12 @@ 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. This is a reasonable default for hosts that don't bundle `sqlite3`.
+window. Unreleased after `2.0.0.beta3`: 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
+previous promoted dump and checkpoint intact. Incremental purge guards remain
+unchanged. This is a reasonable default for hosts that don't bundle `sqlite3`.
 
 ## Retrieval cache options
 
@@ -335,7 +359,7 @@ The embed run writes `woods.json` + `dumps/<ISO8601>/vectors.bin` + `metadata.ms
 
 Requirements:
 - `output_dir` must be set and readable by both the embed process and the MCP server.
-- The MCP server must know the same `output_dir` (pass via `woods-mcp <DIR>` or set `WOODS_DIR`).
+- The MCP server must know the same `output_dir` (pass via `woods-mcp <DIR>` or set `WOODS_DIR`; see MCP path precedence below).
 
 ## Presets
 
@@ -418,11 +442,26 @@ finding qualifying edges. Run extraction again after changing either setting;
 MCP reads the published report. These findings remain informational, never a
 release or architecture gate.
 
-When the JSON snapshot fallback is in use, malformed JSON, top-level values
-other than objects, and files that cannot be read (including concurrent retention
-removals) are warned about and treated as absent. Snapshot lists and unit history
-omit them; direct lookup returns no snapshot, and a diff with an unavailable
-snapshot returns empty added, modified, and deleted lists.
+When the JSON snapshot fallback is in use, malformed JSON, invalid snapshot
+shapes, and files that cannot be read (including concurrent retention removals)
+are warned about and treated as absent. A snapshot needs a hexadecimal string
+`git_sha` matching its filename; `extracted_at` may be a string, null, or omitted.
+When present and non-null, `units` must be an object whose records are objects.
+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
+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,
+and deleted lists. An empty diff in this case is not proof that nothing changed.
+New captures compare against the latest usable snapshot. Unusable SHA-named files
+still count toward retention and are pruned first when the limit is exceeded;
+reading alone does not delete them. Valid legacy snapshots with null or omitted
+timestamps are retained ahead of corrupt files, then treated as oldest among
+usable snapshots. Direct lookup and diff still reject invalid
+caller-supplied SHA paths with an argument error.
 
 `incremental_blast_radius_depth` is unbounded by default because a unit two hops
 out really can have content that depends on the changed file. An STI grandchild
@@ -473,6 +512,18 @@ config.session_store = Woods::SessionTracer::FileStore.new(
 config.session_exclude_paths = ['/health', '/metrics', '/assets']
 ```
 
+### File session retention
+
+`FileStore` accepts `ttl:` in seconds (default `nil`, expiration disabled),
+`max_sessions:` (default `1000`), and `max_requests_per_session:` (default `1000`).
+TTL expires a file when the store clock reaches its modification time plus the
+TTL. Recording after expiry starts a fresh history; expired events are discarded
+before appending or migrating legacy filenames, under the same store lock.
+When legacy and encoded files coexist, each expires independently before any
+surviving histories are merged. Clearing a session is idempotent for supported
+IDs, including Unicode and punctuation, and removes both filename formats when
+applicable.
+
 ### Redis session index compatibility
 
 `RedisStore` lists and clears both legacy SET indexes and recency ZSET indexes.
@@ -652,7 +703,8 @@ These variables are read by the gem and its MCP servers at runtime. They complem
 | Variable | Default | Purpose |
 |----------|---------|---------|
 | `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` | `Dir.pwd` | Path to the extraction output directory. |
+| `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_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. |
@@ -668,6 +720,20 @@ 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
+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
+`WOODS_DIR` remains an invalid override rather than falling through. Earlier
+versions accept the positional path or `WOODS_DIR`; use an explicit path for
+portable client configuration.
+
+Paths are resolved in the MCP process's working directory and filesystem.
+A published index can have `generation.json` pointing to a payload's
+`manifest.json`; a root `manifest.json` is only the legacy flat layout. If
+startup cannot find a manifest, check the reported directory and point at the
+existing index before deciding another extraction is needed.
+
 ### Rake tasks
 
 | Variable | Default | Purpose |

data/docs/CONSOLE_MCP_SETUP.md

@@ -198,6 +198,12 @@ the Rails server environment. The middleware stack registers automatically via
 the gem's Railtie and requires `Authorization: Bearer <token>` on every Console
 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`
+spelling in client configuration for compatibility with earlier releases.
+
 For non-loopback access, `console_mcp_allowed_origins` must include the public
 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
@@ -760,12 +766,12 @@ Each transaction sets a statement timeout before any query runs. The default is
 
 `SqlValidator` rejects non-read-only SQL at the string level, before any database interaction.
 
-Validation runs **once**, inside the executor, with the dialect of the live adapter. There is deliberately no earlier dialect-blind pre-check in the tool handler: a validator built without a dialect is the conservative MySQL+PostgreSQL union, and running it first meant a MySQL host rejected statements whose `\'`/backtick grammar produces a spuriously forbidden PostgreSQL view — the adapter-aware acceptance below could never be reached on a real transport. The executor raises `SqlValidationError` for anything it refuses, which the dispatch pipeline renders as a tool error, so nothing is ungated.
+Validation runs **once**, inside the executor, with the dialect of the live adapter. There is deliberately no earlier dialect-blind pre-check in the tool handler: a validator built without a dialect is the conservative union of supported dialects, and running it first meant a MySQL host rejected statements whose `\'`/backtick grammar produces a spuriously forbidden PostgreSQL view — the adapter-aware acceptance below could never be reached on a real transport. The executor raises `SqlValidationError` for anything it refuses, which the dispatch pipeline renders as a tool error, so nothing is ungated.
 
 
 - **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 both 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. 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.
 - **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
 
@@ -853,7 +859,44 @@ quote and comment rules. MySQL also reads the executing session's `ANSI_QUOTES`
 and `NO_BACKSLASH_ESCAPES` settings for validation, protected-column scanning, and
 table gating; adjacent subtraction operators are not assumed to begin a comment.
 Direct scanner callers without session settings use conservative quote-mode scans.
+SQLite read SQL accepts simple ASCII bare, double-quoted, or backtick identifiers
+(letters, digits, and underscores, starting with a letter or underscore).
+Use whitespace after `FROM` and `JOIN`, and use `SELECT` subqueries rather than
+parenthesized table groups. Bracket-quoted and string-quoted names, quoted names
+containing punctuation, and unsupported table-reference syntax are refused before
+execution, because they cannot be reliably checked against the configured table
+policy. Ordinary string literals remain supported. This restriction is part of
+2.0.0.beta4; keep read tools disabled on older versions when this policy is
+needed. Confirm that the release is available before selecting it. The Rails-version
+integration lane checks these boundaries on real SQLite.
+
 The contributor live-backend lane exercises these boundaries
 through Console requests against PostgreSQL and MySQL. Keep read tools disabled
 unless live SQL access is needed, and retain the configured blocked-table and
 redaction policies when diagnosing a rejected request.
+
+## Console policy corrections in 2.0.0.beta4
+
+In `2.0.0.beta4`, the default model-reading tools check the resolved relation
+against `console_blocked_tables` before fetching records or counts. This includes
+application-defined default scopes and the parent lookup for association counts.
+The checked relation is reused for execution so a dynamic default scope is not
+resolved twice. These checks do not change which Console tools are enabled.
+
+Response handling redacts protected fields before invoking serializers, converts
+the remaining response to JSON-compatible values, then redacts and scans that
+normalized tree before either JSON or Markdown rendering. Symbol values and custom
+JSON serializers therefore receive the same credential checks as ordinary strings.
+Custom values in Markdown now use their JSON-compatible representation. Numbers,
+booleans, nulls, and ordinary record shapes retain their existing meanings.
+
+For SQLite SQL, keyword spellings receive function-policy exceptions only where
+supported query grammar requires them. PostgreSQL reserved-keyword grammar is
+preserved. Unsupported parenthesized offset expressions on other dialects may
+require a plain numeric offset. Keep the configured access and credential policies
+in place when adjusting a query.
+
+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.

data/docs/DOCKER_SETUP.md

@@ -468,6 +468,6 @@ To register `console_sql` and `console_query`, enable
 
 ### Woods MCP tools not available in a git worktree
 
-When working in a git worktree, subagents may not find the woods MCP servers because `.mcp.json` discovery is path-based and the worktree has a different root directory. See [MCP_WORKTREE_SETUP.md](MCP_WORKTREE_SETUP.md) for the fix and verification steps.
+A separate Claude Code session launched in a worktree may have different project-scoped MCP registrations. Subagents inherit the parent session's MCP tools, subject to tool restrictions; changing their working directory does not select a different Woods index. Check registration, the Compose service's mounted checkout, and the served index using [MCP worktree setup](MCP_WORKTREE_SETUP.md).
 
 See [CONSOLE_MCP_SETUP.md](CONSOLE_MCP_SETUP.md) for detailed console server documentation.

data/docs/EXTRACTOR_REFERENCE.md

@@ -2,7 +2,7 @@
 
 Woods ships **35 extractor classes** producing **39 distinct unit types**: one for each meaningful category of Rails code. This doc covers what each extractor captures, how to configure them, and the shape of the data they produce.
 
-> **Counts explained.** `lib/woods/extractors/` contains 42 files: 35 extractor classes (each ending in `_extractor.rb`) plus 7 supporting utilities (`shared_utility_methods`, `shared_dependency_scanner`, `callback_analyzer`, `behavioral_profile`, `route_helper_resolver`, `ast_source_extraction`, `source_nesting`). The 39 unit types comes from some extractors emitting multiple categories, `GraphQLExtractor` alone produces four (`graphql_type`, `graphql_mutation`, `graphql_resolver`, `graphql_query`), and `RailsSourceExtractor` produces both `rails_source` and `gem_source`. Supporting utilities enrich existing extractors (callback side-effects, behavioral config, AST-based source slicing, nested-namespace resolution) but are not themselves extractors and do not appear in the unit type enumeration. The authoritative mapping is `Woods::Extractor::TYPE_TO_EXTRACTOR_KEY` in `lib/woods/extractor.rb`.
+> **Counts explained.** `lib/woods/extractors/` contains 35 extractor classes (each ending in `_extractor.rb`) plus supporting utilities such as `shared_utility_methods`, `shared_dependency_scanner`, `callback_analyzer`, `behavioral_profile`, `route_helper_resolver`, `ast_source_extraction`, `source_nesting`, and `declared_parent`. The 39 unit types comes from some extractors emitting multiple categories, `GraphQLExtractor` alone produces four (`graphql_type`, `graphql_mutation`, `graphql_resolver`, `graphql_query`), and `RailsSourceExtractor` produces both `rails_source` and `gem_source`. Supporting utilities enrich existing extractors (callback side-effects, behavioral config, AST-based source slicing, nested-namespace resolution) but are not themselves extractors and do not appear in the unit type enumeration. The authoritative mapping is `Woods::Extractor::TYPE_TO_EXTRACTOR_KEY` in `lib/woods/extractor.rb`.
 
 ---
 
@@ -65,6 +65,7 @@ Every extractor returns `Array<ExtractedUnit>`. An `ExtractedUnit` is a self-con
 - Reads Rails' per-event callback chains (`_save_callbacks`, `_create_callbacks`, and the other lifecycle events), preserving each chain's order and each entry's `kind`, filter and conditions. The public `type` combines kind and event, such as `before_save` or `after_create`; Rails' separate `before_commit` event is reported as `before_commit`, not `before_before_commit`. `callback_count` equals the emitted callback list's length. The list includes framework-registered callbacks; it is runtime metadata, not an application-only filter or a cross-event execution trace. Regenerate the index after upgrading to pick up corrected callback metadata.
 - Proc/lambda filters, including Rails-generated association callbacks, use stable source-site labels in both metadata and callback chunks: `#<Proc app/models/post.rb:12>` (or `lambda`). App paths are relative to `Rails.root`; external paths are retained and native procs use `native`. Rails 6's numeric filter identity is resolved through `raw_filter`. These labels describe location and callable kind, not captured closure state; callbacks are never executed. Model condition labels retain their existing format.
 - Default callback-object representations omit process addresses: an instance becomes `#<CleanupCallback>`, an anonymous class becomes `#<Class>`, and its instance becomes `#<#<Class>>`. Anonymous namespace prefixes are normalized too (for example, `#<Module>::CleanupCallback`). Named classes and custom `to_s` labels retain their text. These labels do not distinguish arbitrary object state; separate registered callbacks remain separate entries even when their descriptive labels match. Controller object-filter formatting is unchanged.
+- Direct Proc/lambda validation option values (for example inclusion/exclusion membership or message callables) use the same stable kind/source-site labels without execution. Validation order and duplicates, condition formats (`if`, `unless`, `on`), and non-Proc values are unchanged. Nested arrays/hashes are not recursively normalized, and labels do not serialize captured closure state. Run a full extraction after upgrading to refresh retained validation metadata; the stored schema is unchanged.
 - Callback side-effects are analyzed via `CallbackAnalyzer`: detects columns written (`self.col =`), jobs enqueued (`perform_later`), and services called
 - Reflects model class and instance methods after reading the schema, so Rails schema-loading optimizations produce the same method metadata in cold and warmed runs. Application-defined constructors remain visible; Rails versions that install an optimized singleton `new` during schema loading consistently include it in `class_methods`.
 - Automatically skips HABTM join models and anonymous classes
@@ -255,6 +256,10 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 - Discovery and direct extraction accept only mailers backed by an existing app-owned source file, excluding dependency mailers and fabricated convention paths.
 - Each mailer action corresponds to an email template, template paths are recorded in metadata
 - Extracts `default from:`, `layout`, and per-action subject patterns
+- Action names are sorted consistently in metadata, the generated header, template discovery and action chunks. Callback chain order and duplicate registrations are preserved.
+- Direct Proc-valued defaults and Proc callback filters use source-location/kind labels without executing them; application paths are relative to `Rails.root`. Default containers, literal strings and non-Proc values retain their existing types. This does not serialize closure captures or recursively normalize arbitrary nested objects.
+- Object callback filters use descriptive labels with addresses removed only from Ruby's default representation, including anonymous classes and namespaces. Custom labels and literal hexadecimal text are preserved. Labels do not serialize callback object state, and extraction never invokes callbacks.
+- After upgrading, run a full extraction to refresh retained mailer units. Stabilized headers and callable labels can cause a one-time source-hash change; stored index schemas are unchanged.
 
 ---
 
@@ -382,6 +387,7 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 - Scans `app/models` for files that don't define an `ActiveRecord::Base` descendant
 - Common examples: value objects, form objects placed in `app/models`, domain structs
 - Excludes concerns (those go to ConcernExtractor)
+- `parent_class` and the generated Parent annotation describe the selected unit declaration only. Nested or sibling classes cannot supply its parent. An implicit `Object` parent, a dynamic superclass expression, or unparseable source produces `nil`; explicit constant-path parents retain their source names.
 
 ---
 
@@ -421,6 +427,7 @@ class PageView < AnalyticsRecord; end   # metadata[:database] => "analytics"
 - Produces unit types: `graphql_type`, `graphql_mutation`, `graphql_resolver`, `graphql_query`
 - Extracts field metadata (types, descriptions, complexity, arguments), authorization patterns (Pundit, CanCan, `authorized?`), and dependencies on models/services
 - Since all GraphQL units come from one extractor, incremental re-extraction handles them via `extract_graphql_file`
+- `parent_class` and summary chunks describe the selected declaration's explicit constant-path superclass, preserving its written qualification. Nested or sibling declarations and literal text cannot supply a parent. Implicit Object, module interfaces, dynamic superclass expressions, unavailable source, and invalid source have no declared parent (`null` metadata; `unknown` in summaries). This is source declaration metadata, not resolved runtime ancestry.
 
 **Example output (abbreviated):**
 
@@ -677,6 +684,7 @@ Every app-owned unit under a package root carries `metadata[:package]` with the
 **Key details:**
 - Excludes `lib/tasks/` (covered by RakeTaskExtractor) and `lib/generators/`
 - File-based scanning; no assumption about class hierarchy
+- `parent_class` and the generated Parent annotation describe the selected unit declaration only. Nested or sibling classes cannot supply its parent. An implicit `Object` parent, a dynamic superclass expression, or unparseable source produces `nil`; explicit constant-path parents retain their source names.
 
 ---
 

data/docs/INCREMENTAL_EXTRACTION.md

@@ -98,6 +98,23 @@ including inlined code and callback analysis. Multiple runtime mixins sharing a
 file retain separate identities and refresh all their includers. Run a full extraction after upgrading
 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
+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
+units. The published generation and source provenance remain unchanged,
+including when other files in the batch extracted successfully.
+
+Fix the source error named in the extraction log, then retry the **complete
+batch**, or the same named refresh. The watch daemon reports degraded and keeps
+the failed batch pending for retry. An error on one file does not mark a later
+successful file as failed, but the batch still cannot publish until all handled
+errors are resolved. This does not change full extraction's existing tolerance
+for handled consumer errors; its source-freshness report marks those scopes
+unverified.
+
 ## What a run does, in order
 
 `Extractor#extract_changed` is order-sensitive; each step exists because of the
@@ -109,8 +126,8 @@ step before it.
 2. **Reconcile changed paths.** Every changed path that still exists is handed
    to the file-based extractors that claim it (`PathDispatcher`), and units the
    path no longer produces are dropped. This is what indexes a file the index
-   has never seen, and what lets a task removed from a multi-task `.rake` file
-   actually go away.
+   has never seen, and what removes definitions deleted from a surviving
+   source file. Multi-file Rake tasks use wholesale reconciliation below.
 3. **Re-extract the rest of the blast radius**: units whose own file did not
    change but which depend on something that did.
 4. **Reconcile class-based types** against each extractor's
@@ -208,7 +225,6 @@ automatically.
 | `config/locales/**/*.yml` | i18n |
 | `config/initializers`, `config/environments` | configurations |
 | `db/migrate/*.rb` (top level only) | migrations |
-| `lib/tasks/**/*.rake` | rake_tasks |
 | `lib/**/*.rb` (outside `tasks/`, `generators/`) | libs |
 | `spec/**/*_spec.rb`, `test/**/*_test.rb` | test_mappings |
 
@@ -219,12 +235,13 @@ serializer and decorator extractors, and all matching rules run.
 ### Wholesale re-runs
 
 `PathDispatcher.whole_app_rules` → `Extractor::WHOLE_APP_EXTRACTORS`. These
-extractors have no per-file entry point: they introspect the runtime or scan a
-whole directory in one pass. In an already-booted process re-running them is
+extractors need a complete runtime or directory view, even when a low-level
+per-file reader exists. In an already-booted process re-running them is
 cheap, which is what makes wholesale replacement the right shape.
 
 | Trigger | Re-runs |
 |---|---|
+| `lib/tasks/**/*.rake` | rake_tasks (all definitions of every task) |
 | `config/routes.rb`, `config/routes/**` | routes, engines, **and** controllers, mailers, components, view components, view templates |
 | `Gemfile.lock` | engines, middleware, rails_source (gated by `include_framework_sources`) |
 | `config/application.rb`, `config/initializers/**`, `config/environments/**` | middleware |
@@ -235,7 +252,14 @@ cheap, which is what makes wholesale replacement the right shape.
 | `db/views/**/*.sql` | database_views |
 | any `package.yml`, `packwerk.yml` | packages |
 
-Three of these deserve a note:
+Four of these deserve a note:
+
+- **Rake tasks merge definitions across files.** Any changed or deleted `.rake`
+  file reruns the task extractor over all task files. Removing the primary
+  definition preserves surviving definitions; removing a secondary definition
+  drops its source and dependencies from the shared unit. After upgrading from
+  the old per-file rules, run a full extraction to establish a source-freshness
+  baseline with the new rule fingerprint.
 
 - **Routes cascade.** `ROUTE_CONSUMER_EXTRACTORS` embed the route table, controllers write each action's routes into unit metadata and into the action
   chunks, and everything using `RouteHelperResolver` resolves navigation edges

data/docs/MCP_SERVERS.md

@@ -180,7 +180,7 @@ failure boundary; they do not prove uniqueness or become `ambiguous_identity` er
 Use `depth: 0` for the request timeline, or inspect candidates with typed `lookup`
 calls. Re-extraction does not remove a legitimate cross-type collision. Successful
 traces retain their existing identifiers and response shape; target identity has
-not been migrated globally. These corrections are unreleased after `2.0.0.beta2`.
+not been migrated globally. These corrections are available in `2.0.0.beta3`.
 
 The server also exposes MCP resources and resource templates for indexed units. Tool descriptions returned by MCP are the parameter-level source of truth; [Agent guide](AGENT_GUIDE.md) explains selection strategy.
 
@@ -192,6 +192,23 @@ error and continues serving the previous aligned generation; it never swaps in a
 partial or empty replacement. Grant write access for live reloads, or restart the MCP
 process after publishing a new embedded index.
 
+### Graph-analysis pages
+
+Unreleased after `2.0.0.beta3`: `graph_analysis` enforces its advertised default
+of 20 rows per section. Pass `limit` and `offset` to page one selected `analysis`
+or each section of `analysis: "all"`. Explicit limits also bound nested hub
+`dependents` lists. Older servers may return every section row when `limit` is
+omitted; pass a limit explicitly when supporting both versions.
+
+JSON responses retain `<section>_total`, `<section>_offset` (when positive), and
+`<section>_truncated: true` whenever a page omits rows before or after it. Markdown,
+plain, and Claude responses show the same total and offset on last and empty
+pages. For example, offset 20 with limit 5 over 25 published orphans shows
+`5 of 25 from offset 20`; offset 100 shows `0 of 25 from offset 100`. An empty
+page does not mean the section has no findings. These totals describe the
+published report arrays, which can themselves be bounded during extraction;
+they do not establish complete source-reference coverage.
+
 ### Search completeness
 
 Search responses retain `query`, `result_count`, and `results`; `result_count`
@@ -229,6 +246,31 @@ Detected missing, unreadable, or corrupt artifacts remain `isError: true` with
 `has_more`, `total_matches`, and `matched_lower_bound`; no successful empty
 result is substituted. Inspect `woods_status` and run `woods:validate`.
 
+### Dependency graph coverage
+
+`dependencies` and `dependents` return relationships recorded in the published
+index, not an exhaustive call graph or source-reference index. Extraction combines
+runtime reflection with selective source scanning; arbitrary method-body constant
+references (including references to generic PORO and library classes) may have no
+edge. No dependents, a test-only dependent, or a completed traversal does not prove
+there are no production callers. Verify important absence claims in source.
+
+Supporting servers expose the annotated, paginated traversal result in
+`structuredContent.data` for every renderer, including the default packaged
+stdio and HTTP servers. Read `data.total_is_exact`, `data.graph_coverage`, budget
+counters and optional explanation witnesses there; `content[0].text` and
+`structuredContent.text` keep the same human-readable rendering. No `format`
+tool argument is needed or accepted. This additive data payload is unreleased
+after `2.0.0.beta3`; verify the installed response before relying on it. Older
+human-renderer responses can carry only text. The structured nodes and witnesses
+cover the same page, not an additional traversal or an unpaginated graph.
+
+Successful responses carry `graph_coverage` with `scope: "published_relationships"`,
+`source_references: "not_exhaustive"`, and a human-readable `notice`. Text formats
+show the same notice, including compact, root-only and empty-page responses.
+This response metadata and the total exactness field below are unreleased after
+Woods `2.0.0.beta3`; older servers need the same conservative interpretation.
+
 ### Dependency traversal budgets
 
 `dependencies` and `dependents` walk breadth-first in stored graph order. The
@@ -251,7 +293,16 @@ Exact-budget walks that finish all requested work are complete and have no
 `limit` (default 50) and `offset` only page that discovered result; they never
 change the walk budget or depth. On a partial traversal, `nodes_total`, when
 present for pagination, counts the discovered prefix, **not the full reachable
-graph**. Paging beyond that prefix stays partial. To explore more, narrow
+graph**. Every successful response includes `total_is_exact`: false for a
+budget cutoff, true when the requested walk finishes, even when its page is
+truncated or empty. It is independent of `limit`/`offset` and is present for
+unpaged answers too. Partial text answers say `Showing N of at least M (total
+unknown: node_budget)` (or `edge_budget`), including when no pagination is needed.
+`M` includes the root and counts the admitted prefix; it is a lower bound for the
+requested root, depth, type/relationship filters and published generation, not a
+count of all application callers. Exactness describes that same recorded-graph
+scope and never implies exhaustive source coverage. Paging beyond that prefix
+stays partial. To explore more, narrow
 `depth`/`types`/`via`, choose another root, or increase the traversal budget within
 its maximum. Keep the root, filters, budgets, and published generation unchanged
 for stable pages. No wall-clock deadline is used, so cutoffs are deterministic.
@@ -289,6 +340,10 @@ A target name shared by several types has `type: null`,
 record target types, so the response cannot choose among candidates. A witness
 through an ambiguous or unresolved identity sets `typed_path_complete: false`;
 it describes identifier-level reachability, never a uniquely typed path.
+A true value means only that identities along this witness have unambiguous
+types. It does not establish source-reference coverage or observed execution.
+Text labels this `witness types unambiguous=yes/no`; the JSON key and its meaning
+remain unchanged. The text label change is unreleased after `2.0.0.beta3`.
 `types` filters retain the compact traversal's identifier-level semantics: any
 registered type can qualify a name, while edge evidence keeps its actual source
 owner. Multiple relationship kinds between the same endpoints remain separate.

data/docs/MCP_TOOL_COOKBOOK.md

@@ -64,7 +64,7 @@ The Index Server defines **29 schemas**: the packaged executable registers **14*
 | Snapshot (4) | 4 | Extraction with `enable_snapshots = true` normally creates `woods.sqlite3`, which packaged servers discover. If extraction used the JSON fallback, set `WOODS_SNAPSHOTS=true` on the standalone server. Custom embedded servers pass `snapshot_store:`. Internal SQLite migrations are automatic. Tools: `list_snapshots`, `snapshot_diff`, `unit_history`, `snapshot_detail` |
 | `notion_sync` | 1 | `notion_api_token` + `notion_database_ids` both set |
 
-`codebase_retrieve` is always registered (no `retrieve` alias exists), but only returns results once an embedding provider is configured and `rake woods:embed` has run.
+`codebase_retrieve` is always registered (no `retrieve` alias exists). Default semantic mode requires an embedding provider and a completed `woods:embed` run. Explicit `WOODS_RETRIEVAL_MODE=lexical` ranks published extraction units without a provider or embeddings; set it in the MCP process environment and restart the server. See [embedding-free lexical retrieval](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval).
 
 If an agent reports a missing tool, compare its request with the connected server's registered list and [MCP server boundaries](MCP_SERVERS.md#conditional-index-capabilities). The normal packaged executable does not wire operator or feedback collaborators. **Console Server tools are not all unconditionally registered**: 31 tool schemas exist as an inventory, but only the 9 Tier 1 tools are executable by default, or 11 with `console_embedded_read_tools: true` (adds `console_sql`/`console_query`). Tier 2, Tier 3, and `console_eval` are schema-only in every supported mode; there is no bridge or confirmation flow that unlocks them. See [MCP servers](MCP_SERVERS.md#console-server) for the supported inventory.
 
@@ -551,7 +551,7 @@ Static tools miss all of these because they only exist after Rails processes the
 }
 ```
 
-**What you'll get:** Units with no dependents, nothing in the codebase references them. Good candidates for removal or investigation.
+**What you'll get:** Units with no recorded dependents in the published graph, excluding types treated as natural entry points. These are candidates for investigation, not proof of dead code. Method-body references and dynamic callers may be missing; verify source references, framework entry points, and runtime usage before removing anything. See [dependency graph coverage](MCP_SERVERS.md#dependency-graph-coverage).
 
 ---
 
@@ -811,7 +811,7 @@ Keys without a recognised suffix fall through to ActiveRecord `where(hash)` equa
 
 ### "Find code related to subscription billing"
 
-**Tool:** `codebase_retrieve` (Index Server, requires embedding provider)
+**Tool:** `codebase_retrieve` (Index Server, semantic or explicit lexical mode)
 
 ```json
 {
@@ -820,7 +820,7 @@ Keys without a recognised suffix fall through to ActiveRecord `where(hash)` equa
 }
 ```
 
-**What you'll get:** A token-budgeted context string of the most semantically relevant units, ranked by hybrid search (semantic + keyword + PageRank). Requires an embedding provider (`embedding_provider: :openai` or `:ollama`) to be configured.
+**What you'll get:** Ranked context within an estimated text-token budget. Default semantic mode uses configured embeddings and hybrid ranking; explicit lexical mode uses field-aware BM25 over published units, without a provider or `woods:embed`. The same query works in either configured mode, though rankings differ. Confirm the active mode with `woods_status.retriever.mode`; see the [retrieval guide](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval) for setup and budget limits.
 
 ---