woods 2.0.0.beta3 → 2.0.0

data/lib/woods/watch/supervisor_reporting.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Woods
+  module Watch
+    # Publication and retirement of one launcher's diagnostic records.
+    module SupervisorReporting
+      private
+
+      def publish(state, reason, **details)
+        return unless state
+
+        reason ||= 'pending'
+        changed = @state != state || @reason != reason
+        @state = state
+        @reason = reason
+        @details = details
+        @logger.puts("[woods-watch] #{state}: #{reason || 'pending'} (attempt #{@attempts})") if changed
+        heartbeat(force: true)
+      end
+
+      def heartbeat(force: false)
+        return unless @status && heartbeat_due?(force)
+
+        @status.write(state: @state, reason: @reason, attempt: @attempt,
+                      child_pid: @process&.alive? ? @protocol.child_pid : nil, **(@details || {}))
+        @heartbeat_at = monotonic
+      rescue SystemCallError, ArgumentError => e
+        @logger.puts("[woods-watch] cannot write supervision status (#{e.class})")
+        @heartbeat_at = monotonic
+      end
+
+      def heartbeat_due?(force)
+        force || !@heartbeat_at || monotonic - @heartbeat_at >= 5
+      end
+
+      def retire_status
+        @status&.write(state: 'stopped', reason: 'attempt_finished', attempt: @attempt, child_pid: nil)
+      rescue SystemCallError, ArgumentError => e
+        @logger.puts("[woods-watch] cannot retire supervision status (#{e.class})")
+      ensure
+        @status = nil
+        @heartbeat_at = nil
+      end
+    end
+  end
+end

data/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "woods-plugin",
   "description": "Woods user guides for Claude Code: set up, upgrade, configure MCP servers for, investigate codebases with, enable a repository's agents on, and diagnose the Woods Rails code-intelligence gem.",
-  "version": "2.3.36",
+  "version": "2.3.54",
   "author": {
     "name": "lost-in-the"
   },

data/plugin/hooks/woods-input-rules.sh

@@ -75,10 +75,6 @@ woods_input_action() {
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return
   fi
-  if { { { [[ "$path" == *.rake ]]; } && { [[ "$path" == lib/tasks/* ]]; }; }; }; then
-    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
-    return
-  fi
   if { { { [[ "$path" == *.html.erb ]] || [[ "$path" == *.erb ]]; } && { [[ "$path" == app/views/* ]]; }; }; }; then
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return
@@ -115,6 +111,10 @@ woods_input_action() {
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return
   fi
+  if { { { [[ "$path" == *.rake ]]; } && { [[ "$path" == lib/tasks/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
   if { [[ "$path" == config/routes.rb ]] || { { [[ "$path" == config/routes/* ]]; }; }; }; then
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return

data/plugin/skills/woods-agent-enable/SKILL.md

@@ -9,7 +9,7 @@ Installing the gem gives one operator an index; this skill gives every future ag
 
 ## Managed configuration availability
 
-`woods-agent-config` (#407) is unreleased after `2.0.0.beta2`. First record the
+`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
@@ -20,6 +20,12 @@ journals contain private configuration bytes. See the canonical
 for host/Compose preflight, actual Claude file locations, conflict recovery,
 and removal. Preserve manual setup for older installed versions.
 
+For concurrent configuration operations, wait for the active operation to
+finish and generate a fresh plan if the saved snapshots changed. Do not remove
+its lock or overwrite the other application's entry. Coordination across
+applications sharing user configuration is included in Woods `2.0.0`;
+check the installed revision before relying on it.
+
 ## Preflight
 
 Confirm Woods actually works before advertising it to every future session:

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

@@ -16,7 +16,7 @@ This skill describes the Woods 2.x line; the authoritative minimum version lives
 
 ## Managed configuration availability
 
-`woods-agent-config` (#407) is unreleased after `2.0.0.beta2`. First record the
+`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
@@ -36,19 +36,63 @@ 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.
 
+### Watcher setup cannot find already installed Rails or dependencies
+
+Compare normal task discovery with installer preflight in the same container and
+application environment. Early Git builds of the watcher installer stripped
+`BUNDLE_PATH` and `BUNDLE_APP_CONFIG`; Woods `2.0.0` includes the #540 fix.
+Record the loaded revision and bundle configuration source before
+reinstalling dependencies or writing a local bundle-path workaround. Follow the
+[watcher installation guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#managed-development-startup).
+
+### Puma cannot load the Woods plugin after switching branches
+
+Early generated guards checked only whether Woods was activated. An older gem
+can satisfy that check without providing `puma/plugin/woods.rb`. The #542 fix is
+included in Woods `2.0.0`: verify the loaded revision, then use a supporting
+bundle to preview and apply `bin/rails generate woods:watch --operation update
+--mode puma`. The updated guard checks the active gem's require paths, so older
+gems boot without a watcher. Repeating setup does not upgrade the guard. Follow
+the [owned setup runbook](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#ownership-updates-and-removal);
+do not change the owned directive or receipt manually.
+
 ### Watch repeatedly exits 75
 
+First identify the lifecycle owner. The raw task deliberately exits 75; a bare
+Foreman entry then stops all services. Managed `woods-watch`/Puma setup (#538)
+is included in Woods `2.0.0`: verify installed executable/generator help and
+loaded revision before proposing it. Supporting launchers retry boot failures,
+reject idle TTL, and park ownership/protocol conflicts until owner restart.
+Inspect separate supervision state rather than treating its parent PID as a
+healthy daemon. Before the first resolved index path, use launcher logs.
+Do not remove claims or kill PIDs from status to force takeover. See
+[startup diagnosis](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#watcher-startup-or-planned-restart-fails).
+
 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
+the application's actual `rails woods:watch` or `rake woods:watch` entrypoint,
+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. In Woods `2.0.0`, 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
+
+In Woods `2.0.0`, `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 unreleased.
+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.
@@ -58,8 +102,8 @@ 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
+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
@@ -72,7 +116,7 @@ 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
+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
@@ -82,7 +126,7 @@ 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
+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,
@@ -95,7 +139,7 @@ an external name from an internal unit omitted everywhere. Follow the
 
 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.
+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).
 
@@ -107,7 +151,7 @@ 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
+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).
@@ -115,12 +159,18 @@ 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
+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).
 
+Included in Woods `2.0.0`: 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
@@ -139,12 +189,12 @@ 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
+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
-unreleased after `2.0.0.beta2`; check the installed version first. Fetch complete
+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
@@ -152,24 +202,42 @@ restore complete churn history. See the
 
 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.
+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).
 
+If per-unit Git metadata is absent, check `git --version` inside the extraction
+process/container as well as repository access. Builds with #551 warn when Git
+cannot execute and a repository is expected; older versions may be silent.
+Source archives without a Git directory remain supported. `GIT_SHA` and
+structural `ready` do not certify history availability. After repairing Git,
+run full extraction; see the
+[missing-executable diagnostic](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-executable-is-missing-from-the-extraction-environment).
+
+For linked-worktree provenance/history mismatches, check the installed version's
+`WOODS_GIT_DIR` support and compare the selected branch and exact SHA inside the
+extraction environment. Mount the complete shared `.git` at its original path
+with no override, or select `/mounted-common/worktrees/<id>` within a relocated
+complete mount. Derive `<id>` from Git metadata, not the branch name. Selecting
+the shared root uses the primary checkout's HEAD and also changes incremental
+ranges. A commit alone may leave the source-file watcher idle; run full
+extraction after repair or when current Git history is required. See the
+[worktree mount guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
+
 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.
+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 unreleased
-after `2.0.0.beta2`; check the installed gem before expecting them. A missing or
+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
@@ -186,26 +254,35 @@ 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` (included in Woods
+`2.0.0`) 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. Woods `2.0.0` includes
+`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 unreleased after `2.0.0.beta2`.
+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 unreleased after
-Woods 2.0.0.beta2. Verify the installed task through the configured host/container
+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 unreleased after plugin 2.3.35.
+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
@@ -214,8 +291,8 @@ resident watcher for sustained edits and follow the
 
 ## 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
+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
@@ -225,7 +302,19 @@ paging alone only visits the discovered prefix. See the
 
 ## 4. Check semantic retrieval
 
-Configured retrieval defaults (#446) are unreleased after beta2. For an installed
+Do not treat structural `ready: true` or bootstrap `hydrated` as proof that
+embeddings exist. Check the installed reader's capabilities: builds with #549
+expose `woods_status.retriever.corpus`, including locally known vector and
+metadata record counts by type. Missing fields or `null` counts mean unknown,
+not zero. Counts include chunks and do not certify complete unit coverage.
+When both stores are known empty, supporting readers return `empty_index` with
+embed or explicit lexical-mode guidance. Follow the
+[corpus diagnostic contract](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
+Older readers need direct embedding-artifact checks; installing this plugin
+does not update the serving gem. Keep reader revision and index writer version
+separate when comparing results.
+
+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.
@@ -233,7 +322,7 @@ 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;
+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;
@@ -241,7 +330,7 @@ it only permits intentional mass deletion. Source-empty units deliberately retai
 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.
+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.
@@ -252,7 +341,7 @@ Only diagnose this layer when structural tools work and `codebase_retrieve` fail
 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.
+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.
@@ -261,15 +350,25 @@ for isolation and upgrade steps.
 
 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
+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 stdio parse errors or response mismatches during tool calls, check for Rails
+logs on stdout. Through Woods `2.0.0.beta4`, stdout is restored after boot;
+configure the Console process's logger to use stderr or a file. Runtime stdout
+isolation is included in Woods `2.0.0`: verify a patched installed revision
+before relying on it. Prefer `bundle exec rake woods:console`; direct Rails
+runner invocation cannot capture output already emitted during Rails boot.
+See the [Console logging diagnosis](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md#rails-logs-break-mcp-protocol).
+
 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
@@ -280,7 +379,7 @@ Canonical guide: [TROUBLESHOOTING.md](https://github.com/lost-in-the/woods/blob/
 
 ## Lexical retrieval capability check
 
-This is a development capability. Before proposing it, verify the installed gem
+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.
@@ -303,7 +402,7 @@ 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)
+## 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
@@ -326,7 +425,7 @@ 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)
+## 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
@@ -341,7 +440,7 @@ user's setup request. Follow [client hooks](https://github.com/lost-in-the/woods
 ## 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
+`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
@@ -352,7 +451,8 @@ 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
+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

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

@@ -10,13 +10,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
+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.
+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; verify the retrieval mode and its data before using `codebase_retrieve` (see Conceptual questions below). 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
 
@@ -31,9 +31,9 @@ Identifiers are namespaced and typed; never invent one from a filename when `sea
 
 - **Code review / change impact**: `lookup` the changed unit, then `dependents` at depth 1 before going deeper. Group results by relationship type and layer; report direct dependents separately from inferred downstream impact. A graph edge is not test coverage — select tests from mappings and repository search.
 - **Audit / architecture assessment**: `graph_analysis` for orphans, dead ends, hubs, cycles, bridges, cross-database edges, volatile dependencies, and undeclared package edges; `domain_clusters` for architectural domains; `pagerank` for high-impact units worth reading first.
-- **Investigating behavior / debugging**: `trace_flow` from the user-visible entry point (route, controller action, job, mailer, service), `lookup` at ambiguous steps, and verify anything conditional or dynamically dispatched in source and tests — do not infer call order from a dependency edge.
+- **Investigating behavior / debugging**: find the exact indexed unit with `search` and `lookup`, then use `trace_flow` with `UnitIdentifier` or `UnitIdentifier#method` (for example, `CheckoutService#order`). Bare `order` names a unit, potentially a factory, rather than locating an application method. Receiverless local calls may remain unexpanded; inspect their source or trace the owning unit's method explicitly. Flow output is not proof of runtime execution or exhaustive call coverage. See the [flow workflow](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_GUIDE.md#trace-a-feature-flow).
 - **Onboarding**: `structure` for the codebase overview, `lookup` and `dependencies`/`dependents` for a unit's neighborhood, and `domain_clusters` for the domain map, then the default loop on the units that matter.
-- **Conceptual questions**: `codebase_retrieve` when status says ready; govern with `budget` (never `limit`), then verify key units with `lookup`.
+- **Conceptual questions**: check retrieval mode and data before `codebase_retrieve`; structural `ready` alone does not establish semantic availability. On readers supporting #549, inspect `retriever.corpus`; missing or unknown counts require checking embedding artifacts. Govern with `budget` (never `limit`), then verify key units with `lookup`.
 
 ## Boundaries
 
@@ -41,7 +41,7 @@ The normal packaged Index Server registers 14 tools; conditional schemas registe
 
 ## Partial search answers
 
-Search completeness (#410) is unreleased after `2.0.0.beta2`. Verify the installed
+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
@@ -52,10 +52,33 @@ 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 included in Woods `2.0.0`.
+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
+included in Woods `2.0.0`). 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 unreleased in Woods
-2.0.0.beta2. Check the installed gem version and connected tool schema before
+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
@@ -65,25 +88,38 @@ paging alone only visits the discovered prefix. See the
 
 ## 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;
+`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. Budget
+`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 included in Woods `2.0.0`; 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 unreleased after
-2.0.0.beta2, so verify gem support before recommending it. Supporting versions
+`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
@@ -104,8 +140,11 @@ exposes `Woods::Configuration#retrieval_mode` and its matching guide documents
 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`.
+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.
 
@@ -135,7 +174,7 @@ Keep full-source access available. See the canonical
 ## 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
+`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