woods 2.0.0.beta1 → 2.0.0.beta3

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 unreleased after `2.0.0.beta2`. 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,45 @@ 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 misses edits under a shared directory alias
+
+Check the installed version: logical alias preservation (#445) is unreleased.
+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 unreleased after
+`2.0.0.beta2`; 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 unreleased after `2.0.0.beta2`; 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 +82,102 @@ 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 unreleased after `2.0.0.beta2`; 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 unreleased; 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 unreleased: 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 unreleased: 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).
+
 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 unreleased after 2.0.0.beta2; 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
+unreleased after `2.0.0.beta2`; 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 unreleased after 2.0.0.beta2. 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 unreleased
+after `2.0.0.beta2`; 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 unreleased
+after `2.0.0.beta2`; 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:
@@ -50,9 +190,58 @@ Then reconnect through the MCP client and call `woods_status`. Use client-native
 
 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 unreleased after `2.0.0.beta2`.
+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 unreleased after
+Woods 2.0.0.beta2. 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 unreleased after plugin 2.3.35.
+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 unreleased in Woods
+2.0.0.beta2. 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 unreleased after beta2. 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 unreleased after beta2;
+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. 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,8 +249,23 @@ 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
+unreleased after `2.0.0.beta2`; 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 unreleased in Woods 2.0.0.beta2. 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.
@@ -73,3 +277,86 @@ 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
+
+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.
+
+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 (unreleased #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 (unreleased #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 unreleased after beta2 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 unreleased; 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 unreleased after `2.0.0.beta2`; 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,107 @@ 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 unreleased after `2.0.0.beta2`. 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).
+
+## Partial dependency answers
+
+Traversal budgets (`max_nodes`/`max_edges`, #311) are unreleased in Woods
+2.0.0.beta2. 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 unreleased after
+2.0.0.beta2. 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. 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).
+
+## 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 unreleased after
+2.0.0.beta2, 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`. The ranked top 20 is not exhaustive;
+no lexical match does not establish absence. 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 unreleased after beta2 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.

data/plugin/skills/woods-mcp-config/SKILL.md

@@ -5,6 +5,19 @@ description: Configure Woods MCP connections with the exact client JSON shapes a
 
 # Woods MCP configuration
 
+## Managed configuration availability
+
+`woods-agent-config` (#407) is unreleased after `2.0.0.beta2`. 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.
+
 ## Preflight
 
 ```bash
@@ -17,6 +30,15 @@ This skill describes the Woods 2.x line; the authoritative minimum version lives
 
 Default to Index-only. It reads generated code context and exposes 14 tools. Console MCP boots Rails and reads live data; ask before enabling it.
 
+Initialization guidance (#402) is unreleased after `2.0.0.beta2`; check the
+installed gem before expecting MCP `instructions`. Supporting servers provide
+a short workflow through initialization or modern discovery; protocol
+`2024-11-05` omits it. Missing instructions alone are not a connection failure.
+Keep normal protocol negotiation and use the
+[agent guide](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_GUIDE.md)
+when unavailable. See the
+[initialization contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#initialization-guidance).
+
 ## Shape 1: Index-only
 
 ```json
@@ -33,6 +55,11 @@ Default to Index-only. It reads generated code context and exposes 14 tools. Con
 
 Use this shape for any stdio-capable MCP client, adapted to the client's configuration location. `woods-mcp-start` validates and launches; it does not install or auto-restart.
 
+Writer-version provenance (#323) is unreleased; check the installed gem version's
+release notes before expecting `index.woods_version` in `woods_status`. It reports
+the last manifest publisher, independently of `server.version`. Treat missing/null
+as unknown and see [writer provenance](https://github.com/lost-in-the/woods/blob/main/docs/PUBLISHED_INDEX.md#manifest-writer-provenance).
+
 When Woods is installed only in Docker, prefer running the server through the application container:
 
 ```json
@@ -51,6 +78,12 @@ Use a host-side bundle only after verifying Ruby, the application bundle, and th
 
 A read-only index mount is sufficient for structural tools. The `reload` tool for in-memory semantic retrieval also takes Woods' shared on-disk writer lock, so the MCP process needs write access to the index directory. Without it, reload returns a typed degraded error and keeps serving the previous aligned generation. Either grant that access or restart the MCP process after publishing a new embedded index.
 
+For host MCP reading a container daemon's shared index, foreign heartbeat trust
+(#321) is unreleased. Verify the installed gem version's release notes before
+offering `WOODS_WATCH_TRUST_FOREIGN_HOST=1` in the MCP environment. It makes
+`woods_status.watch.alive` use the same bounded freshness policy as task readers;
+see [cross-host liveness](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#cross-host-liveness).
+
 ## Shape 2: Index plus authorized Console
 
 After explicit authorization, enable the live-data master switch in the Rails initializer. The process exits while it remains false:
@@ -62,7 +95,14 @@ Woods.configure do |config|
 end
 ```
 
-The token authenticates HTTP requests and is not sent by a stdio client. Production Rails boot still requires `WOODS_CONSOLE_MCP_TOKEN` to contain at least 32 characters whenever Console is enabled, including for a stdio-only setup. Keep it in the application's secret store. Outside production, omitting it warns and leaves the Console HTTP endpoint guarded with 401.
+The token authenticates HTTP requests and is not sent by a stdio client.
+Before suggesting `console_mcp_http_enabled = false`, verify that the installed
+version supports it: the option is unreleased in Woods 2.0.0.beta2. Supported
+stdio-only hosts can set it to `false` and omit the HTTP token; existing
+versions require the token at production boot whenever Console is enabled.
+For HTTP, retain a strong token, allowed origins and TLS. Use installed-version
+tagged documentation; the [canonical Console guide](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md)
+tracks current source.
 
 Then add a direct Console process:
 
@@ -99,3 +139,51 @@ Reconnect through the client so it performs its supported MCP negotiation. Clien
 Do not use an isolated raw JSON-RPC request as proof of MCP health. Do not claim conditional Index or inventory-only Console schemas are callable.
 
 Canonical guide: [MCP_SERVERS.md](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.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 supported, put `WOODS_RETRIEVAL_MODE=lexical` in the environment of the
+process launching Index MCP (stdio or HTTP). A Rails initializer alone is not
+loaded by that process. Confirm `woods_status.retriever.mode` reports `lexical`.
+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 (unreleased #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).