woods 2.0.0.beta2 → 2.0.0.beta3

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

@@ -7,6 +7,19 @@ description: Install, upgrade, and first-run-configure the Woods Rails code-inte
 
 Install a structural Index Server first. Embeddings and Console MCP are separate opt-ins.
 
+## 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
 
 Read repository instructions and preserve unrelated changes. Record:
@@ -23,7 +36,14 @@ This skill describes the Woods 2.x line; the authoritative minimum version lives
 
 ## Install and inspect
 
-Add `gem "woods", "~> 2.0"` to the development group, then:
+Choose the published version using the canonical
+[installation guide](https://github.com/lost-in-the/woods/blob/main/docs/GETTING_STARTED.md#1-install-the-gem)
+and its linked README release table. When only prereleases are published for
+2.x, add the exact published beta/RC constraint shown there to the development
+group; `~> 2.0` does not select prereleases. Use `gem "woods", "~> 2.0"` only after
+a stable 2.x release is published. Follow the selected version's tag docs and
+verify installed capabilities; installing this plugin does not install `main`
+features. Then run:
 
 ```bash
 bundle install
@@ -54,6 +74,12 @@ bin/rails woods:stats
 
 If extraction fails, reproduce Rails boot and eager loading first. Do not inspect internal payload files when Woods tasks provide the check.
 
+Writer-version provenance (#323) is unreleased; check the installed gem version's
+release notes before expecting `woods_status.index.woods_version`. When present,
+it names the last manifest publisher; `server.version` names the MCP reader.
+Missing/null means unknown. A matching version after an incremental run never
+replaces a required full upgrade extraction. See [writer provenance](https://github.com/lost-in-the/woods/blob/main/docs/PUBLISHED_INDEX.md#manifest-writer-provenance).
+
 Configure the Index Server with the application bundle, absolute app `cwd`, and an index path visible to that process. For a host-installed bundle:
 
 ```json
@@ -82,11 +108,49 @@ When Woods is installed only in Docker, launch it through the application servic
 }
 ```
 
-Reconnect and call `woods_status`, then `search`, `lookup`, and `dependents` for a known class. The normal Index Server has 14 tools. `codebase_retrieve` requires configured embeddings.
-
-Offer to add `bundle exec rake woods:watch` to the existing development process manager. When authorized, it catches up missed changes and automatically maintains the structural index; the Index Server refreshes on its next call, so ordinary edits need no manual extraction or MCP restart. State that boot-captured changes require supervisor restart, Docker may need `WOODS_WATCH_POLL=1`, and semantic vectors still need `woods:embed_incremental`.
-
-The plugin also ships two hooks (Woods 2.3 or later), shipped disabled. A `PostToolUse` hook runs `woods:incremental` in the background when an edit touches models, routes, migrations, schema, or a `package.yml`, reading `cwd` from the hook payload so linked worktrees refresh their own index; it batches paths from overlapping edits instead of dropping them under lock contention. A `SessionStart` hook warns when the published generation predates the last commit, a check scoped to commit timestamps, so it does not cover uncommitted edits or an older checkout. Both do nothing until `tmp/woods/generation.json` exists and until the user sets `WOODS_HOOKS_ENABLED=1`; set `WOODS_HOOK_RAKE="docker compose exec -T app bundle exec rake"` when the bundle lives in a container, `WOODS_OUTPUT` when the index directory is non-default, and `WOODS_HOOKS_DISABLED=1` to turn both back off.
+Reconnect and call `woods_status`, then `search`, `lookup`, and `dependents` for a known class. The normal Index Server has 14 tools. `codebase_retrieve` requires configured embeddings in semantic mode; see the lexical capability check below for the opt-in provider-free mode.
+
+Offer to add `bundle exec rake woods:watch` to the existing development process manager. When authorized, it catches up missed changes and automatically maintains the structural index; the Index Server refreshes on its next call, so ordinary edits need no manual extraction or MCP restart. Use the standalone watch command; do not prepend the `environment` task. Check the installed version's watch guide before relying on automatic startup reconciliation. State that live boot-captured changes require supervisor restart, Docker may need `WOODS_WATCH_POLL=1`, and semantic vectors still need `woods:embed_incremental`.
+
+Foreign-host heartbeat trust (`WOODS_WATCH_TRUST_FOREIGN_HOST=1`, #321) is unreleased.
+Check the installed gem version against its release notes before offering it;
+do not assume installing this plugin upgrades the gem. For a supporting version,
+follow [cross-host liveness](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#cross-host-liveness)
+and set the opt-in in each task/MCP reader of a shared container index. Explain
+the 15-minute crash-detection delay and preserve one supervisor per daemon.
+
+For slow bind mounts, check whether the installed version documents
+`WOODS_WATCH_POLL_INTERVAL` before suggesting it; this setting is unreleased
+in Woods 2.0.0.beta2. Where supported, a positive value such as `2.5` reduces
+polling frequency at the cost of detection latency. Use the installed preflight version to select tagged documentation; the
+[canonical watch guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md)
+tracks current source and may describe unreleased behavior.
+
+The plugin ships opt-in refresh and session-start hooks. The expanded refresh
+contract (#408) is unreleased after Woods 2.0.0.beta2: first verify the installed
+gem exposes `woods:hook_refresh` through the actual application command. Do not
+infer support from the plugin version. With support, edits to standard services,
+controllers, jobs, views, concerns, locales, supported tests/lib files, routes,
+and packages queue incremental work; boot/config/schema edits request a fresh
+full extraction. A live daemon defers without acknowledging the queue. Failed or
+deferred events remain under `<output>/hook-pending/` and retry on the next
+relevant edit. Inspect `hook.log` before retrying; never delete pending events to
+hide a failure. Prefer `woods:watch` for sustained edits because hook coverage
+increases Rails boot frequency.
+
+Both hooks require an existing index and `WOODS_HOOKS_ENABLED=1`; disable with
+`WOODS_HOOKS_DISABLED=1`. Use `WOODS_HOOK_RAKE="docker compose exec -T app bundle
+exec rake"` for a container-only bundle and `WOODS_OUTPUT` for a non-default
+index. The host needs Bash and either jq or Ruby, not the application bundle.
+The refresh worker's deadline starts after the complete event input has been
+collected, validated, and queued; it does not bound input collection. It includes
+subsequent batches, but cancelling Docker exec does not prove its container
+process stopped. See the [hook deadline and retry contract](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#hooks-for-agent-sessions).
+Source freshness (#405) is unreleased after beta2: verify the installed command
+exposes `woods:source_status` and `woods-extract` before using it. Supporting
+SessionStart hooks check source content and report missing/failed evidence as
+unknown; silence does not acknowledge queued refresh work. Follow the [hook guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#hooks-for-agent-sessions)
+for transport, retry and custom-root limits.
 
 ## Ask before expanding scope
 
@@ -97,3 +161,40 @@ Require explicit approval before adding Ollama/OpenAI, pgvector/Qdrant, secrets,
 Report the Woods version, branch, files changed, commands/results, index path, MCP calls verified, semantic retrieval status, Console status, and unresolved risks. Never infer availability from source schemas alone.
 
 Canonical runbook: [AGENT_SETUP.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.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 and authorized, offer explicit lexical mode for ranked discovery
+over extraction output without provider credentials or vectors. Semantic mode
+remains the default; setting up embeddings is a separate choice.
+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 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: woods
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta2
+  version: 2.0.0.beta3
 platform: ruby
 authors:
 - Leah Armstrong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-10 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -118,6 +118,9 @@ executables:
 - woods-console-mcp
 - woods-console
 - woods-mcp-http
+- woods-agent-config
+- woods-extract
+- woods-hook-context
 extensions: []
 extra_rdoc_files: []
 files:
@@ -131,6 +134,7 @@ files:
 - docs/AGENT_GUIDE.md
 - docs/AGENT_SETUP.md
 - docs/BACKEND_MATRIX.md
+- docs/CLIENT_HOOKS.md
 - docs/CONFIGURATION_REFERENCE.md
 - docs/CONSOLE_MCP_SETUP.md
 - docs/DOCKER_SETUP.md
@@ -140,6 +144,7 @@ files:
 - docs/FAQ.md
 - docs/GETTING_STARTED.md
 - docs/INCREMENTAL_EXTRACTION.md
+- docs/INDEX_LAYOUT.md
 - docs/INTERNALS.md
 - docs/MCP_HTTP_TRANSPORT.md
 - docs/MCP_SERVERS.md
@@ -150,14 +155,19 @@ files:
 - docs/PUBLISHED_INDEX.md
 - docs/README.md
 - docs/RETRIEVAL_GUIDE.md
+- docs/RUNTIME_TRACING.md
+- docs/SOURCE_FRESHNESS.md
 - docs/TOKEN_BENCHMARK.md
 - docs/TROUBLESHOOTING.md
 - docs/UNBLOCKED_INTEGRATION.md
 - docs/UPGRADING_TO_2.md
 - docs/WATCH_DAEMON.md
 - docs/WHY_WOODS.md
+- exe/woods-agent-config
 - exe/woods-console
 - exe/woods-console-mcp
+- exe/woods-extract
+- exe/woods-hook-context
 - exe/woods-mcp
 - exe/woods-mcp-http
 - exe/woods-mcp-start
@@ -170,6 +180,21 @@ files:
 - lib/tasks/woods_checks.rake
 - lib/tasks/woods_evaluation.rake
 - lib/woods.rb
+- lib/woods/agent_configuration/applier.rb
+- lib/woods/agent_configuration/cli.rb
+- lib/woods/agent_configuration/cli_options.rb
+- lib/woods/agent_configuration/document.rb
+- lib/woods/agent_configuration/error.rb
+- lib/woods/agent_configuration/launcher.rb
+- lib/woods/agent_configuration/layout.rb
+- lib/woods/agent_configuration/managed_section.rb
+- lib/woods/agent_configuration/plan.rb
+- lib/woods/agent_configuration/plan_diff.rb
+- lib/woods/agent_configuration/planned_files.rb
+- lib/woods/agent_configuration/planner.rb
+- lib/woods/agent_configuration/planner_validation.rb
+- lib/woods/agent_configuration/preflight.rb
+- lib/woods/agent_configuration/recovery.rb
 - lib/woods/ast.rb
 - lib/woods/ast/call_site_extractor.rb
 - lib/woods/ast/method_extractor.rb
@@ -193,8 +218,10 @@ files:
 - lib/woods/console/console_response_renderer.rb
 - lib/woods/console/credential_index.rb
 - lib/woods/console/credential_scanner.rb
+- lib/woods/console/credential_scanner_registry.rb
 - lib/woods/console/dispatch_pipeline.rb
 - lib/woods/console/embedded_executor.rb
+- lib/woods/console/encrypted_credential_snapshot.rb
 - lib/woods/console/eval_guard.rb
 - lib/woods/console/input_contract.rb
 - lib/woods/console/model_validator.rb
@@ -230,6 +257,7 @@ files:
 - lib/woods/db/migrator.rb
 - lib/woods/db/schema_version.rb
 - lib/woods/dependency_graph.rb
+- lib/woods/embedding/corpus.rb
 - lib/woods/embedding/fake.rb
 - lib/woods/embedding/indexer.rb
 - lib/woods/embedding/openai.rb
@@ -252,6 +280,7 @@ files:
 - lib/woods/evaluation/metrics.rb
 - lib/woods/evaluation/query_set.rb
 - lib/woods/evaluation/report_generator.rb
+- lib/woods/export/typed_reader.rb
 - lib/woods/export/unit_facts.rb
 - lib/woods/extracted_unit.rb
 - lib/woods/extractor.rb
@@ -276,6 +305,8 @@ files:
 - lib/woods/extractors/line_neutralizer.rb
 - lib/woods/extractors/mailer_extractor.rb
 - lib/woods/extractors/manager_extractor.rb
+- lib/woods/extractors/method_parameters.rb
+- lib/woods/extractors/middleware_argument.rb
 - lib/woods/extractors/middleware_extractor.rb
 - lib/woods/extractors/migration_extractor.rb
 - lib/woods/extractors/model_extractor.rb
@@ -315,9 +346,19 @@ files:
 - lib/woods/gem_mapper.rb
 - lib/woods/generation.rb
 - lib/woods/git_command.rb
+- lib/woods/git_history.rb
 - lib/woods/git_provenance.rb
 - lib/woods/graph_analyzer.rb
+- lib/woods/hooks/context_cli.rb
+- lib/woods/hooks/context_event.rb
+- lib/woods/hooks/context_hint.rb
+- lib/woods/hooks/context_impact.rb
+- lib/woods/hooks/context_output.rb
+- lib/woods/hooks/context_state.rb
+- lib/woods/hooks/refresh.rb
+- lib/woods/hooks/rule_projection.rb
 - lib/woods/index_artifact.rb
+- lib/woods/input_rules.rb
 - lib/woods/mcp/bearer_auth.rb
 - lib/woods/mcp/bootstrap_state.rb
 - lib/woods/mcp/bootstrapper.rb
@@ -325,19 +366,26 @@ files:
 - lib/woods/mcp/errors.rb
 - lib/woods/mcp/index_reader.rb
 - lib/woods/mcp/index_reader_pinning.rb
+- lib/woods/mcp/initialization_guidance.rb
 - lib/woods/mcp/origin_guard.rb
 - lib/woods/mcp/protocol_policy.rb
 - lib/woods/mcp/provider_probe.rb
+- lib/woods/mcp/published_lexical_retriever.rb
 - lib/woods/mcp/renderers/claude_renderer.rb
 - lib/woods/mcp/renderers/json_renderer.rb
 - lib/woods/mcp/renderers/markdown_renderer.rb
 - lib/woods/mcp/renderers/plain_renderer.rb
+- lib/woods/mcp/search_results.rb
 - lib/woods/mcp/server.rb
 - lib/woods/mcp/tasks/extension.rb
 - lib/woods/mcp/tasks/request_capture.rb
 - lib/woods/mcp/tasks/store.rb
 - lib/woods/mcp/tool_contract.rb
 - lib/woods/mcp/tool_response_renderer.rb
+- lib/woods/mcp/traversal_evidence.rb
+- lib/woods/mcp/traversal_evidence_index.rb
+- lib/woods/mcp/traversal_evidence_page.rb
+- lib/woods/mcp/traversal_evidence_text.rb
 - lib/woods/mcp/version_aware_tool_dispatch.rb
 - lib/woods/model_name_cache.rb
 - lib/woods/notion/client.rb
@@ -349,6 +397,7 @@ files:
 - lib/woods/notion/rate_limiter.rb
 - lib/woods/notion/sync_manifest.rb
 - lib/woods/observability/structured_logger.rb
+- lib/woods/obsidian/destination_plan.rb
 - lib/woods/obsidian/errors.rb
 - lib/woods/obsidian/name_mapper.rb
 - lib/woods/obsidian/note_builder.rb
@@ -365,16 +414,28 @@ files:
 - lib/woods/published_index/typed_unit_reader.rb
 - lib/woods/railtie.rb
 - lib/woods/railtie_support.rb
+- lib/woods/rake_helpers.rb
 - lib/woods/release.rb
 - lib/woods/reload_policy.rb
 - lib/woods/resilience/circuit_breaker.rb
+- lib/woods/resilience/graph_invariant_validator.rb
+- lib/woods/resilience/graph_invariant_validator/membership_checks.rb
+- lib/woods/resilience/graph_invariant_validator/node_checks.rb
+- lib/woods/resilience/graph_invariant_validator/reverse_relationship_checks.rb
 - lib/woods/resilience/index_validator.rb
+- lib/woods/resilience/index_validator/graph_checks.rb
 - lib/woods/resilience/retryable_provider.rb
 - lib/woods/resolved_config.rb
 - lib/woods/retrieval/context_assembler.rb
+- lib/woods/retrieval/lexical_assembler.rb
+- lib/woods/retrieval/lexical_index.rb
 - lib/woods/retrieval/query_classifier.rb
 - lib/woods/retrieval/ranker.rb
+- lib/woods/retrieval/scope.rb
+- lib/woods/retrieval/scoped_graph_store.rb
+- lib/woods/retrieval/scoped_vector_store.rb
 - lib/woods/retrieval/search_executor.rb
+- lib/woods/retrieval/source_evidence.rb
 - lib/woods/retriever.rb
 - lib/woods/retry_after.rb
 - lib/woods/ruby_analyzer.rb
@@ -392,6 +453,17 @@ files:
 - lib/woods/session_tracer/solid_cache_coordination.rb
 - lib/woods/session_tracer/solid_cache_store.rb
 - lib/woods/session_tracer/store.rb
+- lib/woods/session_tracer/unit_resolver.rb
+- lib/woods/source_inputs/consumer_errors.rb
+- lib/woods/source_inputs/handoff.rb
+- lib/woods/source_inputs/launcher.rb
+- lib/woods/source_inputs/manifest.rb
+- lib/woods/source_inputs/private_key.rb
+- lib/woods/source_inputs/scanner.rb
+- lib/woods/source_inputs/scopes.rb
+- lib/woods/source_inputs/session.rb
+- lib/woods/source_inputs/status.rb
+- lib/woods/source_inputs/verifier.rb
 - lib/woods/storage/graph_store.rb
 - lib/woods/storage/inapplicable_backend.rb
 - lib/woods/storage/metadata_store.rb
@@ -415,6 +487,7 @@ files:
 - lib/woods/util/host_guard.rb
 - lib/woods/util/uuid5.rb
 - lib/woods/version.rb
+- lib/woods/watch/boot_snapshot.rb
 - lib/woods/watch/daemon.rb
 - lib/woods/watch/listen_watcher.rb
 - lib/woods/watch/polling_watcher.rb
@@ -422,8 +495,14 @@ files:
 - lib/woods/watch/tree_scan.rb
 - lib/woods/watch/watcher.rb
 - plugin/.claude-plugin/plugin.json
+- plugin/hooks/adapters/normalize.jq
+- plugin/hooks/adapters/normalize.rb
 - plugin/hooks/hooks.json
+- plugin/hooks/woods-context.sh
+- plugin/hooks/woods-input-rules.sh
+- plugin/hooks/woods-opencode.mjs
 - plugin/hooks/woods-post-edit.sh
+- plugin/hooks/woods-refresh.sh
 - plugin/hooks/woods-session-start.sh
 - plugin/skills/woods-agent-enable/SKILL.md
 - plugin/skills/woods-diagnose/SKILL.md
@@ -435,10 +514,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/lost-in-the/woods
-  source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta2
-  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0.beta2/CHANGELOG.md
+  source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta3
+  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0.beta3/CHANGELOG.md
   bug_tracker_uri: https://github.com/lost-in-the/woods/issues
-  documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta2/docs
+  documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta3/docs
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []