woods 2.0.0.beta2 → 2.0.0.beta4

data/docs/MCP_SERVERS.md

@@ -27,6 +27,15 @@ bin/rails woods:validate
 bin/rails woods:stats
 ```
 
+For embedding-free ranked retrieval, start Index MCP with
+`WOODS_RETRIEVAL_MODE=lexical`. This opt-in reads the published extraction units;
+it does not probe providers or load vectors. `woods_status.retriever.mode` reports
+`lexical`, and inactive embedding fields are `null`. The default semantic mode
+keeps its existing embedding setup and failure behavior. See
+[retrieval modes](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval) for scoring,
+query limits and measured tradeoffs. Both packaged stdio and HTTP launches honor
+the setting; put it in the MCP process's environment, not just a Rails initializer.
+
 The stdio server can then run outside Rails. Point it at the index root (`tmp/woods/` by default), not at an internal generation or payload directory.
 
 ### Configure a stdio client
@@ -47,6 +56,10 @@ Prefer the application's bundle and a project-scoped configuration:
 
 `woods-mcp-start` checks that the directory and published manifest exist, then replaces itself with `woods-mcp`. It does not install dependencies or restart a crashed process.
 
+`woods_status.index.woods_version` identifies the last publisher of the served
+manifest; `server.version` identifies the running MCP reader. Missing writer
+provenance is `null`. See [manifest writer provenance](PUBLISHED_INDEX.md#manifest-writer-provenance).
+
 You can launch the server directly when the client already handles preflight:
 
 ```bash
@@ -57,6 +70,12 @@ Keep stdout reserved for MCP protocol messages. Diagnose startup failures from s
 
 ### Client configuration locations
 
+Supporting development builds offer preview/apply/update/remove ownership for
+Claude Code project or explicit user configuration. See
+[managed configuration](AGENT_SETUP.md#managed-claude-code-configuration) for
+`woods-agent-config`, host/Compose preflight, conflict handling, and recovery.
+Manual configuration remains available for older gems and other clients.
+
 MCP clients expose project or user-level server settings in different locations. Use project scope when available, preserve the `command`, `args`, and absolute `cwd` semantics above, and translate only the surrounding client-specific format. Woods is model-independent: compatibility depends on the client supporting MCP stdio or Streamable HTTP, not on whether the connected model is from OpenAI, Anthropic, Google, xAI, or another provider.
 
 Client configuration formats can change independently of Woods. If a client rejects otherwise valid JSON, check that client's current MCP documentation.
@@ -99,6 +118,27 @@ Reconnect the client, then call:
 
 Prefer a real MCP client's connection flow over a hand-written JSON-RPC pipe. Modern MCP 2026-07-28 requests carry per-request protocol metadata and can use `server/discover` without an initialization handshake; older clients still use `initialize`. A valid raw smoke test must implement one complete flow rather than sending an isolated `tools/list` or `tools/call` request.
 
+### Initialization guidance
+
+The Index Server supplies a short, client-neutral `instructions` field through
+the SDK's `initialize` response and modern `server/discover`. It describes the
+status → discovery → inspection → bounded traversal → source-verification
+workflow, and lists only the tools actually registered by this server.
+Instructions are stable for unchanged tool registration and bounded to 2,048
+UTF-8 bytes across supported configurations. Building the text does not probe
+providers, extract code, or write configuration.
+
+Registration alone does not establish retrieval readiness: check `woods_status`
+before using `codebase_retrieve`, including after reload. The guidance grants
+no extraction, configuration-change, or Console authorization. Detailed usage
+belongs in the [agent guide](AGENT_GUIDE.md).
+
+This addition is unreleased after `2.0.0.beta2`. The SDK omits `instructions`
+when negotiating protocol `2024-11-05`; that behavior is preserved. Older gems,
+legacy clients, and clients that do not show server instructions can use the
+agent guide or investigation skill. Leave protocol negotiation enabled rather
+than pinning a newer version solely to obtain guidance.
+
 ### Tools (29 — 14 registered in the packaged default)
 
 The Index Server defines 29 schemas across core and conditional capabilities. The normal packaged executable registers the 14 tools below; the remaining schemas require the specialized wiring described afterward.
@@ -108,8 +148,8 @@ The Index Server defines 29 schemas across core and conditional capabilities. Th
 | `woods_status` | Index health, generation, counts, and retrieval readiness |
 | `search` | Discover identifiers by regex, prefix, suffix, source, or metadata |
 | `lookup` | Fetch one exact unit with source, metadata, and relationships |
-| `dependencies` | Traverse what a unit depends on (`depth`, `types`, `via` narrow; `limit`, `offset` page) |
-| `dependents` | Traverse what depends on a unit (`depth`, `types`, `via` narrow; `limit`, `offset` page) |
+| `dependencies` | Traverse what a unit depends on (`depth`, `types`, `via` narrow; `max_nodes`, `max_edges` budget work; `limit`, `offset` page) |
+| `dependents` | Traverse what depends on a unit (`depth`, `types`, `via` narrow; `max_nodes`, `max_edges` budget work; `limit`, `offset` page) |
 | `structure` | Summarize structural relationships around a unit |
 | `trace_flow` | Follow a request, job, mail, or other execution flow |
 | `framework` | Inspect relevant Rails or installed gem source |
@@ -118,7 +158,29 @@ The Index Server defines 29 schemas across core and conditional capabilities. Th
 | `domain_clusters` | Discover connected domains in the graph |
 | `pagerank` | Find structurally central units |
 | `reload` | Reload a newly published generation without restarting the client |
-| `codebase_retrieve` | Natural-language retrieval; returns a configuration error until embeddings exist |
+| `codebase_retrieve` | Natural-language retrieval with embeddings or explicit lexical mode over extraction output |
+
+When an identifier appears in multiple extraction types, `framework` reads its
+framework-source bucket and `recent_changes` reads each selected type bucket.
+Their paths and metadata belong to that selected bucket. When session tracing
+is configured, newly recorded requests use the dispatched controller's runtime
+class name; the fallback for requests without an instance respects Rails acronym
+inflections. Existing trace records are unchanged. Controller lookup and root
+outgoing-edge selection preserve the controller type. Downstream references and the shared context pool still use
+bare identifiers. If a dependency encountered within the requested depth has
+multiple published types, `session_trace` returns an `ambiguous_identity` tool
+error naming the identifier and candidate types, with no partial context. This
+also prevents an earlier dependency from occupying a later controller’s context
+key. Unrelated collisions do not block a trace, and a known controller root keeps
+its controller identity. A controller absent from the index remains in the
+timeline without a source reference, so another type cannot fill that reference.
+Candidate discovery and source reads use one pinned
+generation. Corrupt or missing listed artifacts retain the `internal_error`
+failure boundary; they do not prove uniqueness or become `ambiguous_identity` errors.
+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 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.
 
@@ -130,6 +192,181 @@ 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`
+is the number returned, not an estimated total. The additive `completeness`
+object describes the requested types, literal filters, and fields in the pinned
+generation. This contract is unreleased after `2.0.0.beta2`.
+
+| `reason` | `status` | `has_more` | `total_matches` |
+|---|---|---|---|
+| `exhausted` | `complete` | `false` | Exact count |
+| `result_limit` | `partial` | `true` | `null` (unknown) |
+| `scan_budget` or `regex_timeout` | `partial` | `null` (unknown) | `null` (unknown) |
+
+`matched_lower_bound` counts distinct observed `(type, identifier)` matches,
+including at most one lookahead match beyond `limit`. A result-limit response
+therefore establishes another match; an exactly full page can instead be
+complete if the requested domain is exhausted. Deep lookahead shares
+`WOODS_SEARCH_MAX_SCAN` with the initial scan and retains round-robin scanning
+across types. Search does not count the entire omitted tail or offer pagination.
+The existing `types` filter and result labels name directory families:
+`rails_source` includes both Rails and gem source units. Deep reads accept those
+two stored types only in that shared directory; `lookup` and lexical retrieval
+retain the unit's actual `rails_source` or `gem_source` type.
+
+All partial responses retain `partial: true` and include a narrowing `hint`.
+JSON exposes these fields; Markdown, plain text, and Claude formats label the
+returned count, stopping reason, known/unknown remainder, and total explicitly.
+Narrow `types`, literal `exact_prefix`/`exact_suffix`, or deep `fields` before
+using discovery as exhaustive evidence. Completeness applies to this index and
+query domain, not to unindexed application code.
+
+Detected missing, unreadable, or corrupt artifacts remain `isError: true` with
+`_meta.error_code: "corrupt_artifact"`. Their `_meta.completeness` has
+`status: "unknown"`, `reason: "unreadable_or_corrupt_source"`, and `null` for
+`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
+walk defaults to `max_nodes: 1000` (including the root) and `max_edges: 10000`;
+callers can select 1–10,000 nodes and 1–100,000 edge checks. The node budget
+counts distinct nodes admitted after filters. Every candidate edge is charged
+before filtering, including duplicates, cycles, and the forward-edge checks
+needed to match a reverse `via` filter. Thus restrictive filters cannot bypass
+the edge budget. Nodes at the requested `depth` are recorded without reading
+their adjacency lists.
+
+When further expansion would exceed a budget, JSON reports `partial: true`,
+`partial_reason: "node_budget"` or `"edge_budget"`, and `traversal_budget` with
+`max_nodes`, `max_edges`, `visited_nodes`, and `visited_edges`. Text renderers
+also identify the partial traversal. Already discovered nodes remain in the
+answer, but an empty `deps` array in a partial answer does not prove a leaf.
+Exact-budget walks that finish all requested work are complete and have no
+`partial` marker.
+
+`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**. 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.
+
+Budgets cover traversal work after per-generation graph loading and cache
+preparation (JSON parsing, typed-edge normalization, node types and database
+metadata). They do not cap that initial load, elapsed time, or total process
+memory. These arguments are unreleased in Woods 2.0.0.beta2; check the connected
+server's tool schema before sending them to an older installation.
+
+### Traversal explanations
+
+Supporting development versions accept `explain: true` on `dependencies` and
+`dependents`. Check the connected schema first; this option is unreleased after
+2.0.0.beta2. Omitted or false keeps the existing compact response.
+
+The additive `explanation` object contains:
+
+- `direction`: `forward` or `reverse`, plus the requested `root` identity.
+- `edges`: records keyed by response-local IDs such as `e0`. Every record keeps
+  the original **source → target** direction, even during reverse traversal.
+  `source` contains its recorded `identifier` and `type`; `target` contains its
+  identifier and the unique type when the published graph establishes one.
+  `via`, `through`, `through_db`, and `disable_joins` preserve recorded values;
+  absent legacy attributes are null (shown as unknown in text), including an
+  unrecorded `disable_joins` rather than an invented false value.
+- `witnesses`: one shortest breadth-first predecessor per admitted identifier,
+  keyed by identifier. Each has `parent`, `edge_id`, `impact` (`root`, `direct`,
+  or `transitive`), and `typed_path_complete`. Follow parent references to the
+  root to reconstruct one witness; alternative paths are not enumerated.
+
+A target name shared by several types has `type: null`,
+`resolution: "ambiguous"`, and sorted `candidate_types`. An unresolved target has
+`resolution: "unresolved"` and an empty candidate list. Forward artifacts do not
+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.
+
+Direct witnesses establish a recorded root relationship; transitive witnesses
+represent inferred downstream reachability through recorded relationships.
+Neither establishes observed execution, confidence, call order, or test coverage.
+
+Node pagination retains required ancestor witnesses once, marked `context: true`
+when outside the page; returned rows have `context: false`. Context records do
+not increase the result-row count. Page evidence retains the witness edges and
+other observed relationships among its visible/context endpoints; an empty page
+has empty edge/witness maps. Edge IDs are local to this traversal response.
+
+All examined evidence shares the existing edge budget, before `via`/`types`
+filtering. Current `reverse_via` buckets allow direct reverse evidence lookup;
+legacy recovery charges each reverse candidate and every inspected forward edge.
+The shared predecessor forest and emitted records remain bounded by admitted
+nodes and inspected edges. Per-generation JSON loading and the cached
+O(nodes + variants) ownership/type preparation are outside the walk budget;
+explanation mode never flattens all forward edges as per-request preparation.
+Partial traversal and pagination metadata retain the budget contract above.
+
 ### Conditional Index capabilities
 
 The Ruby server builder contains 15 additional schemas for sessions, pipeline operations, retrieval feedback, temporal snapshots, and Notion sync. They register only when their required collaborators or configuration are wired.
@@ -140,6 +377,7 @@ The normal packaged executable does not wire pipeline-operator or feedback-store
 
 Use HTTP only for a deliberate shared or remote deployment. It expands the network boundary and requires authentication, origin restrictions, and TLS termination. Follow [MCP HTTP transport](MCP_HTTP_TRANSPORT.md); do not translate the stdio example into an unauthenticated public listener.
 
+
 ## Console Server
 
 The Console Server launches a Rails process through direct, Docker, or SSH connection configuration. It reads live data and must be treated as a separate security decision.
@@ -151,11 +389,14 @@ Console MCP is disabled by default because it reads live application data. Enabl
 ```ruby
 Woods.configure do |config|
   config.console_mcp_enabled = true
-  config.console_mcp_token = ENV["WOODS_CONSOLE_MCP_TOKEN"]
+  config.console_mcp_http_enabled = false # stdio-only
 end
 ```
 
-The bearer token authenticates HTTP clients and is not sent over stdio. Rails still validates Console configuration while booting: production requires a token of at least 32 characters whenever Console is enabled, including for a stdio-only client. Keep it in the application's secret store, not in the initializer.
+This explicitly disables HTTP Console while retaining stdio access; no HTTP
+token is needed at boot. Existing configurations default to HTTP enabled.
+For HTTP deployment, enable the HTTP flag and configure its token, origins
+and TLS using the [Console setup guide](CONSOLE_MCP_SETUP.md#option-c-http-rack-middleware).
 
 Without a console connection file, the executable then launches the Rails task directly from its `cwd`:
 
@@ -229,3 +470,33 @@ Report vulnerabilities privately through [SECURITY.md](../SECURITY.md).
 5. Check [Troubleshooting](TROUBLESHOOTING.md) for the exact stderr message.
 
 For agent query behavior after connection, continue to [Agent guide](AGENT_GUIDE.md).
+
+### Explicit retrieval and discovery scope
+
+On a server whose tool schema advertises them, `packages` and `source_paths` narrow
+`search` and `codebase_retrieve` before candidate limits. These are per-call
+arguments, not configuration settings. Inspect applied scope and completeness;
+a narrow graph query can omit relevant cross-boundary dependencies. See the
+[scope contract](RETRIEVAL_GUIDE.md#explicit-package-and-source-path-scopes) for
+root/nested ownership, path normalization, errors, storage support, and cost.
+
+### Source freshness in status
+
+`woods_status` accepts optional `source_check: "quick"` (default, 250ms scan) or
+`"deep"` (five seconds). `index.source_freshness` describes the served generation
+as `current`, `drifted` or `unknown`; missing source/key and incomplete capture
+never count as current. No Rails initialization or provider call is needed.
+See [source freshness](SOURCE_FRESHNESS.md) for scope, private-key handling and
+fresh-process extraction. Existing HEAD/dirty fields remain separate diagnostics.
+
+### Explicit source evidence modes
+
+When advertised by the installed schema, `lookup` and `codebase_retrieve` accept
+`evidence: 'compact'` or `'outline'`; omitted/`'full'` preserves existing behavior.
+Retrieval uses its original query. Compact lookup accepts optional `query` and an
+estimated `budget` (default 2000); full lookup remains complete. `lookup` also
+accepts an actual `type` and a `source_sha256` guard for typed, byte-verified
+follow-up from an excerpt. Compact modes cannot be combined with metadata-only
+lookup controls. Structured provenance stays within the existing closed output
+schema's `data` field. Read the [evidence contract](RETRIEVAL_GUIDE.md#compact-published-evidence-and-api-outlines)
+before interpreting published line ranges as physical source locations.

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.
 
@@ -255,13 +255,24 @@ The `metadata.inlined_concerns` array lists which concerns were resolved:
 }
 ```
 
-**What you'll get:** A BFS tree of everything that references `User`, controllers, services, jobs, mailers, up to 2 hops out. Set `depth: 1` for direct dependents only.
+**What you'll get:** A BFS traversal of units that reference `User`, such as controllers, services, jobs, and mailers, up to 2 hops out. Set `depth: 1` for direct dependents only.
 
-The answer is bounded to 50 nodes. When it is cut, the response ends with a
+The answer is paged to 50 nodes by default. When it is cut, the response ends with a
 `Showing N of M (truncated)` line, the same one `graph_analysis` prints. Reach
 for `depth`, `types` and `via` first: they make the answer smaller. `limit` and
 `offset` only page what those leave, so a hub read one page at a time still
-costs every page.
+repeats the walk. A separate traversal budget can return `partial: true`;
+that marker means the reachable graph is incomplete even after the final page.
+See [traversal budgets](MCP_SERVERS.md#dependency-traversal-budgets) before
+changing `max_nodes` or `max_edges`.
+
+To explain why a row is affected, check the connected schema and add
+`"explain": true`. The response preserves source-to-target labels even while
+walking dependents. Its predecessor witnesses distinguish direct relationships
+from transitive inferred reachability, retain ancestor context across pages, and
+mark ambiguous types explicitly. See the
+[explanation contract](MCP_SERVERS.md#traversal-explanations); these witnesses are
+not proof of observed execution.
 
 To find only which jobs depend on `User`:
 
@@ -323,26 +334,30 @@ column.
 }
 ```
 
-**Example response:**
+**Example JSON data** (inside the MCP response envelope):
 
 ```json
-[
-  {
-    "identifier": "PaymentsController",
-    "type": "controller",
-    "file_path": "app/controllers/payments_controller.rb",
-    "metadata": {
-      "actions": ["create", "show", "webhook"],
-      "routes": [
-        { "verb": "POST", "path": "/payments", "action": "create" },
-        { "verb": "POST", "path": "/payments/webhook", "action": "webhook" }
-      ]
-    }
+{
+  "query": "payment",
+  "result_count": 1,
+  "results": [
+    { "identifier": "PaymentsController", "type": "controller", "match_field": "identifier" }
+  ],
+  "completeness": {
+    "status": "complete",
+    "reason": "exhausted",
+    "has_more": false,
+    "total_matches": 1,
+    "matched_lower_bound": 1
   }
-]
+}
 ```
 
-Search `source_code` when you want semantic matches, not just naming matches.
+Use `lookup` on the returned identifier for source, actions, and routes. Search
+`source_code` for textual matches beyond names. Supporting versions distinguish
+exact totals from a bounded result prefix; `partial` means this is discovery,
+not an exhaustive list. Completeness metadata is unreleased after `2.0.0.beta2`;
+see the [search contract](MCP_SERVERS.md#search-completeness).
 
 ---
 
@@ -536,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).
 
 ---
 
@@ -796,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
 {
@@ -805,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.
 
 ---