woods 2.0.0.beta4 → 2.0.1

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

@@ -55,11 +55,26 @@ when unavailable. See the
 
 Use this shape for any stdio-capable MCP client, adapted to the client's configuration location. `woods-mcp-start` validates and launches; it does not install or auto-restart.
 
+MCP registration does not start automatic indexing. Existing readers observe
+published generations without reconnecting; separately verify the watcher owner,
+startup catch-up, and a real edit. Native launcher/Puma installation (#538) is
+included in Woods `2.0.0`: check installed `woods-watch` and generator help
+before offering it. Preserve the existing external service in Docker/Grove and
+keep its source/index aligned across switches. See
+[automatic maintenance](https://github.com/lost-in-the/woods/blob/main/docs/AUTOMATIC_MAINTENANCE.md).
+
 Writer-version provenance (#323) is available in Woods `2.0.0.beta3`; check the installed
 gem version's release notes before expecting `index.woods_version` in `woods_status`. It reports
 the last manifest publisher, independently of `server.version`. Treat missing/null
 as unknown and see [writer provenance](https://github.com/lost-in-the/woods/blob/main/docs/PUBLISHED_INDEX.md#manifest-writer-provenance).
 
+Verify semantic retrieval separately from structural `ready`. A reachable
+provider and bootstrap `hydrated` can coexist with empty stores. If the recorded
+reader supports #549, inspect `retriever.corpus` for local record counts and
+known-empty diagnostics; absent or unknown counts require checking embedding
+artifacts. These fields do not certify embedding coverage. See the
+[readiness distinction](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
+
 When Woods is installed only in Docker, prefer running the server through the application container:
 
 ```json
@@ -74,7 +89,13 @@ When Woods is installed only in Docker, prefer running the server through the ap
 }
 ```
 
-Use a host-side bundle only after verifying Ruby, the application bundle, and the index are available on the host. Always pass the path visible to the process that runs `woods-mcp`. Prefer an explicit index path on all versions. After `2.0.0.beta3`, an unreleased change adds `WOODS_OUTPUT` as a fallback after the positional path and `WOODS_DIR`; check the installed version's configuration guide before relying on it. `woods-mcp-start` still refuses a missing path rather than selecting its working directory.
+Use a host-side bundle only after verifying Ruby, the application bundle, and the index are available on the host. Always pass the path visible to the process that runs `woods-mcp`. Prefer an explicit index path on all versions. Woods `2.0.0` includes `WOODS_OUTPUT` as a fallback after the positional path and `WOODS_DIR`; check the installed version's configuration guide before relying on it. `woods-mcp-start` still refuses a missing path rather than selecting its working directory.
+
+For linked worktrees, verify source/index alignment and the extraction's Git
+branch and exact SHA. Preserve the complete shared Git layout and select the
+worktree-specific directory when using the installed version's `WOODS_GIT_DIR`
+override; the shared root selects the primary checkout's HEAD. Follow the
+[worktree mount guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
 
 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.
 
@@ -116,6 +137,12 @@ 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.
 
+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
+revision before relying on it. Use the rake entry point to capture Rails boot
+output as well.
+
 Console registers nine default tools. `config.console_embedded_read_tools = true` explicitly adds `console_sql` and `console_query` for eleven total. Tier 2, Tier 3, and `console_eval` are inventory-only in supported packaged modes.
 
 ## Shape 3: Authenticated Console HTTP
@@ -187,3 +214,18 @@ returned typed, SHA-guarded `full_evidence` lookup for verification. Published-u
 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
+
+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
+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.

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

@@ -38,7 +38,7 @@ This skill describes the Woods 2.x line; the authoritative minimum version lives
 
 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
+and confirm the selected version on RubyGems. 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
@@ -108,9 +108,58 @@ When Woods is installed only in Docker, launch it through the application servic
 }
 ```
 
+For linked worktrees, verify source/index alignment and the extraction's Git
+branch and exact SHA. Preserve the complete shared Git layout and select the
+worktree-specific directory when using the installed version's `WOODS_GIT_DIR`
+override; the shared root selects the primary checkout's HEAD. Follow the
+[worktree mount guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
+
 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`.
+Structural readiness alone does not verify semantic retrieval. If that mode is
+requested, confirm an embedding run and a useful retrieval result. Readers with
+#549 expose `retriever.corpus` counts; check the installed capability before
+expecting them. Unknown counts are not zero, and positive counts do not certify
+complete embedding coverage. See
+[corpus diagnostics](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
+
+Offer one automatic-maintenance owner within the setup scope. The managed launcher,
+watcher generator, and Puma adapter (#538) are **included in Woods `2.0.0`**.
+Record the loaded gem path and revision, then verify `bundle exec woods-watch
+--help` and `bin/rails generate woods:watch --help` before using them. Follow the
+[managed startup runbook](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#managed-development-startup):
+Puma for simple Rails startup, an explicit verified Foreman command/Procfile, or
+the existing external Docker/Grove supervisor. Preview before applying within
+existing authorization. Preserve `bin/dev`; never claim an unused Procfile is
+active. Keep the portable receipt with generated files and respect edit conflicts.
+Puma installation supports the normal default `config/puma.rb` route; an existing
+environment-specific file or custom `-C` route needs a different explicit owner.
+The #542 guard included in Woods `2.0.0` checks plugin files in the active gem, including Git/path
+bundles. Older gems without the plugin skip watcher startup. Existing generated
+Puma setups need an explicit `--operation update --mode puma` (preview first) to
+upgrade the owned guard in place; repeating setup preserves it. The wrapper and
+Foreman entry still require a supporting gem. Remove owned setup before a permanent
+downgrade; do not hand-edit the receipt or its managed block.
+Run setup in the normal application bundle environment. The #540 fix in Woods `2.0.0`
+preserves `BUNDLE_PATH`, `BUNDLE_APP_CONFIG`, and group selection during preflight;
+older Git builds may falsely report missing gems. Check the loaded revision
+before changing persistent Bundler settings to work around that error.
+The #544 fix in Woods `2.0.0` makes generator refusals exit nonzero. Earlier Git builds
+can exit zero after printing a refusal; verify the diagnostic and applied setup
+before treating their exit status as installation success.
+For an interrupted install, use the generator's `--operation recover --pretend`
+before applying recovery; preserve journals when concurrent edits block it. The
+Rails generator command boots the app first: use the runbook's direct bundled
+Ruby recovery helper when an initializer prevents boot.
+
+On older gems, use the raw task only with a restart-capable external supervisor;
+do not place it bare in Foreman, where exit 75 stops the whole stack. Use the
+application's real Rails task entrypoint without a preceding `environment` task.
+Managed mode rejects idle TTL and does not take over conflicting owners. Verify
+startup catch-up, an edit, and a planned restart through the existing MCP reader;
+for Grove, also verify worktree/source/index alignment. Docker may need polling.
+Semantic vectors still need `woods:embed_incremental`; hooks and MCP registration
+do not install watcher startup.
 
 Foreign-host heartbeat trust (`WOODS_WATCH_TRUST_FOREIGN_HOST=1`, #321) is available in
 Woods `2.0.0.beta3`.
@@ -155,13 +204,18 @@ for transport, retry and custom-root limits.
 
 ## Ask before expanding scope
 
-For pgvector, match the provider output and migration dimensions within 1–2,000. Default `text-embedding-3-large` output (3,072) needs an explicit smaller provider width or another backend; never silently truncate vectors. Early adapter/generator refusal is unreleased after `2.0.0.beta3`, so check the installed revision. See the [dimension contract](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#pgvector-postgresql).
+For pgvector, match the provider output and migration dimensions within 1–2,000. Default `text-embedding-3-large` output (3,072) needs an explicit smaller provider width or another backend; never silently truncate vectors. Early adapter/generator refusal is included in Woods `2.0.0`, so check the installed revision. See the [dimension contract](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#pgvector-postgresql).
 
 Require explicit approval before adding Ollama/OpenAI, pgvector/Qdrant, secrets, Console MCP/live-data access, HTTP transport, or purge overrides. The `:local` preset avoids cloud keys but requires the `sqlite3` gem, an installed/running Ollama service, and a pulled model (`ollama pull nomic-embed-text` by default); `:shared_filesystem` avoids sqlite3 but still uses Ollama. Recommend `gem "tokenizers", "~> 0.5"` for exact counting on dense Ruby source, while stating that it is optional.
 
 ## Handoff
 
-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.
+Report the Woods version/revision, branch, files changed, commands/results, index
+path, MCP calls verified, semantic retrieval and Console status, and unresolved
+risks. For automatic maintenance record the owner, actual startup command,
+completed catch-up, observed edit/restart, and worktree verification. Report
+refresh hooks, session checks, and context hints separately. Never infer
+availability from source schemas or a live process alone.
 
 Canonical runbook: [AGENT_SETUP.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md).
 
@@ -201,3 +255,11 @@ 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.
+
+### Security-patch compatibility preflight
+
+For security-patch candidates after 2.0.0, record the loaded revision and gem
+path as well as the version. Review the [Console compatibility guide](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md#read-policy-compatibility)
+and HTTP origin compatibility at that revision before upgrading an authorized
+Console installation. The plugin does not install these fixes or establish that
+a release is published.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: woods
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta4
+  version: 2.0.1
 platform: ruby
 authors:
 - Leah Armstrong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -113,6 +113,7 @@ description: |
 email:
 - info@leah.wtf
 executables:
+- woods-watch
 - woods-mcp
 - woods-mcp-start
 - woods-console-mcp
@@ -133,6 +134,7 @@ files:
 - assets/woods-wordmark-white-with-bg.png
 - docs/AGENT_GUIDE.md
 - docs/AGENT_SETUP.md
+- docs/AUTOMATIC_MAINTENANCE.md
 - docs/BACKEND_MATRIX.md
 - docs/CLIENT_HOOKS.md
 - docs/CONFIGURATION_REFERENCE.md
@@ -171,11 +173,14 @@ files:
 - exe/woods-mcp
 - exe/woods-mcp-http
 - exe/woods-mcp-start
+- exe/woods-watch
 - lib/generators/woods/install_generator.rb
 - lib/generators/woods/pgvector_generator.rb
 - lib/generators/woods/templates/add_pgvector_to_woods.rb.erb
 - lib/generators/woods/templates/create_woods_tables.rb.erb
 - lib/generators/woods/templates/woods.rb.tt
+- lib/generators/woods/watch_generator.rb
+- lib/puma/plugin/woods.rb
 - lib/tasks/woods.rake
 - lib/tasks/woods_checks.rake
 - lib/tasks/woods_evaluation.rake
@@ -211,6 +216,7 @@ files:
 - lib/woods/checks/moved_messages.rb
 - lib/woods/chunking/chunk.rb
 - lib/woods/chunking/semantic_chunker.rb
+- lib/woods/console/adapter_family.rb
 - lib/woods/console/audit_logger.rb
 - lib/woods/console/bridge_protocol.rb
 - lib/woods/console/confirmation.rb
@@ -235,6 +241,7 @@ files:
 - lib/woods/console/sql_table_scanner.rb
 - lib/woods/console/sql_validator.rb
 - lib/woods/console/sqlite_read_guard.rb
+- lib/woods/console/stdio_transport.rb
 - lib/woods/console/table_gate.rb
 - lib/woods/console/tool_specs.rb
 - lib/woods/console/tools/tier1.rb
@@ -370,6 +377,7 @@ files:
 - lib/woods/mcp/index_reader_pinning.rb
 - lib/woods/mcp/initialization_guidance.rb
 - lib/woods/mcp/origin_guard.rb
+- lib/woods/mcp/origin_policy.rb
 - lib/woods/mcp/protocol_policy.rb
 - lib/woods/mcp/provider_probe.rb
 - lib/woods/mcp/published_lexical_retriever.rb
@@ -430,6 +438,7 @@ files:
 - lib/woods/resilience/retryable_provider.rb
 - lib/woods/resolved_config.rb
 - lib/woods/retrieval/context_assembler.rb
+- lib/woods/retrieval/corpus_status.rb
 - lib/woods/retrieval/lexical_assembler.rb
 - lib/woods/retrieval/lexical_index.rb
 - lib/woods/retrieval/query_classifier.rb
@@ -469,6 +478,7 @@ files:
 - lib/woods/source_inputs/verifier.rb
 - lib/woods/storage/graph_store.rb
 - lib/woods/storage/inapplicable_backend.rb
+- lib/woods/storage/local_corpus_stats.rb
 - lib/woods/storage/metadata_store.rb
 - lib/woods/storage/pgvector.rb
 - lib/woods/storage/qdrant.rb
@@ -491,10 +501,32 @@ files:
 - lib/woods/util/uuid5.rb
 - lib/woods/version.rb
 - lib/woods/watch/boot_snapshot.rb
+- lib/woods/watch/child_environment.rb
+- lib/woods/watch/cli.rb
 - lib/woods/watch/daemon.rb
+- lib/woods/watch/event_stream.rb
+- lib/woods/watch/guardian.rb
+- lib/woods/watch/installation.rb
+- lib/woods/watch/installation/layout.rb
+- lib/woods/watch/installation/options.rb
+- lib/woods/watch/installation/planner.rb
+- lib/woods/watch/installation/probe.rb
+- lib/woods/watch/installation/receipt.rb
+- lib/woods/watch/installation/recovery.rb
+- lib/woods/watch/installation/templates.rb
+- lib/woods/watch/lifecycle.rb
 - lib/woods/watch/listen_watcher.rb
+- lib/woods/watch/managed_child.rb
+- lib/woods/watch/managed_cleanup.rb
+- lib/woods/watch/managed_process.rb
 - lib/woods/watch/polling_watcher.rb
+- lib/woods/watch/puma_adapter.rb
+- lib/woods/watch/puma_child.rb
 - lib/woods/watch/status.rb
+- lib/woods/watch/supervision_records.rb
+- lib/woods/watch/supervision_status.rb
+- lib/woods/watch/supervisor.rb
+- lib/woods/watch/supervisor_reporting.rb
 - lib/woods/watch/tree_scan.rb
 - lib/woods/watch/watcher.rb
 - plugin/.claude-plugin/plugin.json
@@ -517,10 +549,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.beta4
-  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0.beta4/CHANGELOG.md
+  source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.1
+  changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.1/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.beta4/docs
+  documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.1/docs
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []