woods 2.0.1 → 2.1.0

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

@@ -77,6 +77,28 @@ 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.
 
+### Managed watcher parks after its owning container disappeared
+
+The explicit lease-based recovery command (#591) is unreleased after `2.0.0`.
+Check the loaded revision and `bundle exec woods-watch --help` before using it.
+Supporting daemons write a claim token and hold a lifetime lease; recovery checks
+the exact selected token and a free matching lease. Use the installed version's
+[claim recovery procedure](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#managed-development-startup).
+Never remove a claim or lock sidecar manually, infer death from age alone, or use
+recovery against a live supervisor. Legacy/unverifiable claims cannot use this
+command. Recovery leaves status and pending work intact; remove the reader-only
+foreign-host trust override from owner startup. Blank idle timeouts are also
+normalized by supporting builds; older tasks may reject an empty value.
+
+### Verified extraction selects the wrong output or cannot use its identity key
+
+In supporting #591 builds (unreleased after `2.0.0`), an implicit preboot output
+that disagrees with finalized Rails configuration refuses before publication.
+Pass matching `--output` or `WOODS_OUTPUT` explicitly and retain the same capture,
+key and writer destination. Read the safe key-path/ownership/permissions diagnosis;
+never rotate or print key bytes as a generic fix. Follow
+[source capture setup](https://github.com/lost-in-the/woods/blob/main/docs/SOURCE_FRESHNESS.md).
+
 ### Watch retains facts from an initializer deleted while stopped
 
 Record the installed revision. In Woods `2.0.0`, startup preserves
@@ -84,6 +106,51 @@ 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.
 
+### Watch misses an edit made while another extraction publishes
+
+Record the loaded revision; a matching `2.0.0` version alone does not prove the
+#585 repair is present. Supporting Git builds use the generation's optional
+source-capture boundary and recorded dirty paths, with content checks for
+unchanged candidates. Legacy or invalid boundary metadata causes one full
+startup reconciliation under the usual reload/restart rules. On older builds,
+finish a full extraction against settled source before restarting watch.
+Do not infer source freshness from a recent generation marker or remove a
+foreign watch claim. See the installed version's
+[startup catch-up guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md).
+
+### Watch does not recover after a failed reconciliation
+
+The deletion-only startup retry repair (#640) and empty-touch publication error
+repair (#641) are unreleased after Woods `2.0.0`; verify the loaded revision.
+Supporting revisions retain pathless deletion reconciliation for heartbeat
+retry and report failed flow withdrawal as degraded even when no units changed.
+On older builds, fix the logged cause and restart watch to reconcile again.
+An empty touched-unit list is not proof that publication succeeded. Inspect
+the generation and publication errors; see the installed version's
+[startup recovery guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#startup-is-not-a-clean-slate).
+
+### Extraction fails while a sibling extractor succeeds
+
+The #584 publication-reporting repair is unreleased after Woods `2.0.0`.
+Supporting revisions refuse the whole publication after a consumer constructor
+or extraction failure and keep the previous generation active. Fix the logged
+cause and retry the complete batch; do not treat a sibling's success as a
+completed extraction. For custom/embedded pipeline tools, acknowledgement only
+means the background task started: inspect its final task state. Those operator
+tools are not registered by the packaged default Index Server. See
+[extraction failures](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md).
+
+### Manager, policy or migration identity does not match the source
+
+The selected-declaration repairs in #594 are unreleased after `2.0.0`.
+Supporting writers use actual loaded ancestry where available and inspect
+historical migration declarations without executing them. An unresolved qualified
+migration namespace needs the documented source/normal-boot setup; do not load
+historical migrations to force discovery. Full re-extraction repairs previously
+misidentified migration units. Method chunks now distinguish `self.call`, `call`
+and punctuation-bearing names, so rebuild affected embeddings after upgrading.
+See the [extractor contracts](https://github.com/lost-in-the/woods/blob/main/docs/EXTRACTOR_REFERENCE.md).
+
 ### A cleaned index directory still exists
 
 In Woods `2.0.0`, `woods:clean` retains the output directory and
@@ -112,6 +179,15 @@ extraction will remove a legitimate cross-type collision. See the canonical
 
 ## 2. Check the published index
 
+In supporting unreleased writers after 2.0.0, incremental extraction and
+targeted refresh refuse a flat index with a manifest or a generation whose
+manifest writer major version is below 2. Run full `woods:extract` using the
+[upgrade sequence](https://github.com/lost-in-the/woods/blob/main/docs/UPGRADING_TO_2.md#3-clean-and-re-extract).
+Do not relabel the manifest or delete its writer field. A generation that
+already lacks this field can be an early v2 beta and is allowed; an empty
+output directory still needs a full baseline. Legacy read support does not
+make partial writes a valid migration.
+
 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
@@ -119,6 +195,21 @@ 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).
 
+The incremental/refresh collision guard (#561) is unreleased after 2.0.0; verify
+the writer revision before relying on it. A refusal preserves the prior
+generation. Older writers could already have overwritten ownership: repair the
+producer/source issue and perform a successful full extraction to recover.
+Woods 2.0.0 can also misidentify Struct/Data classes inside namespace wrappers
+(#559). The fix is unreleased after 2.0.0, planned for 2.1: verify the writer's
+loaded revision before expecting assigned PORO/library child identities. A full
+extraction repairs old identities and establishes reference-cache format 3;
+incremental extraction refuses the older cache. Preserve the last generation
+until the rebuild succeeds. Do not rename valid application constants or disable
+collision checks to bypass an older writer's inference. Follow the
+[assigned value-class contract](https://github.com/lost-in-the/woods/blob/main/docs/EXTRACTOR_REFERENCE.md#assigned-value-classes);
+constructor blocks and unverified dynamic assignments remain outside reference
+coverage. Updating this plugin does not upgrade the writer.
+
 ```bash
 bin/rails woods:validate
 bin/rails woods:stats
@@ -126,6 +217,14 @@ 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.
 
+For incremental CI, restore only an index for the selected diff's exact base
+commit; a cold or unrelated cache requires full extraction. Fetch the actual
+PR base ref and sufficient history before running the task. Nested-app Git
+paths, normalization of `./` and contained absolute `CHANGED_FILES`, and blank
+CI-variable handling are unreleased after `2.0.0` (#571); check the installed
+revision before relying on them. Keep nonempty invalid ranges as failures.
+See the [incremental CI contract](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md#github-actions-with-an-exact-baseline).
+
 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
@@ -226,8 +325,17 @@ 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
+Builds containing #588 (unreleased after `2.0.0`) reconcile the whole jobs and
+serializers families on relevant Ruby batches, including nested runtime classes.
+Incomplete discovery retains unproven units and refuses ownership transfers.
+Direct incremental calls reject restart-sensitive inputs; apply migrations and
+run full extraction in a fresh Rails process. Fresh one-shot incremental tasks
+escalate those inputs themselves. Disabling `precompute_flows` withdraws stored
+flows on the next successful writer run. Check the revision and follow the
+[runtime reconciliation guide](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md#runtime-removals-and-bundle-updates).
+
+After a bundle change or on older builds after 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
@@ -273,8 +381,37 @@ 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).
 
+## Missing GraphQL units
+
+In supporting unreleased readers after 2.0.0, `lookup` accepts the directory
+family alias `type: "graphql"` and returns the actual subtype. Prefer the
+concrete type from `search` for follow-up checks. On older readers, retry with
+that concrete type before concluding that a published GraphQL unit is absent.
+
+Woods 2.0.0 can omit schema classes, resolvers inherited through application
+superclasses, and runtime types owned by additional schemas (#558, #562, #563).
+The fixes are **unreleased after 2.0.0, planned for 2.1**; check the writer's loaded
+revision before expecting them. A supporting writer publishes schema classes as
+`graphql_type` with `metadata.graphql_kind: "schema"`, and combines the runtime
+type inventories of every current application schema. Confirm that the application
+boots, then run full extraction and validate to establish a complete upgrade baseline.
+
+A schema introspection failure stops publication and leaves the prior generation
+active. Fix the named schema error and retry; do not treat a partial boot or an
+empty type inventory as proof that a query root was removed. Missing embeddings
+cannot explain an absent structural unit. Follow the
+[GraphQL extraction contract](https://github.com/lost-in-the/woods/blob/main/docs/EXTRACTOR_REFERENCE.md#graphqlextractor)
+for source fallback, runtime-only removal and reference-coverage limits.
+
 ## Deferred refresh hooks
 
+For missing Unicode edit events on a host without jq, inspect the locale and
+the installed hook files. The #592 UTF-8 fallback repair is unreleased after
+Woods `2.0.0`; it fixes edit queueing and SessionStart decoding under `LC_ALL=C`.
+Older hooks can use jq or a UTF-8 locale. Confirm the pending queue and published
+generation, since hook exit zero does not establish refresh. See
+[client hook recovery](https://github.com/lost-in-the/woods/blob/main/docs/CLIENT_HOOKS.md#queue-paths-and-recovery).
+
 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
@@ -300,6 +437,13 @@ 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).
 
+On a reviewed post-2.0 writer containing the unreleased reference expansion,
+missing/incompatible reference-cache state requires a full extraction before
+incremental maintenance resumes. Check the loaded revision, not VERSION alone.
+Increasing `max_nodes` cannot recover edges the writer never recorded. Follow the
+[baseline diagnostic](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#source-reference-baseline-needs-a-full-extraction)
+and preserve pending work. This plugin does not add extraction capabilities.
+
 ## 4. Check semantic retrieval
 
 Do not treat structural `ready: true` or bootstrap `hydrated` as proof that
@@ -338,6 +482,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 an unsupported OpenAI `dimensions` option or stale vectors after changing
+provider width/endpoint, check the installed revision: the embedding request and
+cache consistency fix (#586) is unreleased after Woods `2.0.0`. It distinguishes
+stored vector width from explicit reduction, omits unsupported width parameters
+for fixed-width ada, and scopes embedding cache entries to provider configuration.
+Follow the installed version's [embedding options and cache guidance](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#embedding-options);
+never bypass a width refusal or infer this capability from the plugin version.
+
+Injected-provider restoration (#599) is unreleased after Woods `2.0.0`.
+Supporting writers preserve effective non-secret built-in settings through known
+wrappers. If a snapshot carries `requires_host_provider`, use a supporting reader
+and configure the compatible provider explicitly, or deliberately select lexical
+mode. Older readers do not enforce this additive marker. Record both writer and
+reader revisions when an endpoint or context size changes after restoration;
+do not remove the marker or copy endpoint credentials into `woods.json`. See
+[injected providers](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#injecting-a-provider-object).
+
 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
@@ -346,6 +507,16 @@ 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.
 
+### Restored snapshot files are not visible
+
+`woods:clean` deletes history stored inside the output directory. Follow the
+[upgrade backup and selective-restore sequence](https://github.com/lost-in-the/woods/blob/main/docs/UPGRADING_TO_2.md#3-clean-and-re-extract)
+before cleaning; do not restore an old structural baseline over a new one.
+`WOODS_SNAPSHOTS=true` enables store construction, but it still prefers SQLite
+and does not import JSON history. A retained JSON history needs an explicit
+`JsonSnapshotStore` reader if SQLite became available. Preserve the original
+backup and verify an old snapshot before resuming writers.
+
 ## 5. Check Console separately
 
 For repeated missing-token boot warnings on a stdio-only host, check whether
@@ -369,6 +540,15 @@ For MySQL SQL refusals, inspect the executing session's `sql_mode` and the insta
 
 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.
 
+Woods `2.0.1` includes per-mount HTTP guards, complete collection-cell redaction,
+longest exact-credential matching, and stricter SQL provenance/grammar checks.
+Verify the installed version, loaded gem path and any Git revision before relying
+on those protections. Keep automatic mounting, configured policies, and credential
+checks intact; use scalar projections or a structured query when SQL cannot
+preserve field identity. On an affected version, disable Console if those controls
+are required. See the
+[2.0.1 correction notes](https://github.com/lost-in-the/woods/blob/v2.0.1/docs/CONSOLE_MCP_SETUP.md#maintenance-policy-corrections).
+
 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
@@ -377,6 +557,17 @@ Return the first failing layer, commands/evidence, root-cause hypothesis, whethe
 
 Canonical guide: [TROUBLESHOOTING.md](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md).
 
+## SQLite metadata and typed semantic results
+
+If a SQLite-backed index retains deleted units after embedding, or a `:local`
+reader returns no type-filtered semantic matches after restart, record the exact
+embedding and reader revisions. The SQLite reconciliation and metadata hydration
+fix (#572) is unreleased after Woods `2.0.0`. With that fix, a full embed removes
+stale SQLite rows; restarting the reader restores vector type filters from the
+configured SQLite metadata store. Incremental empty-input and bulk-deletion
+guards still apply. See the canonical
+[SQLite metadata configuration](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#sqlite-metadata).
+
 ## Lexical retrieval capability check
 
 Lexical retrieval is available from `2.0.0.beta3`. Before proposing it, verify the installed gem
@@ -414,6 +605,46 @@ 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).
 
+### Source paths with invalid filename bytes (unreleased after Woods 2.0.0; #573)
+
+Check the writer revision before relying on this handling. An
+`undecodable_source_path` diagnostic means Woods could not represent a filename
+as UTF-8; source freshness remains unknown and reference publication preserves
+the previous generation. Inspect the escaped path, correct the filename in the
+application checkout, and retry extraction. Do not fabricate current freshness
+or discard the prior index. Valid Unicode filenames remain supported, including
+under a C locale. See [source freshness](https://github.com/lost-in-the/woods/blob/main/docs/SOURCE_FRESHNESS.md).
+
+### Directory symlinks prevent the first extraction (#653)
+
+The directory-link capture repair is unreleased after Woods `2.0.1`; check the
+writer revision. Older writers can refuse `unverified_symlink_directory` even
+for valid static-assets links. Supporting writers retain logical source aliases
+and verify scoped files inside the app root; cycles, changing links and external
+source still refuse verification. Do not replace valid application links or
+disable publication safeguards. Upgrade the writer and run one fresh full
+extraction. See [source scope](https://github.com/lost-in-the/woods/blob/main/docs/SOURCE_FRESHNESS.md#scope-and-partial-extraction).
+
+### Surviving-file ownership moves (unreleased after Woods 2.0.0; #574)
+
+Check the writer revision before relying on this correction. A moved class can
+keep its identity when a complete Rails boot proves its unique new owner. For
+file-derived identities, submit both changed paths together so extraction can
+prove that the surviving old file released the identity. Retry the complete
+batch after resolving boot or extraction failures; do not disable collision
+checks or delete the previous generation to force a move through. Simultaneous
+owners still fail. See [incremental extraction](https://github.com/lost-in-the/woods/blob/main/docs/INCREMENTAL_EXTRACTION.md).
+
+### Once-loader naming (unreleased after Woods 2.0.0; #579)
+
+Check the loaded writer revision when a declared library child is misnamed as
+its enclosing wrapper. Writers with this fix use the owning Rails loader,
+including `config.autoload_lib_once` naming rules. Run one full extraction after
+upgrading an affected index before resuming incremental maintenance. This does
+not combine unmanaged files that reopen one namespace or invent a class for a
+VERSION-only file. Preserve collision diagnostics for those cases. See
+[extractor naming](https://github.com/lost-in-the/woods/blob/main/docs/EXTRACTOR_REFERENCE.md#identifier-naming-source-derived-units).
+
 ## Compact evidence capability check
 
 Inspect the connected server's installed tool schemas before using `evidence` on
@@ -461,13 +692,105 @@ byte-identical generated assets into `_woods/ownership.json`; changed legacy sid
 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.
 
-### Console read compatibility on security-patch candidates
-
-Verify the loaded revision for corrections after 2.0.0. Active redaction refuses
-SQL relation/CTE column alias lists; typed EAV matching can intentionally mask
-extra values where tables share a final name or differ only by case. Keep the
-policy enabled and use explicit scalar columns or structured tools. Check exact
+## Source freshness and query errors after 2.0.0
+
+Check the installed revision before using these unreleased diagnostics:
+
+- Builds containing #589 expose `recorded_root`, `checked_root`, and `root_source`.
+  A recorded-root check does not certify a copied checkout. Follow `deep_check`
+  for a quick-reader timeout, `inspect_source_scan` for mapping/permission/limit
+  problems, and `fresh_capture` for incomplete capture or boot evidence. Preserve
+  mixed recommendations. Missing evidence cannot prove all files were added or
+  unreadable files deleted. See
+  [source freshness](https://github.com/lost-in-the/woods/blob/main/docs/SOURCE_FRESHNESS.md).
+- Supporting builds publish a usable code index with freshness `unavailable`
+  and reason `source_manifest_too_large` when evidence alone exceeds its
+  serialized-size limit. Follow `inspect_source_limits` and inspect
+  `unavailable.size_bytes` / `unavailable.limit_bytes`; repeating an identical
+  full capture cannot fix this. Changed-file and Git-based incremental work
+  remain usable with validated source-reference proof. An oversized launcher
+  handoff starts a fresh child without verified preboot capture. Actual invalid
+  evidence, failed writes and source instability retain publication safeguards.
+- Supporting readers retain readable unscoped search matches when an individual
+  needed unit cannot be decoded or opened, with partial reason
+  `unreadable_or_corrupt_source`. Empty partial results do not prove absence;
+  identifier-only summary hits do not validate bodies. Run `woods:validate`.
+  Explicit package/source-path scope still validates the full unit set before
+  matching; corrupt index-wide artifacts also retain typed errors. See
+  [search completeness](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#search-completeness).
+- With `:local`, supporting readers return degraded reload because snapshot
+  vectors and SQLite metadata cannot refresh atomically together. The old
+  aligned state remains served. Restart `woods-mcp` after `woods:embed`; granting
+  write access alone cannot fix this case. See the
+  [backend matrix](https://github.com/lost-in-the/woods/blob/main/docs/BACKEND_MATRIX.md#persistence-story).
+- Builds containing #593 return actual types from family-filtered search and
+  reject unknown type names. An unknown flow unit or snapshot is `not_found`,
+  while a valid empty answer remains successful. Repeated `corrupt_artifact`
+  errors after a malformed generation marker require validation and restoration
+  or a fresh extraction; never edit the pointer to guess a payload. See
+  [Index MCP contracts](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#resource-identity-and-damaged-generation-markers).
+- Builds containing #590 retain intended private bundle settings during managed
+  preflight. Compare named identity fields and owned bytes before changing an
+  installer setup. Keep receipts; use the supporting executable for removal
+  before downgrading and real parent directories for temporary plans. See
+  [managed configuration](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md#managed-claude-code-configuration).
+
+### Console HTTP remains unavailable after a Rails boot error
+
+In builds containing #597's HTTP repair (unreleased after `2.0.0`), an eager-load
+`NameError` makes that worker return a stable, non-cacheable HTTP 503. Reproduce
+the application's eager loading, correct its naming or boot failure, and restart
+the worker; do not keep retrying against a partially loaded model registry or
+relax authentication/table rules. A 401 still indicates authentication failure.
+See [Console startup diagnostics](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md).
+
+### Missing default or parenthesized state machines
+
+The #594 literal state-machine repair is unreleased after `2.0.0`; verify the
+writer's revision before relying on it. Supporting builds recognize direct
+`state_machine` calls with the default `state` attribute or an explicit name,
+including multiline parenthesized arguments. They do not infer dynamic or
+inherited machines from missing edges. Re-extract with a supporting writer and
+compare the selected model's actual registry when coverage is uncertain. See the
+[extractor contract](https://github.com/lost-in-the/woods/blob/main/docs/EXTRACTOR_REFERENCE.md#statemachineextractor).
+
+### Unreleased functional audit repairs
+
+Record the loaded revision as well as VERSION before using these post-2.0.0
+behaviors. A supporting exporter offers `UNBLOCKED_DRY_RUN=1` and explicit
+`UNBLOCKED_MIGRATE_FROM_REF`; read the installed
+[Unblocked migration guide](https://github.com/lost-in-the/woods/blob/main/docs/UNBLOCKED_INTEGRATION.md#explicit-ref-migration)
+before moving a scope. Preserve receipts, use one writer, and never use force
+purge to bypass unresolved ownership.
+
+Unresolved legacy owned receipts leave Unblocked sync incomplete. Select the
+known old ref explicitly; refs containing slashes cannot be inferred from URI
+prefixes. Obsolete documents without current replacements require review and
+manual remote and receipt cleanup. Do not remove receipts merely to clear the
+diagnostic. Inventory entries without a non-empty string URI are skipped and
+provide no ownership evidence.
+
+Supporting embedding builds validate complete prefixed inputs, split source
+without truncation, and rebuild old checkpoints once. Ollama counts are estimates
+and requests use `truncate: false`; installing a tokenizer gem no longer selects
+BERT for every model. Read the installed
+[input contract](https://github.com/lost-in-the/woods/blob/main/docs/EMBEDDING_MODELS.md#why-num_ctx-isnt-enough)
+and bounded unit/model/limit diagnostic before changing provider settings.
+
+For reopened `lib/` units, inspect all `source_contributors`; primary `file_path`
+is not complete ownership. Full extraction is required to rebuild the upgraded
+reference cache. Missing dependency-owned components/channels are intentional
+in supporting builds; app-owned mailers include parallel base-class branches.
+
+### Console read compatibility in 2.0.1 and 1.6.4
+
+Verify the installed version and loaded gem path, plus the locked revision for
+Git-sourced builds. Woods `2.0.1` and `1.6.4` refuse SQL relation/CTE column alias
+lists while redaction is active; typed EAV matching can intentionally mask extra
+values where tables share a final name or differ only by case. Keep the policy
+enabled and use explicit scalar columns or structured tools. Check exact
 sensitive-key spelling and configure binary secret columns for column redaction.
-Read the [Console compatibility guide](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility)
-at the installed revision for adapter, timeout and projection limits; a plugin
-update does not patch Woods.
+Use the installed line's guide for adapter, timeout and projection limits:
+[2.0.1](https://github.com/lost-in-the/woods/blob/v2.0.1/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility)
+or [1.6.4](https://github.com/lost-in-the/woods/blob/v1.6.4/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility).
+A plugin update does not patch Woods or make planned 2.1 features available.

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

@@ -59,6 +59,17 @@ 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 [post-2.0 reference expansion](https://github.com/lost-in-the/woods/blob/main/docs/EXTRACTOR_REFERENCE.md#constant-source-references)
+is unreleased and planned for 2.1. Verify the loaded writer revision and full
+baseline before expecting its additional edges. `code_reference` is source
+evidence, not observed execution; the coverage warning remains applicable.
+
+The same planned expansion discovers callable standalone `app/models` modules
+as `poro` units with `metadata.ruby_kind: "module"`. Runtime model mixins retain
+`concern` ownership. Verify the installed writer and run a full extraction before
+expecting those units; namespace-only wrappers and uncertain source ownership
+remain outside discovery.
+
 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

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

@@ -5,6 +5,21 @@ description: Configure Woods MCP connections with the exact client JSON shapes a
 
 # Woods MCP configuration
 
+For builds containing #590 (unreleased after `2.0.0`), managed preflight retains
+intended bundle settings, project receipts omit the unused user config directory,
+and watcher ownership tolerates Git checkout umasks. Check the installed revision
+before relying on this. Keep the supporting executable for update/removal before
+a permanent downgrade; never delete a receipt to bypass a conflict. Use a private
+real directory for plan files when the system temporary path is a symlink. Follow
+the [portability guidance](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md#managed-claude-code-configuration).
+
+For builds containing #597's launcher repair (planned for 2.1; not included in
+`2.0.1`),
+`config/console.yml` must be a supported top-level mapping with string keys and
+mode-appropriate options. Nested or unsupported configuration is refused before
+launch rather than silently selecting local mode. Check the installed revision
+and follow the [Console configuration guide](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md).
+
 ## Managed configuration availability
 
 `woods-agent-config` (#407) is available in Woods `2.0.0.beta3`. First record the
@@ -39,6 +54,14 @@ Keep normal protocol negotiation and use the
 when unavailable. See the
 [initialization contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#initialization-guidance).
 
+The packaged Index process does not load Rails initializers. Session and Notion
+tool registration requires an explicitly configured custom/embedded process;
+application configuration alone does not wire them into a separate executable.
+Use `bin/rails woods:notion_sync` for ordinary application export and verify
+`tools/list` for custom capabilities. For a custom Console path, configure it
+before Railtie initialization and restart. See the
+[process boundaries](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#conditional-index-capabilities).
+
 ## Shape 1: Index-only
 
 ```json
@@ -99,6 +122,11 @@ override; the shared root selects the primary checkout's HEAD. Follow the
 
 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.
 
+In supporting unreleased builds after 2.0.0, the `:local` preset also returns
+degraded on reload because snapshot vectors and SQLite metadata cannot refresh
+atomically together. Restart `woods-mcp` after `woods:embed`; write access alone
+does not resolve this case. See the [backend matrix](https://github.com/lost-in-the/woods/blob/main/docs/BACKEND_MATRIX.md#persistence-story).
+
 For host MCP reading a container daemon's shared index, foreign heartbeat trust
 (#321) is available in Woods `2.0.0.beta3`. Verify the installed gem version's release notes before
 offering `WOODS_WATCH_TRUST_FOREIGN_HOST=1` in the MCP environment. It makes
@@ -125,6 +153,12 @@ 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.
 
+Prefer the automatic Rails middleware mount. Per-instance guards for legacy
+manual mounts are included in Woods `2.0.1` and `1.6.4`; verify the installed
+version, loaded gem path and any Git revision before relying on them. A plugin
+update does not patch the server. Follow the installed version's Console guide
+and leave HTTP disabled for stdio-only use.
+
 Then add a direct Console process:
 
 ```json
@@ -137,6 +171,11 @@ Then add a direct Console process:
 
 For Docker/SSH, configure `~/.woods/console.yml` or `WOODS_CONSOLE_CONFIG`; the launcher owns process replacement. Direct Docker stdio uses `docker exec -i`, or `docker compose exec -T` to disable Compose's pseudo-TTY while retaining stdin.
 
+Supporting unreleased builds after `2.0.0` prefer the selected app's executable
+`bin/rake` in direct mode. A relative `directory` in `console.yml` is relative to
+the launcher's initial `cwd`. Record the installed revision before relying on
+this preference; explicit commands still win.
+
 Reserve stdout for MCP. Through Woods `2.0.0.beta4`, configure the Console
 process's Rails logger to use stderr or a file, including logs during queries.
 Runtime stdout isolation is included in Woods `2.0.0`; verify the installed
@@ -204,6 +243,26 @@ 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).
 
+Supporting unreleased builds after 2.0.0 report `unavailable` with
+`source_manifest_too_large` when source evidence exceeds its serialized-size
+limit. The code index remains usable. Follow `inspect_source_limits`, inspect
+`unavailable.size_bytes` / `unavailable.limit_bytes`, and retain the limitation;
+an identical full extraction or a deeper scan cannot fix oversized evidence.
+An oversized launcher handoff cannot establish verified preboot capture.
+
+## Partial search and GraphQL lookup (unreleased after 2.0.0)
+
+Check the installed reader revision before relying on these repairs. Unscoped
+search skips an individual unit it needs but cannot read, retains readable matches,
+and reports successful partial completeness with
+`reason: "unreadable_or_corrupt_source"`. Empty partial results do not prove
+absence. Identifier-only search can use summaries without validating unit
+bodies; run `woods:validate` for damage. Explicit package/source-path scope
+still requires readable bodies across its full-unit preflight. Corrupt
+index-wide artifacts return a typed error. Supporting `lookup` also accepts
+`type: "graphql"`, but returns the unit's concrete type; use that type for follow-up checks.
+See the [search contract](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md#search-completeness).
+
 ## Compact evidence capability check
 
 Inspect the connected server's installed tool schemas before using `evidence` on
@@ -215,17 +274,29 @@ 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).
 
-### HTTP configuration diagnostics on security-patch candidates
+### Origin policy compatibility
+
+In Woods `2.0.1`, HTTP preflight and the SDK share one captured policy. List the
+browser's exact origin, including its port, for cross-origin requests; portless
+entries additionally permit same-authority
+traffic. Include a non-loopback MCP endpoint authority and restart after edits.
+Do not disable SDK protection or rewrite Origin/Host to make a request pass.
+Follow the [2.0.1 HTTP guide](https://github.com/lost-in-the/woods/blob/v2.0.1/docs/MCP_HTTP_TRANSPORT.md#browser-origins-dns-rebinding-defense)
+and verify both preflight and authenticated dispatch.
+
+### HTTP configuration diagnostics in 2.0.1
 
-Check the installed revision before expecting this unreleased correction. Invalid
-origin settings, including invalidly encoded entries, refuse at boot. The HTTP
-executable reports one configuration diagnostic and exits 2. Correct the named
-entry and restart; keep authentication and origin checks enabled. Follow the
+Verify the installed version, loaded gem path and any Git revision. In Woods
+`2.0.1`, invalid origin settings, including invalidly encoded entries, refuse at
+boot. The HTTP executable reports one configuration diagnostic and exits 2.
+Correct the named entry and restart; keep authentication and origin checks enabled. Follow the
 installed revision's canonical `docs/MCP_HTTP_TRANSPORT.md` for accepted origins.
 
 Use whitespace-free literal origin entries; explicit lists replace browser
 defaults, and wildcard patterns are unsupported. Preserve the real Host behind
 proxies. Verify both preflight and bearer-authenticated dispatch against the
-[HTTP compatibility guide](https://github.com/lost-in-the/woods/blob/main/docs/MCP_HTTP_TRANSPORT.md#origin-configuration-compatibility)
-at the installed revision; configured non-loopback Hosts are passed to the SDK
-in supporting patches.
+[2.0.1 HTTP compatibility guide](https://github.com/lost-in-the/woods/blob/v2.0.1/docs/MCP_HTTP_TRANSPORT.md#origin-configuration-compatibility).
+For applications staying on 1.6, use `1.6.4` and its
+[HTTP compatibility guide](https://github.com/lost-in-the/woods/blob/v1.6.4/docs/MCP_HTTP_TRANSPORT.md#origin-configuration-compatibility);
+configuration normalization differs between the two lines. A plugin update does
+not update either server's installed gem.