woods 2.0.0.beta2 → 2.0.0.beta4

data/plugin/skills/woods-diagnose/SKILL.md

@@ -14,6 +14,19 @@ git status --short --branch
 
 This skill describes the Woods 2.x line; the authoritative minimum version lives in the marketplace entry. Diagnose against capabilities the recorded installed version actually provides.
 
+## Managed configuration availability
+
+`woods-agent-config` (#407) is available in Woods `2.0.0.beta3`. First record the
+installed version and test `bundle exec woods-agent-config --help` in the
+selected application bundle. When supported, use its saved setup/update/remove
+plan and explicit client/scope/root selection; apply the reviewed plan within
+the user's existing authorization. Do not infer ownership from a server name
+or repair edited managed sections by overwriting them. Plans and recovery
+journals contain private configuration bytes. See the canonical
+[managed configuration runbook](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md#managed-claude-code-configuration)
+for host/Compose preflight, actual Claude file locations, conflict recovery,
+and removal. Preserve manual setup for older installed versions.
+
 ## 1. Check Rails
 
 ```bash
@@ -23,8 +36,58 @@ bundle exec rails runner 'Rails.application.eager_load!; puts "eager load ok"'
 
 Use the application's normal Docker command and environment variables when applicable. Fix boot/eager-load failures before Woods.
 
+### Watch repeatedly exits 75
+
+Check the installed version's watch guide. Older releases, including
+`2.0.0.beta2`, can rediscover the same restart-trigger paths on every boot. Stop
+the supervisor, run one successful full extraction, then restart the standalone
+watch task. Do not assume automatic startup reconciliation exists in that release.
+For versions documenting environment-boot snapshots, confirm that the command is
+`bundle exec rake woods:watch`, with no preceding `environment` task, and check
+whether boot inputs keep changing during initialization or catch-up.
+
+### Watch retains facts from an initializer deleted while stopped
+
+Record the installed revision. Unreleased after `2.0.0.beta3`, startup preserves
+registered deleted boot inputs as full-extraction obligations. On earlier builds,
+stop watch, run a successful full extraction in a fresh process, then restart
+standalone `woods:watch`. See the installed version's watch guide.
+
+### A cleaned index directory still exists
+
+Unreleased after `2.0.0.beta3`, `woods:clean` retains the output directory and
+hidden extraction guard for concurrent writer coordination. Verify published
+artifacts are gone; do not remove that guard while writers may be running.
+
+### Watch misses edits under a shared directory alias
+
+Check the installed version: logical alias preservation (#445) is available in Woods `2.0.0.beta3`.
+Older polling/catch-up walkers could visit an irrelevant alias first and suppress
+`app/models` when both point to the same physical directory. Compare the logical
+path with the extraction input path; a running daemon alone does not prove coverage.
+Use a manual extraction for recovery until upgrading. The corrected walker keeps
+independent aliases and prunes ancestor cycles; do not remove cycle or ignore guards.
+See the installed version's watch guide before assuming this behavior.
+
+### Session trace reports ambiguous identity
+
+The `session_trace` `ambiguous_identity` error (#213) is available in Woods `2.0.0.beta3`;
+check the installed gem before expecting it. It names a dependency
+with multiple published extraction types, so no partial session context is
+returned. Use `depth: 0` for the timeline or inspect the named candidates with
+explicit `lookup` types. Do not choose one by index order or suggest that a full
+extraction will remove a legitimate cross-type collision. See the canonical
+[session identity contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#index-server).
+
 ## 2. Check the published index
 
+For a `same-type identifier collision`, inspect both named source files and the
+Rails loader before suggesting source edits. Wrapper-nested class naming needs
+Zeitwerk mode and Zeitwerk >= 2.6.9; an older loader or classic mode can produce
+the collision even when the namespace wrappers are valid. The expanded error
+guidance (B-149) is available in Woods `2.0.0.beta3`; check the installed version
+first. Follow the [loader compatibility guidance](https://github.com/lost-in-the/woods/blob/main/docs/UPGRADING_TO_2.md#check-the-loader-for-wrapper-nested-classes).
+
 ```bash
 bin/rails woods:validate
 bin/rails woods:stats
@@ -32,12 +95,108 @@ bin/rails woods:stats
 
 If missing or stale, run the narrow maintenance path justified by the evidence: `woods:incremental` for known file changes or `woods:extract` for first run, broad change, upgrade, or drift. Woods tasks understand `generation.json`; do not assume `manifest.json` is at the root.
 
+Semantic graph validation (#413) is available in Woods `2.0.0.beta3`; verify the
+installed gem before expecting these errors. Supporting versions check typed
+unit identity, graph/index agreement and forward/reverse/file/type memberships
+within one pinned generation. Preserve the failing generation and exact error,
+then run a fresh full extraction with the intended bundle and validate again.
+Do not hand-edit derived graph indexes to silence failures. A repeated error on
+a fresh full run is evidence to report as an extraction defect. Unresolved
+targets can be valid; validation cannot prove runtime execution or distinguish
+an external name from an internal unit omitted everywhere. Follow the
+[semantic recovery guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#semantic-graph-validation-errors).
+
+If external targets such as `http_api` lose dependents after incremental
+extraction, check whether the installed Woods version includes B-193.
+The fix is available in Woods `2.0.0.beta3`; installing this plugin does not upgrade the gem.
+Affected indexes need one full extraction after upgrading to a fixed version.
+Follow the [recovery guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#external-dependency-targets-lose-dependents-after-incremental-extraction).
+
+For a custom shell/Python reader or upload gate, check its installed-version
+assumptions against the [filesystem layout contract](https://github.com/lost-in-the/woods/blob/main/docs/INDEX_LAYOUT.md).
+Resolve the pointer once and pin the manifest during a complete read/copy; never
+select the highest payload directory or treat a missing root graph as no index.
+Confirm the installed release and filesystem support retention locks before
+using the pinning examples; flat layouts need writers stopped for a consistent copy.
+
+A host reader can report a container daemon dead because foreign-host records
+are rejected by default. Foreign heartbeat trust (#321) is available in Woods `2.0.0.beta3`: first
+check the installed Woods version and that version's release notes. Only for a
+supporting version, offer `WOODS_WATCH_TRUST_FOREIGN_HOST=1` in every relevant
+task/MCP reader and follow [cross-host liveness](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#cross-host-liveness).
+Fresh `degraded` still means incremental work is needed; a fresh `running`
+record can outlive a crashed foreign daemon by up to 15 minutes. Older versions
+need their status check run in the daemon's own container.
+
+Writer-version provenance (#323) is available in Woods `2.0.0.beta3`: verify the installed
+gem version's release notes before expecting it. If `index.woods_version` exists, compare it
+with `server.version`; missing/null is unknown, not a failure. A validator
+major-version warning calls for full extraction and upgrade review, while a match
+does not certify retained units were migrated. See [writer provenance](https://github.com/lost-in-the/woods/blob/main/docs/PUBLISHED_INDEX.md#manifest-writer-provenance).
+
+Unreleased after `2.0.0.beta3`: incremental/refresh handled source errors keep
+the previous generation active and leave watch batches pending. Repair the
+logged source error and retry the complete batch; see
+[handled source errors](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md#handled-source-errors-and-retry).
+Check the installed revision before relying on this behavior.
+
 If a one-shot extraction raises `Could not publish generation`, the candidate
 payload was written but never made visible; readers still serve the previous
 complete generation. Fix the named filesystem, permission, space, or mount
 failure and rerun the same task. Never edit `generation.json` or point a reader
 at the unreachable payload by hand.
 
+For slow extraction, use `WOODS_PROFILE=1` when supported by the installed
+version. Keep process boot and resident-cycle measurements separate. Older
+profiles nest payload sync and retention inside `publish`; current source
+reports disjoint phases and a separate `[profile total]` line. Do not add
+whole-run totals to phase durations or promise the new lines on an older gem.
+Use the installed version's tagged guide; the
+[canonical profiling guide](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md#profiling-fixed-costs)
+tracks current source.
+
+For volatile-dependency reports dominated by one target, compare the full
+`stats.volatile_dependency_count` with the persisted array and use the
+[ratio tuning guidance](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#pipeline-options).
+The optional per-target cap (B-188) is available in Woods `2.0.0.beta3`; check the
+installed gem before suggesting `volatile_dependency_limit_per_target`.
+Re-extract to publish configuration changes; the report remains informational.
+
+For a shallow-checkout git-enrichment warning, the shallow guard (B-189) is
+available in Woods `2.0.0.beta3`; check the installed version first. Fetch complete
+history with `git fetch --unshallow` or `actions/checkout` `fetch-depth: 0`, then
+run full extraction. Depth two only enables a two-commit diff; it does not
+restore complete churn history. See the
+[git metadata recovery guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-metadata-is-missing-or-shows-zeros).
+
+For `Git enrichment omitted: history could not be read completely`, first check
+whether the installed Woods release documents the new streamed-history policy;
+it is available in Woods `2.0.0.beta3`. Supporting versions require Git 2.31 or newer.
+Check `git --version` in the extraction container and repository/object-store
+access with its `WOODS_GIT_DIR` setting. A failed history stream is discarded;
+repair git access and run full extraction to refresh retained metadata. See the
+[history contract](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#git-enrichment-history).
+
+After a bundle change or removal of a dynamically defined job, incremental
+extraction can retain stale runtime units. Use a fresh process with the updated
+bundle for full extraction, then validate. For missing external gem paths,
+first distinguish an upgraded bundle from a reader on a different host/mount.
+The more explicit `woods:validate` bundle-update remedy (B-166) is available in Woods
+`2.0.0.beta3`; the full-extraction recovery works on older versions too.
+See [runtime removals and bundle updates](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md#runtime-removals-and-bundle-updates).
+
+### Export identity checks
+
+For Notion or Unblocked exports, typed selection checks (#213) are available in Woods
+`2.0.0.beta3`; check the installed gem before expecting them. A missing or
+mismatched export identity calls for index validation and a fresh extraction,
+not a force flag. An `ambiguous export URI` means two types share an identifier
+and source file: preserve existing documents and report the collision; do not
+rename public identifiers or force deletion. Follow the canonical
+[Notion](https://github.com/lost-in-the/woods/blob/main/docs/NOTION_INTEGRATION.md#sync-manifest-incremental-sync)
+and [Unblocked](https://github.com/lost-in-the/woods/blob/main/docs/UNBLOCKED_INTEGRATION.md#uri-scheme)
+guides for recovery and current limitations.
+
 ## 3. Check the MCP process and path
 
 Compare the client config with the exact command, absolute `cwd`, bundle, and index path visible to that process. Run the configured executable manually to read stderr. For a host bundle:
@@ -46,13 +205,71 @@ Compare the client config with the exact command, absolute `cwd`, bundle, and in
 bundle exec woods-mcp-start ./tmp/woods
 ```
 
+If startup says `Could not resolve a published Woods index` (unreleased after
+`2.0.0.beta3`) or names a missing `manifest.json` on older versions, first check
+the selected index path: an atomic index uses `generation.json` to locate its
+payload manifest. The new headline does not change index validation or recovery.
+Point at an existing index before suggesting a new extraction. Prefer the
+explicit path above; `WOODS_DIR` is also supported. An unreleased change after
+`2.0.0.beta3` adds `WOODS_OUTPUT` after those two choices, so verify the installed
+version's configuration guide before relying on that fallback.
+
 Then reconnect through the MCP client and call `woods_status`. Use client-native tool inspection after initialization. Expect 14 packaged Index tools, not all conditional schemas.
 
 For Docker-only bundles, test the configured container command instead, for example `docker compose exec -T app bundle exec woods-mcp /app/tmp/woods`. Use the container path for a container process and a host path only for a host process.
 
+For corrupt pipeline cooldown state, first confirm this is a custom server
+with `pipeline_repair` registered; packaged `woods-mcp` does not wire it.
+Recovery through `reset_cooldowns` (B-159) is available in Woods `2.0.0.beta3`.
+Check the installed version before attempting it and follow the
+[corrupt cooldown recovery guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#corrupt-pipeline-cooldown-state).
+
+## Deferred refresh hooks
+
+Expanded hook coverage and `woods:hook_refresh` (#408) are available in Woods
+`2.0.0.beta3`. Verify the installed task through the configured host/container
+command before diagnosing this plugin's queue. Read `<output>/hook.log` and
+`hook-pending/`; status 75 means an active daemon deferred work, not that it was
+consumed. Fix task availability, boot/publication failures or a stalled command,
+then retry with the same output and command prefix. Preserve pending events.
+For mkdir fallback locks, inspect the recorded owner PID before manual removal.
+The concurrent dead-owner recovery fix is included in plugin `2.3.36`.
+If competing hooks leave an empty lock without a drain, preserve the queued
+events and follow the canonical recovery guide below.
+A Docker timeout does not prove the application process stopped. Prefer a
+resident watcher for sustained edits and follow the
+[canonical retry guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#hooks-for-agent-sessions).
+
+## Partial dependency answers
+
+Traversal budgets (`max_nodes`/`max_edges`, #311) are available in Woods `2.0.0.beta3`.
+Check the installed gem version and connected tool schema before
+using them; installing this plugin does not upgrade the gem. On a supporting
+server, `partial`/`partial_reason` means the walk stopped early, independently
+of page truncation. Do not claim an exhaustive blast radius or treat empty
+deps as proof of a leaf. Narrow depth/types/via or increase a supported budget;
+paging alone only visits the discovered prefix. See the
+[budget contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#dependency-traversal-budgets).
+
 ## 4. Check semantic retrieval
 
-Only diagnose this layer when structural tools work and `codebase_retrieve` fails. Check `woods_status`, configured provider/model/vector store, provider reachability, and whether `woods:embed` completed.
+Configured retrieval defaults (#446) are available in Woods `2.0.0.beta3`. For an installed
+version that supports them, an omitted tool budget uses the serving retriever's
+configured default; an explicit budget overrides it. Standalone MCP does not
+inherit the host initializer's token setting from the embedding snapshot.
+Do not tune relevance with similarity_threshold: it is inert and deprecated.
+Use query/type/scope selection and inspect ranking evidence instead. See
+[retrieval tuning](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#tuning).
+
+Native embedding completeness checks (#442/#444) are available in Woods `2.0.0.beta3`;
+confirm the installed version first. If embedding reports `Embedding input
+incomplete`, repair the named published extraction artifact or rebuild extraction
+before retrying. Do not use `WOODS_ALLOW_PURGE=1` to bypass an integrity failure;
+it only permits intentional mass deletion. Source-empty units deliberately retain
+metadata without vectors. See the canonical
+[input-integrity guide](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#input-integrity-and-source-empty-units).
+
+Only diagnose this layer when structural tools work and `codebase_retrieve` fails. If a no-provider message recommends only embeddings or `search`, check the lexical capability below: beta3 supports explicit `WOODS_RETRIEVAL_MODE=lexical` even though that error omits it. Put the setting in the MCP process environment and restart; never silently change retrieval modes. First check `woods_status.retriever.mode`. For lexical mode, validate the published extraction index and follow the capability check below. For semantic mode, check the configured provider/model/vector store, provider reachability, and whether `woods:embed` completed.
 
 - OpenAI: verify the key exists without printing it.
 - Ollama: verify the service and configured model locally.
@@ -60,12 +277,29 @@ Only diagnose this layer when structural tools work and `codebase_retrieve` fail
 - Dimension mismatch: rebuild into a store matching the configured model; do not suppress the preflight.
 - Purge guard: back up and inspect the proposed deletion; never set `WOODS_ALLOW_PURGE` without explicit approval.
 
+For metadata appearing in another index or worktree, compare `WOODS_OUTPUT`,
+`config.output_dir`, and any explicit `metadata_store_options[:database]`.
+The default SQLite path following `WOODS_OUTPUT` during embedding (B-156) is
+available in Woods `2.0.0.beta3`; check the installed version before relying on it.
+An explicit database path still wins. See the
+[SQLite path contract](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#sqlite-metadata)
+for isolation and upgrade steps.
+
 ## 5. Check Console separately
 
+For repeated missing-token boot warnings on a stdio-only host, check whether
+its installed version supports `console_mcp_http_enabled = false` before
+suggesting it; this option is available in Woods `2.0.0.beta3`. The default
+preserves HTTP enablement, so selecting stdio as a client alone does not
+suppress HTTP token validation. Never disable authentication on an HTTP
+endpoint to silence this warning.
+
 Console failures are live Rails/config/security failures, not Index failures. Verify authorized environment, Rails boot, `WOODS_CONSOLE_CONFIG` or direct `cwd`, blocked-table policy, credentials, and stderr.
 
 For MySQL SQL refusals, inspect the executing session's `sql_mode` and the installed version's Console guide. Do not change quote modes to bypass a security refusal.
 
+For SQLite SQL refusals on `2.0.0.beta4` or a reviewed revision containing its Console corrections, consult the installed Console guide for supported identifier and table-reference syntax. Simplify the query to supported syntax; never relax the blocked-table or function policy. These builds also check resolved default scopes and scan normalized response values. Confirm a patched gem is published before recommending it, and check the installed version’s canonical Console guide; do not infer release availability from this plugin.
+
 Nine tools are normal. Eleven appear only with `console_embedded_read_tools`. Do not chase Tier 2/3 or `console_eval`; they do not register in supported packaged modes. Never work around redaction, credential scanning, SQL validation, or a block.
 
 ## Report
@@ -73,3 +307,87 @@ Nine tools are normal. Eleven appear only with `console_embedded_read_tools`. Do
 Return the first failing layer, commands/evidence, root-cause hypothesis, whether any file changed, and the smallest next action. If a fix is requested, change one thing and rerun the failing check before proceeding.
 
 Canonical guide: [TROUBLESHOOTING.md](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md).
+
+## Lexical retrieval capability check
+
+Lexical retrieval is available from `2.0.0.beta3`. Before proposing it, verify the installed gem
+exposes `Woods::Configuration#retrieval_mode` and its matching guide documents
+`WOODS_RETRIEVAL_MODE`. Keep the installed-version preflight; do not infer support
+from the plugin version or an unreleased checkout.
+
+For lexical errors, inspect the published generation and validate or re-extract
+the index; adding provider credentials cannot repair a corrupt lexical index.
+Semantic provider failure never switches to lexical automatically.
+See the [retrieval guide](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval)
+for the supported contract, checked against the installed gem version.
+
+## Explicit package or path scope
+
+Check the connected tool's advertised input schema before sending `packages` or
+`source_paths`; older installed gems may not support them. When present, both
+`search` and `codebase_retrieve` apply explicit scope before candidate limits.
+Use published nearest package names or application-relative directory prefixes,
+then inspect `applied_scope` and search completeness. Unknown packages are argument
+errors; unsupported custom vector adapters degrade instead of running a global
+query. Scoping can hide relevant cross-boundary relationships, so broaden the
+request deliberately when the task needs them. See the
+[scope contract](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#explicit-package-and-source-path-scopes).
+
+## Source-content freshness (Woods 2.0.0.beta3; #405)
+
+Check installed-version support before using `woods-extract` or the optional
+`woods_status.source_check` argument. With support, inspect
+`index.source_freshness`: `current`, `drifted` or `unknown`. Repeated edits to an
+already-dirty file can leave the porcelain fingerprint unchanged. A quick scan
+limit may justify one `source_check: "deep"`; unavailable source/private keys or
+unproved boot/consumer coverage remain unknown. A fresh `bundle exec woods-extract full`
+inside the application environment establishes preboot evidence. Never publish
+`.source-inputs.key`, silently change its permissions, or delete queued edits to
+hide diagnostics. Follow [source freshness](https://github.com/lost-in-the/woods/blob/main/docs/SOURCE_FRESHNESS.md).
+
+## Compact evidence capability check
+
+Inspect the connected server's installed tool schemas before using `evidence` on
+`lookup` or `codebase_retrieve`; older releases do not provide these controls.
+When available, explicit `compact` selects complete published source spans and
+`outline` lists declared APIs. Read omission/provenance fields and follow the
+returned typed, SHA-guarded `full_evidence` lookup for verification. Published-unit
+coordinates are not physical file offsets; unknown generation remains unknown.
+Keep full-source access available. See the canonical
+[evidence contract](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#compact-published-evidence-and-api-outlines).
+
+## Explicit edit adapters (Woods 2.0.0.beta3; #409)
+
+Check the installed gem exposes `woods:hook_refresh` before enabling hooks.
+Claude's registered wrapper covers one documented edit path; OpenCode 1.18.27
+has a separate native `.js` registration wrapper importing Woods' shipped
+adapter. Its verified patch metadata carries all added/updated/deleted/moved
+paths. Keep the complete plugin directory available, preserve opt-in/disable
+settings and pending events, and inspect the generation and hook log before
+claiming refresh. Unsupported tool shapes and symlink paths need watch or an
+explicit extraction. Do not install native client registration without the
+user's setup request. Follow [client hooks](https://github.com/lost-in-the/woods/blob/main/docs/CLIENT_HOOKS.md).
+
+## Optional context hints
+
+Check installed `bundle exec woods-hook-context --help` before enabling
+`WOODS_HOOK_CONTEXT_ENABLED=1`; this capability is available in Woods `2.0.0.beta3` and the
+plugin does not upgrade the gem. Context and refresh opt-ins are independent;
+`WOODS_HOOKS_DISABLED=1` disables both. Native Claude context is synchronous and
+bounded, with served-generation and pre-refresh/unknown labels. Verify candidate
+dependents and suggested tests manually; silence is not no impact. Do not clear
+refresh queues when optional hints time out. See the canonical
+[context guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#optional-bounded-context-hints)
+for output/time limits, container root mapping and emitted-hint suppression.
+
+### Obsidian destination conflicts
+
+Destination ownership preflight (#441) is available in Woods `2.0.0.beta3`; first check
+the installed Woods version and
+its matching guide. On versions with this check, `refusing <path>: unmanaged or modified destination`
+means the export preserved a conflicting note, setting, or sidecar and skipped the stale-note sweep.
+A `.woods-vault` sentinel or force-purge flag does not authorize overwriting it. Inspect and back up
+the named file before moving it aside, or choose a new export directory. Older vaults can adopt
+byte-identical generated assets into `_woods/ownership.json`; changed legacy sidecars may need this
+manual recovery. Never fabricate ownership receipts or remove personal files to silence the error.
+See the installed version's `docs/OBSIDIAN_INTEGRATION.md` for the exact safety contract.

data/plugin/skills/woods-investigate/SKILL.md

@@ -9,6 +9,13 @@ Woods is runtime evidence: resolved routes, schema, associations, callbacks, inl
 
 ## Preflight
 
+Supporting servers include concise MCP initialization/discovery guidance without
+this plugin. That feature (#402) is available in Woods `2.0.0.beta3`; check the
+installed server version, and do not require it from protocol `2024-11-05`.
+Follow the [agent guide](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_GUIDE.md)
+when instructions are absent. A registered tool does not establish retrieval
+readiness or authorize maintenance or live Console access.
+
 Call `woods_status` before relying on the index. Require a ready index with a current generation and non-zero counts for the types you need; use `codebase_retrieve` only when status reports retrieval enabled. If status is unhealthy or the generation predates the code under review, report that and ask the owner to run `woods:incremental` or `woods:extract` — do not present "not found" as proof the code does not exist.
 
 ## The default loop
@@ -32,8 +39,146 @@ Identifiers are namespaced and typed; never invent one from a filename when `sea
 
 The normal packaged Index Server registers 14 tools; conditional schemas register only when their wiring is configured — use the connected server's own tool list, never the source inventory. Console MCP is authorized live-data access, not another code-search mode; use Index tools for structure. Never work around a block, validation error, or redaction.
 
+## Partial search answers
+
+Search completeness (#410) is available in Woods `2.0.0.beta3`. Verify the installed
+server version and response before relying on it; this plugin does not upgrade
+the gem. On supporting versions, `result_count` counts returned rows, while
+`completeness.reason: exhausted` establishes an exact total for the requested
+index/query domain. `result_limit` proves at least one additional match;
+`scan_budget` and `regex_timeout` leave more matches and totals unknown. Narrow
+types, literal prefix/suffix filters, or deep fields when `partial` is true.
+Artifact errors have unknown completeness. Missing metadata on older servers,
+a full page, and an empty partial result never establish exhaustive absence.
+See the [search contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#search-completeness).
+
+## Graph coverage
+
+Dependency tools report published relationships, not exhaustive source-reference
+or call coverage. Selective method-body scanning can miss references to generic
+PORO and library targets. No dependents or test-only dependents do not establish
+absence of production callers; check source before making that claim.
+
+The response `graph_coverage` notice, `total_is_exact` field, and human label
+`witness types unambiguous` (#470/#471) are unreleased after Woods `2.0.0.beta3`.
+Verify the installed server version and actual response fields; this plugin does
+not add them. Apply these limits to older servers even without the notice.
+Supporting stdio and HTTP servers expose the paginated traversal payload in
+`structuredContent.data` independently of the text renderer (#481, also
+unreleased after `2.0.0.beta3`). Check the installed response; older default
+responses may carry only text. Do not pass an unsupported `format` argument.
+
+`total_is_exact: false` means a budget-limited prefix; a true value describes only
+the requested root, depth, filters and published generation. Pagination alone
+does not change exactness. On older responses inspect `partial` directly.
+Treat partial `nodes_total` as a root-inclusive lower bound, including on the
+last page, an empty page or an unpaged answer. See the
+[coverage contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#dependency-graph-coverage).
+
+## Partial dependency answers
+
+Traversal budgets (`max_nodes`/`max_edges`, #311) are available in Woods `2.0.0.beta3`.
+Check the installed gem version and connected tool schema before
+using them; installing this plugin does not upgrade the gem. On a supporting
+server, `partial`/`partial_reason` means the walk stopped early, independently
+of page truncation. Do not claim an exhaustive blast radius or treat empty
+deps as proof of a leaf. Narrow depth/types/via or increase a supported budget;
+paging alone only visits the discovered prefix. See the
+[budget contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#dependency-traversal-budgets).
+
+## Explain recorded relationships
+
+`explain: true` on `dependencies`/`dependents` (#414) is available in Woods `2.0.0.beta3`.
+Verify the installed gem and connected tool schema before using it;
+installing this plugin does not add server capabilities. Supporting servers
+preserve original source-to-target direction and labels in both traversal
+modes. Follow shared `parent`/`edge_id` witnesses, distinguish direct records
+from transitive inferred impact, and treat `context: true` ancestors as page
+context. Null attributes and candidate type ambiguities remain unknown;
+`typed_path_complete: false` never establishes a uniquely typed path; true means
+only that witness identities have unambiguous types, not complete source coverage.
+Budget
+cutoffs still apply. Verify important conclusions in source and tests, since
+recorded reachability does not establish observed execution. See the
+[explanation contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#traversal-explanations).
+
+## Graph-analysis pages
+
+Pass explicit `limit` and `offset` when paging `graph_analysis`. Enforcing the
+advertised default of 20 rows per section and preserving total/offset on last
+and empty pages (#519) are unreleased after `2.0.0.beta3`; check the installed
+response rather than inferring support from the plugin version. On supporting
+servers, read `<section>_total` and `<section>_offset` in JSON, or the human
+pagination notice. An empty later page does not mean no findings. Totals count
+the published report array, which may already be bounded during extraction.
+See the [page contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#graph-analysis-pages).
+
+## Volatile dependency reports
+
+Read `stats.volatile_dependency_count` before judging the top-20 array: it
+counts all qualifying edges. A frequently changed dependency can occupy most
+rows. Use the installed version's ratio tuning guidance; the optional
+`volatile_dependency_limit_per_target` setting (B-188) is available in Woods
+`2.0.0.beta3`, so verify gem support before recommending it. Supporting versions
+can cap each typed target before selecting the global top 20 and expose the
+cap plus `volatile_dependency_reported_count` in stats. Re-extract after
+configuration changes. Treat the report as candidates for source review, never
+an automatic gate. See the
+[configuration reference](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#pipeline-options).
+
 ## Report evidence
 
 Name the tools and exact identifiers used, cite the source paths Woods returned, separate direct Woods evidence from inference, and state generation/staleness caveats. Say when a claim still needs source or test verification.
 
 Canonical guides: [AGENT_GUIDE.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_GUIDE.md), [MCP_TOOL_COOKBOOK.md](https://github.com/lost-in-the/woods/blob/main/docs/MCP_TOOL_COOKBOOK.md).
+
+## Lexical retrieval capability check
+
+This is a development capability. Before proposing it, verify the installed gem
+exposes `Woods::Configuration#retrieval_mode` and its matching guide documents
+`WOODS_RETRIEVAL_MODE`. Keep the installed-version preflight; do not infer support
+from the plugin version or an unreleased checkout.
+
+When status reports lexical mode, use the matching fields/terms as discovery
+evidence and verify key units with `lookup`. At most 20 eligible matching
+candidates are considered; fewer source entries may fit the budget. This is not
+exhaustive, and no lexical match does not establish absence. When the installed
+server reports considered/included counts, compare them; older versions may
+only describe the shortlist limit. Continue using `budget`, not `limit`.
+See the [retrieval guide](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval)
+for the supported contract, checked against the installed gem version.
+
+## Explicit package or path scope
+
+Check the connected tool's advertised input schema before sending `packages` or
+`source_paths`; older installed gems may not support them. When present, both
+`search` and `codebase_retrieve` apply explicit scope before candidate limits.
+Use published nearest package names or application-relative directory prefixes,
+then inspect `applied_scope` and search completeness. Unknown packages are argument
+errors; unsupported custom vector adapters degrade instead of running a global
+query. Scoping can hide relevant cross-boundary relationships, so broaden the
+request deliberately when the task needs them. See the
+[scope contract](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#explicit-package-and-source-path-scopes).
+
+## Compact evidence capability check
+
+Inspect the connected server's installed tool schemas before using `evidence` on
+`lookup` or `codebase_retrieve`; older releases do not provide these controls.
+When available, explicit `compact` selects complete published source spans and
+`outline` lists declared APIs. Read omission/provenance fields and follow the
+returned typed, SHA-guarded `full_evidence` lookup for verification. Published-unit
+coordinates are not physical file offsets; unknown generation remains unknown.
+Keep full-source access available. See the canonical
+[evidence contract](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#compact-published-evidence-and-api-outlines).
+
+## Optional context hints
+
+Check installed `bundle exec woods-hook-context --help` before enabling
+`WOODS_HOOK_CONTEXT_ENABLED=1`; this capability is available in Woods `2.0.0.beta3` and the
+plugin does not upgrade the gem. Context and refresh opt-ins are independent;
+`WOODS_HOOKS_DISABLED=1` disables both. Native Claude context is synchronous and
+bounded, with served-generation and pre-refresh/unknown labels. Verify candidate
+dependents and suggested tests manually; silence is not no impact. Do not clear
+refresh queues when optional hints time out. See the canonical
+[context guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#optional-bounded-context-hints)
+for output/time limits, container root mapping and emitted-hint suppression.