woods 2.0.0.beta4 → 2.0.0

data/docs/CONFIGURATION_REFERENCE.md

@@ -210,7 +210,7 @@ config.vector_store_options = {
 
 Woods uses an HNSW index over pgvector's `vector` representation, which supports
 **1–2,000 dimensions** ([pgvector's HNSW limits](https://github.com/pgvector/pgvector#hnsw)).
-Unreleased after `2.0.0.beta3`: the adapter rejects wider dimensions before any
+Included in Woods `2.0.0`: the adapter rejects wider dimensions before any
 SQL, and `woods:pgvector` rejects invalid widths before writing a migration.
 There is no automatic vector truncation or half-precision conversion.
 
@@ -282,7 +282,7 @@ in the promoted dump; the index MCP server loads that snapshot at startup or
 reload. Incremental embedding publishes changes to paths, dependencies, and
 other unit metadata even when unchanged source needs no new embedding. A run
 with no content or metadata changes keeps the existing dump and retention
-window. Unreleased after `2.0.0.beta3`: a full `Indexer#index_all` run replaces
+window. Included in Woods `2.0.0`: a full `Indexer#index_all` run replaces
 the published corpus even when a custom caller reuses in-memory vector and
 metadata stores. Deleted units, including metadata-only records, are removed;
 an empty full rebuild publishes an empty dump. Failed embedding leaves the
@@ -451,7 +451,7 @@ A malformed record invalidates the entire snapshot, rather than exposing partial
 history. Legacy bare identifier keys, omitted/null unit collections, and optional per-unit hash
 fields remain supported; timestamp strings are not restricted to a new format.
 Unit history limits count matching unit records, not the most recent snapshots
-searched (JSON fallback correction unreleased after `2.0.0.beta3`). A unit
+searched (JSON fallback correction included in Woods `2.0.0`). A unit
 missing from newer snapshots can still have retained history.
 Snapshot lists and unit history omit unusable files; direct lookup returns no
 snapshot, and a diff with an unavailable snapshot returns empty added, modified,
@@ -704,7 +704,7 @@ These variables are read by the gem and its MCP servers at runtime. They complem
 |----------|---------|---------|
 | `WOODS_RETRIEVAL_MODE` | `semantic` | Explicit packaged MCP retrieval mode: `semantic` or `lexical`. Lexical reads extraction unit JSON without provider autodetection, credentials or vector artifacts. |
 | `WOODS_DIR` | unset | MCP extraction-index path, after a positional argument and before `WOODS_OUTPUT`. See precedence below. |
-| `WOODS_OUTPUT` | unset | MCP index-path fallback when neither a positional path nor `WOODS_DIR` is set; unreleased after `2.0.0.beta3`. |
+| `WOODS_OUTPUT` | unset | MCP index-path fallback when neither a positional path nor `WOODS_DIR` is set; included in Woods `2.0.0`. |
 | `WOODS_REQUIRE_INDEX` | unset | Set to `"1"` to fail closed: the server refuses to boot (raises `MissingArtifact`) unless a real index (`woods.json`) is present. By default an extract-only host boots in pattern/structural mode without it. Explicit lexical mode requires a valid published extraction index, not `woods.json`. |
 | `WOODS_ALLOW_AUTODETECT` | unset | **Deprecated no-op.** Auto-detect is now the default; accepted for backward compatibility only. |
 | `WOODS_SEARCH_MAX_SCAN` | `500` | Cap on unit files loaded during a phase-2 (metadata/source_code) `search`. Hitting the cap sets `partial: true` in the response. |
@@ -720,7 +720,7 @@ These variables are read by the gem and its MCP servers at runtime. They complem
 | `WOODS_QDRANT_URL`, `WOODS_QDRANT_COLLECTION`, `WOODS_QDRANT_API_KEY` | n/a | Override/require Qdrant connection settings when a pgvector/Qdrant-backed index is served outside its host application (no `Woods.configuration` available). |
 | `WOODS_PG_URL` | n/a | Required when a pgvector-backed index is served outside its host application. |
 
-**MCP index path precedence (unreleased after `2.0.0.beta3`):** positional
+**MCP index path precedence (included in Woods `2.0.0`):** positional
 argument → `WOODS_DIR` → `WOODS_OUTPUT` → current directory for `woods-mcp`
 and `woods-mcp-http`. `woods-mcp-start` still requires one of the first three;
 it never silently selects the current directory. An explicitly empty
@@ -771,10 +771,24 @@ existing index before deciding another extraction is needed.
 | `WOODS_WATCH_CATCH_UP` | `1` (enabled) | Set to `"0"` to skip generation-watermark catch-up on daemon start. |
 | `WOODS_WATCH_TRUST_FOREIGN_HOST` | unset (disabled) | Set to `"1"` in each task/MCP reader to trust a foreign daemon's heartbeat for up to 15 minutes, without a local pid check. See [cross-host liveness](WATCH_DAEMON.md#cross-host-liveness) for clock bounds, degraded coverage, and startup limitations. |
 
+### Managed watcher startup
+
+**Included in Woods `2.0.0`.** `woods-watch` wraps the raw task for native
+Foreman/Puma lifecycle management. `--root PATH` selects the application working
+directory; `--boot-timeout SECONDS` defaults to `300` and bounds boot/handshake,
+not extraction. Explicit child argv follows `--`. Output-directory precedence
+remains `WOODS_OUTPUT`, then `Woods.configuration.output_dir`.
+
+Managed mode requires `WOODS_WATCH_IDLE_TIMEOUT` to be unset, preserves one owner,
+and never takes over a conflicting daemon. The optional Puma adapter only starts
+in its finalized development environment. See [startup and installation](WATCH_DAEMON.md#managed-development-startup)
+for the generator's explicit modes, portable receipt, update/removal, and the
+separate supervision status. Raw task settings above remain compatible.
+
 ### Opt-in plugin refresh hooks
 
 These settings control the plugin shell worker. Check installed
-`woods:hook_refresh` support first; the task is unreleased after 2.0.0.beta2.
+`woods:hook_refresh` support first; the task is included in Woods `2.0.0`.
 See [hook coverage and retry](WATCH_DAEMON.md#hooks-for-agent-sessions) and
 [optional context limits](WATCH_DAEMON.md#optional-bounded-context-hints).
 
@@ -807,26 +821,23 @@ tasks for manual refreshes; hook transport is not a general shell execution API.
 | `GITHUB_BASE_REF` | unset (GitHub Actions) | Build the diff range `origin/<ref>...HEAD` for `woods:incremental`; an unfetched ref makes the range unresolvable, same exit behavior. |
 | `RAILS_ENV` | `development` | Rails environment the rake tasks boot in. |
 | `WOODS_PROFILE` | unset | Set to `"1"` to log disjoint `[Woods] [profile] <phase> in N.NNs` durations, including git enrichment, reconciliation, payload sync, pointer publication (`publish`) and retention (`payload prune`). Separate `[profile total]` lines report whole extraction wall time, including unprofiled setup and failed runs; never add these totals to phase durations. Excludes process/Rails boot before extraction. Off by default. |
-| `WOODS_GIT_DIR` | unset | Absolute path to the canonical git directory. Wins over the repository Woods would otherwise find, at all three of its git call sites: per-unit `commit_count`/`change_frequency` (enrichment), `manifest.json`'s `git_branch`/`git_sha` (provenance), and the `woods:incremental` diff range. All three build their command line with `Woods::GitCommand.argv`. |
+| `WOODS_GIT_DIR` | unset | Absolute path passed directly to Git's `--git-dir`, selecting that directory's `HEAD`. For a linked worktree use its `worktrees/<id>` directory inside the complete shared Git layout. Wins over the repository Woods would otherwise find, at all three of its git call sites: per-unit `commit_count`/`change_frequency` (enrichment), `manifest.json`'s `git_branch`/`git_sha` (provenance), and the `woods:incremental` diff range. All three build their command line with `Woods::GitCommand.argv`. |
 | `GIT_BRANCH`, `GIT_SHA` | unset | Provenance for a checkout with no `.git` at all (a source tarball, a Docker `COPY` that excludes it). Ignored when a `.git` is present but unresolvable, so a stale build arg cannot mask a worktree. |
 
-**`GIT_DIR` alone is not enough for a linked git worktree.** Woods runs git as a
-subprocess, so git's own `GIT_DIR` and `GIT_COMMON_DIR` are honored wherever git
-honors them. But pointing `GIT_DIR` at a worktree's *private* git directory only
-moves the failure: that directory reaches the shared object store through a
-relative `commondir` pointer, which still resolves outside a container mount,
-and `GIT_COMMON_DIR` does not override it. `git rev-parse --git-dir` then
-succeeds while no ref resolves.
-
-Woods refuses to enrich in that state rather than writing `commit_count: 0` and
-`change_frequency: "new"` on every unit: the git keys are omitted, provenance is
-`"unknown"`, and one warning names the cause. Point `WOODS_GIT_DIR` at the
-canonical git directory (the one a worktree's `gitdir:` pointer ultimately leads
-to) and mount it:
-
-```bash
-WOODS_GIT_DIR=/canonical-git bundle exec rake woods:extract
-```
+For linked worktrees in containers, preserve access to the complete shared
+Git directory and the worktree-specific HEAD. A same-path mount that resolves
+the existing `.git` pointer needs no override. For a relocated complete layout,
+set `WOODS_GIT_DIR=/mounted-common/worktrees/<id>`, deriving `<id>` from Git's
+worktree metadata rather than the branch name. Selecting `/mounted-common`
+itself selects the primary checkout's HEAD and can produce incorrect history,
+provenance, and incremental paths. See the canonical
+[worktree mount and verification steps](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
+
+Git subprocesses inherit Git's own environment variables, so inspect existing
+`GIT_DIR` and `GIT_COMMON_DIR` settings when resolving layout problems.
+If HEAD cannot be resolved, enrichment omits the Git keys and provenance is
+`"unknown"` for a present but unresolvable `.git`; one warning names the cause.
+After correcting the layout, run a full extraction to refresh retained metadata.
 
 ### Exporters
 
@@ -846,11 +857,10 @@ The `woods-mcp` bootstrapper emits a one-line STDERR banner at startup indicatin
 
 ## Git enrichment history
 
-Current source requires **Git 2.31 or newer** for optional per-unit git
+Woods 2.0 requires **Git 2.31 or newer** for optional per-unit git
 metadata. Extraction still succeeds when git is unavailable or history cannot
 be read completely. Git enrichment is omitted in either case; a failed or
 incomplete streamed history read logs a warning.
-This requirement and the history policy below are unreleased after 2.0.0.beta2.
 
 Per-unit enrichment also requires a non-shallow repository. A shallow checkout
 or a failed repository-depth probe omits enrichment with one warning per

data/docs/CONSOLE_MCP_SETUP.md

@@ -48,7 +48,7 @@ its token, allowed origins and TLS as described in [Option C](#option-c-http-rac
 
 The rake task does two things before starting the MCP server:
 
-1. **Captures stdout before Rails boots.** Rails boot emits OpenTelemetry warnings, gem notices, and other output to stdout. An MCP client cannot parse these as JSON-RPC, they break the protocol. The rake task redirects stdout → stderr immediately, saves the real stdout fd, and restores it after boot completes.
+1. **Captures stdout before Rails boots.** Rails boot emits OpenTelemetry warnings, gem notices, and other output to stdout. An MCP client cannot parse these as JSON-RPC. The rake task saves the protocol output and redirects application stdout to stderr. In the runtime isolation fix (included in Woods `2.0.0`), that redirection remains active throughout the server's lifetime; only the MCP transport writes to the saved protocol pipe. Rails loggers, `puts`, and writes to standard output during queries stay on stderr.
 2. **Calls `Rails.application.eager_load!`** to load all application models. Without eager loading, only the models that happen to be autoloaded before the first query appear in the registry.
 
 ### MCP client configuration
@@ -83,7 +83,7 @@ rake woods:console
   │    ├─ Rails.application.eager_load!
   │    ├─ build model registry from ActiveRecord::Base.descendants
   │    ├─ Server.build_embedded(model_validator:, safe_context:, ...)
-  │    └─ MCP::Server::Transports::StdioTransport.new(server).open
+  │    └─ Woods::Console::StdioTransport.new(server, output: protocol_out).open
   │
   └─ MCP server responds to tool calls via stdin/stdout
 ```
@@ -201,7 +201,7 @@ request. Missing or incorrect tokens receive `401 Unauthorized`.
 The HTTP authentication scheme is ASCII case-insensitive (`Bearer`, `bearer`,
 or `BEARER`); the token remains case-sensitive and must match exactly after one
 space. This applies to both Console HTTP and `woods-mcp-http`. Case-insensitive
-scheme support is unreleased after `2.0.0.beta3`; use the canonical `Bearer`
+scheme support is included in Woods `2.0.0`; use the canonical `Bearer`
 spelling in client configuration for compatibility with earlier releases.
 
 For non-loopback access, `console_mcp_allowed_origins` must include the public
@@ -799,13 +799,15 @@ to enforce their narrower parameterized scope grammar.
 - **HTTP:** Check that the Rails server is running and listening on the expected port. An unauthenticated `curl http://localhost:3000/mcp/console` should return `401` when the enabled middleware and bearer-auth guard are mounted. A request with the configured bearer token proceeds to MCP protocol handling.
 - **All modes:** Run `bundle exec rake woods:console` directly in a terminal. It should hang (waiting for MCP protocol input) rather than exit immediately. If it exits, check the error output.
 
-### Rails boot noise breaks MCP protocol
+<a id="rails-boot-noise-breaks-mcp-protocol"></a>
 
-The rake task redirects stdout to stderr before Rails boots specifically to prevent this. If you see JSON parse errors from the MCP client, check:
+### Rails logs break MCP protocol
 
-1. You are using `bundle exec rake woods:console`, not `rails runner exe/woods-console` directly (the runner path handles this too, but via a different mechanism).
-2. No `puts` or `print` calls run at boot in your initializers before the task can capture stdout.
-3. Try running `bundle exec rake woods:console 2>/dev/null` to isolate, the MCP protocol output goes to stdout, Rails noise goes to stderr.
+Prefer `bundle exec rake woods:console`: it captures output before the Rails environment boots. Direct `rails runner` invocation can redirect output only after Rails has booted; it cannot recover an already contaminated protocol stream.
+
+The runtime isolation fix is included in Woods `2.0.0`. Earlier builds restore stdout after boot, so a logger that writes there can interleave SQL or application logs with MCP responses. On those builds, configure the Console process's application logger to write to stderr or a file. Discarding stderr does not fix logs written to stdout.
+
+With a build containing the fix, application output remains on stderr during tool calls. If protocol contamination persists, inspect wrapper scripts and output emitted before the rake task starts; reserve stdout for MCP and retain stderr for diagnosis. Do not disable Console redaction or credential scanning to troubleshoot transport logging.
 
 ### Models not visible to `console_status`
 

data/docs/DOCKER_SETUP.md

@@ -87,9 +87,24 @@ docker compose exec app bundle exec rake woods:extract_framework
 
 Run the watcher as its own development service or process-manager entry, not as a one-off terminal command. Docker Desktop bind mounts may not deliver reliable native filesystem events; set `WOODS_WATCH_POLL=1` for polling when needed. The watcher updates structural generations automatically, while semantic vectors still require `woods:embed_incremental`.
 
+Use the application's actual Rails task entrypoint. If its root `Rakefile` wraps
+Compose, the container may need `bundle exec rails woods:watch`. Keep the raw
+task under one external restart owner: `restart: unless-stopped` recovers after
+Docker restarts while respecting an intentional stop; `on-failure` covers failed
+process exits but not Docker restart. Leave idle TTL unset for continuous work.
+
+Validate `docker compose config`: explicit YAML anchor keys can replace inherited
+mounts/environment, and short `depends_on` does not establish database readiness.
+Preserve the existing source/bundle mounts and use the application's healthcheck
+convention. With Grove, include the watcher in the applicable shared or isolated
+services list and align source/index mounts to the selected worktree. Follow
+[Docker and Grove verification](AUTOMATIC_MAINTENANCE.md#docker-verify-the-resolved-service)
+instead of copying a generic service that loses required settings.
+
 When host-side tasks or one-off containers read the daemon's shared index,
 `WOODS_WATCH_TRUST_FOREIGN_HOST=1` lets those readers trust its recent heartbeat.
 Set it in each reader process; Docker does not forward host variables by default.
+Ordinary Index MCP reads do not need this trust or the extraction writer lock.
 See [cross-host liveness](WATCH_DAEMON.md#cross-host-liveness) for the 15-minute
 crash-detection bound and single-supervisor requirement.
 

data/docs/EVALUATION.md

@@ -90,8 +90,8 @@ bundle exec ruby -Ilib bench/evaluation/runner.rb
   strategy selection also fail. The baseline format is developer-only and is
   **not** the `EVAL_BASELINE_FILE` aggregate-threshold format.
 
-B-190/B-191 recapture on Ruby 4.0.6 (five warmed pipeline repetitions per query; Ruby 3.3.1
-and 3.4.10 replay the same answers):
+B-190/B-191 baseline, with the #549 output-label refresh captured on Ruby 4.0.6
+(five warmed pipeline repetitions per query):
 
 | Strategy | Queries | Precision@5 | Recall | MRR | Mean actual context tokens |
 |---|---:|---:|---:|---:|---:|
@@ -99,8 +99,14 @@ and 3.4.10 replay the same answers):
 | Vector | 4 | 0.313 | 0.375 | 0.625 | 1,041.2 |
 | Graph | 8 | 0.813 | 0.519 | 1.000 | 1,041.1 |
 | Hybrid | 4 | 0.750 | 0.396 | 1.000 | 1,058.8 |
-| Direct with type filtering | 4 | 0.375 | 0.750 | 0.625 | 551.0 |
-| Within-type vector fallback | 4 | 0.400 | 1.000 | 1.000 | 1,250.8 |
+| Direct with type filtering | 4 | 0.375 | 0.750 | 0.625 | 552.0 |
+| Within-type vector fallback | 4 | 0.400 | 1.000 | 1.000 | 1,251.8 |
+
+The clearer `Retrieval metadata records` heading adds one exact `cl100k_base`
+token to each of the eight direct/fallback contexts. The other 20 contexts,
+retrieved identifiers and order, annotations, and quality metrics are unchanged.
+The refresh reuses captured vectors and the pinned `tiktoken 0.11.0` tokenizer;
+it performs no new model inference.
 
 Precision@5 divides relevant hits by the actual returned slice size (up to five),
 not always by five. Recall divides retrieved relevant units by all annotated

data/docs/EXTRACTOR_REFERENCE.md

@@ -32,6 +32,14 @@ Extractors discover code one of two ways:
 
 Some extractors combine both (e.g., `JobExtractor` scans directories first, then supplements with `ApplicationJob.descendants`).
 
+Discovery is not exhaustive. A standalone module under `app/models` that is
+called through singleton methods is not discovered by the model/PORO paths;
+conventional concerns and app modules included by live models have separate
+concern discovery. This gap is tracked in [#552](https://github.com/lost-in-the/woods/issues/552).
+Separately, dependency scanning does not capture every method-body constant
+reference ([#475](https://github.com/lost-in-the/woods/issues/475)). A missing unit
+or edge is not proof of unused code; cross-check the application source.
+
 ### Identifier naming (source-derived units)
 
 File-based extractors derive an identifier in three steps, first match wins:
@@ -746,11 +754,15 @@ History is limited to commits reachable from `HEAD` in the past 365 days,
 including merged branch history. Unmerged branches, remote refs, and tool
 checkpoint refs do not contribute. Commands run against the application root;
 when `WOODS_GIT_DIR` is set, `HEAD` belongs to that explicitly selected git
-directory, which may differ from a linked worktree's HEAD.
+directory. For a linked worktree, select its `worktrees/<id>` directory within
+the complete shared Git layout; selecting the shared root instead uses the
+primary checkout's HEAD. See the [worktree mount guide](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
 
 After upgrading from a version that included all refs, run a full
 `woods:extract` to replace previously published git metadata. Incremental
-extraction refreshes only the units it rewrites.
+extraction refreshes only the units it rewrites. A commit alone does not
+necessarily trigger the source-file watcher; run full extraction when current
+Git history is required.
 
 | Field | Description |
 |-------|-------------|

data/docs/FAQ.md

@@ -134,7 +134,7 @@ When a model includes a concern, the behavior defined in that concern is part of
 
 ### How do I update the index after code changes?
 
-Use incremental mode, which re-extracts only files that have changed since the last run:
+Use incremental mode to dispatch a selected batch of changed paths:
 
 ```bash
 bundle exec rake woods:incremental
@@ -143,7 +143,12 @@ bundle exec rake woods:incremental
 docker compose exec app bundle exec rake woods:incremental
 ```
 
-Incremental mode is ideal for CI pipelines and local development workflows. It is typically 5-10× faster than a full extraction. Nine unit types, `route`, `middleware`, `engine`, `scheduled_job`, `state_machine`, `factory`, `event`, `database_view`, and `rails_source`, don't map to individual files, so incremental mode re-runs their extractor **wholesale** whenever the relevant trigger path changes (e.g. `config/routes.rb` for routes, `Gemfile.lock` for middleware/engines/rails_source; `rails_source` participates only when `include_framework_sources` is enabled). You never need to run a full extraction just because one of these changed, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for details.
+The default Git range is `HEAD~1`; CI variables, an explicit range, or
+`CHANGED_FILES` can select another batch. Incremental extraction also refreshes
+affected concern consumers and re-runs whole-app extractors when their trigger
+paths change. It can reduce work, but has no universal speedup: Rails boot, graph
+work, and publication still take time. See the [incremental contract](INCREMENTAL_EXTRACTION.md)
+for scope, whole-app triggers, and cases that require a full extraction.
 
 ---
 
@@ -411,7 +416,13 @@ When you run `rake woods:embed`, Woods generates embedding vectors for each extr
 
 ### What is the `codebase_retrieve` tool for?
 
-`codebase_retrieve` is the primary semantic search tool on the Index Server. It accepts a natural-language description of what you're looking for ("find where user email validation happens", "which services send Stripe API calls") and returns the most relevant extracted units as formatted context. It requires embedding configuration, without an embedding provider the tool responds with an error (`isError`, code `:not_configured`) and a remediation hint covering provider setup and the `search` tool for pattern-based matching in the meantime. Token budget is controlled by `config.max_context_tokens` (default: 8000).
+`codebase_retrieve` ranks extracted units for a natural-language query, such as
+"find where user email validation happens". Default semantic mode requires an
+embedding provider and vector store. Explicit lexical mode ranks published
+extraction text without either: set `WOODS_RETRIEVAL_MODE=lexical` in the MCP
+process environment and restart it. There is no automatic fallback between
+modes. See the [retrieval guide](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval)
+for setup, ranking evidence, and the estimated text-budget contract.
 
 ---
 

data/docs/GETTING_STARTED.md

@@ -12,15 +12,15 @@ If an agent will perform the installation, use the safety and handoff checklist
 
 ## 1. Install the gem
 
-Use the [README release table](../README.md) to choose a version, then confirm
-that **exact version is published** on the [RubyGems versions page](https://rubygems.org/gems/woods/versions)
-before editing the Gemfile. A prepared release checkout can update the README
+Choose a version from the [RubyGems versions page](https://rubygems.org/gems/woods/versions)
+and confirm that **exact version is published** before editing the Gemfile.
+A prepared release checkout can update the documentation
 before its gem is published; if the version is absent, choose an available
 version or wait for publication.
 
 If the published 2.x line has only beta or release-candidate versions, use an
-exact pin to the published prerelease, following the README's prerelease
-instructions; `~> 2.0` does not select prereleases. Follow the selected version's
+exact pin to the published prerelease; `~> 2.0` does not select prereleases.
+Follow the selected version's
 tag documentation. The `main` guides may describe features absent from the
 published gem.
 
@@ -148,21 +148,22 @@ Reconnect the MCP server and check `woods_status`. For OpenAI, pgvector, Qdrant,
 
 ### Keep the index current
 
-For automatic maintenance, keep a watcher running beside the Rails development process:
-
-```bash
-bin/rails woods:watch
-```
-
-```text
-# Procfile.dev
-web:   bin/rails server
-woods: bundle exec rake woods:watch
-```
+Enable one watcher through the application's normal development startup. The
+[managed startup guide](WATCH_DAEMON.md#managed-development-startup) covers
+opt-in Puma integration for a simple Rails application, an owned Foreman entry
+for existing Procfile workflows, and external supervision for Docker/Grove.
+The managed launcher and generator are **included in Woods `2.0.0`**;
+check the installed commands before using them. Older packages can run the raw
+`bin/rails woods:watch` task under an external restart-capable supervisor.
 
 On startup it reconciles changes made since the last successful generation. While running it batches file events, reloads Rails code when safe, extracts affected units, and publishes atomically. The Index Server detects the new generation on its next call and reloads automatically. After the initial extraction, ordinary code edits need no manual extraction or MCP restart.
 
-When dependencies, initializers, database configuration, credentials, or schema change, Rails cannot safely reload all captured state. The watcher records a degraded reason and exits with status 75 so the process manager can restart it. Docker bind mounts may require polling; follow [Watch daemon](WATCH_DAEMON.md).
+When dependencies, initializers, database configuration, credentials, or schema
+change, the raw task exits 75 to request a fresh Rails boot. The managed launcher
+handles that restart internally; an external supervisor must handle it for the
+raw task. Do not add the bare task to Foreman. Docker bind mounts may require
+polling. See the [low-interaction workflow](AUTOMATIC_MAINTENANCE.md) for ownership,
+hooks, and the checks that establish automatic maintenance is active.
 
 The watcher maintains the structural index. If semantic retrieval is enabled, also run `bin/rails woods:embed_incremental` to update vectors. Without a resident watcher, run `bin/rails woods:incremental` after changes. Use a full `woods:extract` after major upgrades or when validation reports drift. CI and shared-artifact patterns are covered in [Incremental extraction](INCREMENTAL_EXTRACTION.md).
 

data/docs/INCREMENTAL_EXTRACTION.md

@@ -89,8 +89,13 @@ Recovery choices, in the order they are worth trying:
 3. Run a full `woods:extract` when the range cannot be repaired this run.
 
 The diff itself is rooted at the extracted application (`git -C Rails.root`),
-so it cannot read whatever checkout the process happened to start in — the
-same rooting rule the manifest's git provenance follows.
+independently of the process working directory. An explicit `WOODS_GIT_DIR`
+selects that Git directory's HEAD for both the diff and manifest provenance.
+For a linked worktree, use its worktree-specific directory within the complete
+shared layout; selecting the shared root instead reads the primary checkout's
+HEAD. See [worktree mount verification](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
+Git-only changes may not trigger the source-file watcher; see the
+[watcher limitation](WATCH_DAEMON.md#watcher-backends).
 
 Named, source-defined app modules included by runtime models are tracked as concern units even
 outside `concerns/` directories. Changing their source refreshes their includers,
@@ -100,7 +105,7 @@ to populate these previously missing source mappings.
 
 ## Handled source errors and retry
 
-Unreleased after `2.0.0.beta3`: when an incremental extraction or named refresh
+Included in Woods `2.0.0`: when an incremental extraction or named refresh
 records a handled consumer error (for example malformed locale or schedule
 YAML), it raises `Woods::ExtractionError` before publishing. Empty output from
 that failed consumer does not authorize replacing or deleting its last-good

data/docs/INDEX_LAYOUT.md

@@ -94,8 +94,8 @@ families and `manifest.provenance.mode`; it is not Rails runtime evidence.
 ### Semantic graph validation
 
 `woods:validate` checks raw graph data against the unit indexes and artifacts in
-one pinned published generation. This validation is unreleased after
-`2.0.0.beta2`. It checks the shapes of `nodes`, `edges`, `reverse`, `file_map`,
+one pinned published generation. This validation is included in Woods `2.0.0`.
+It checks the shapes of `nodes`, `edges`, `reverse`, `file_map`,
 `type_index`, and optional `variants`; typed identities must be unique and agree
 with the actual indexed units. Forward sources must exist. Reverse, file, and
 type memberships must match the union of primary and variant contributions.

data/docs/MCP_SERVERS.md

@@ -56,6 +56,12 @@ Prefer the application's bundle and a project-scoped configuration:
 
 `woods-mcp-start` checks that the directory and published manifest exist, then replaces itself with `woods-mcp`. It does not install dependencies or restart a crashed process.
 
+The MCP client owns this reader process. Automatic index maintenance has its own
+[watcher startup](WATCH_DAEMON.md#managed-development-startup): configuring MCP
+does not enable it. A running reader sees new published generations on subsequent
+calls without reconnecting. Verify a real edit, not only a successful connection;
+see [automatic maintenance](AUTOMATIC_MAINTENANCE.md).
+
 `woods_status.index.woods_version` identifies the last publisher of the served
 manifest; `server.version` identifies the running MCP reader. Missing writer
 provenance is `null`. See [manifest writer provenance](PUBLISHED_INDEX.md#manifest-writer-provenance).
@@ -133,12 +139,23 @@ before using `codebase_retrieve`, including after reload. The guidance grants
 no extraction, configuration-change, or Console authorization. Detailed usage
 belongs in the [agent guide](AGENT_GUIDE.md).
 
-This addition is unreleased after `2.0.0.beta2`. The SDK omits `instructions`
+This addition is included in Woods `2.0.0`. The SDK omits `instructions`
 when negotiating protocol `2024-11-05`; that behavior is preserved. Older gems,
 legacy clients, and clients that do not show server instructions can use the
 agent guide or investigation skill. Leave protocol negotiation enabled rather
 than pinning a newer version solely to obtain guidance.
 
+### Structural and semantic readiness
+
+`ready` describes the published structural index. A reachable embedding provider
+and bootstrap state `hydrated` do not establish that semantic stores contain
+data. Supporting readers also report `retriever.corpus`: locally known vector
+and metadata entry counts, counts by type, and whether those stores are empty,
+populated, or unknown. These are stored records (including chunks), not a count
+of extracted units with verified embedding coverage. Positive counts do not
+prove complete coverage or working provider access. See
+[semantic corpus diagnostics](RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
+
 ### Tools (29 — 14 registered in the packaged default)
 
 The Index Server defines 29 schemas across core and conditional capabilities. The normal packaged executable registers the 14 tools below; the remaining schemas require the specialized wiring described afterward.
@@ -194,7 +211,7 @@ process after publishing a new embedded index.
 
 ### Graph-analysis pages
 
-Unreleased after `2.0.0.beta3`: `graph_analysis` enforces its advertised default
+Included in Woods `2.0.0`: `graph_analysis` enforces its advertised default
 of 20 rows per section. Pass `limit` and `offset` to page one selected `analysis`
 or each section of `analysis: "all"`. Explicit limits also bound nested hub
 `dependents` lists. Older servers may return every section row when `limit` is
@@ -214,7 +231,7 @@ they do not establish complete source-reference coverage.
 Search responses retain `query`, `result_count`, and `results`; `result_count`
 is the number returned, not an estimated total. The additive `completeness`
 object describes the requested types, literal filters, and fields in the pinned
-generation. This contract is unreleased after `2.0.0.beta2`.
+generation. This contract is included in Woods `2.0.0`.
 
 | `reason` | `status` | `has_more` | `total_matches` |
 |---|---|---|---|
@@ -260,16 +277,16 @@ Supporting servers expose the annotated, paginated traversal result in
 stdio and HTTP servers. Read `data.total_is_exact`, `data.graph_coverage`, budget
 counters and optional explanation witnesses there; `content[0].text` and
 `structuredContent.text` keep the same human-readable rendering. No `format`
-tool argument is needed or accepted. This additive data payload is unreleased
-after `2.0.0.beta3`; verify the installed response before relying on it. Older
+tool argument is needed or accepted. This additive data payload is included in
+Woods `2.0.0`; verify the installed response before relying on it. Older
 human-renderer responses can carry only text. The structured nodes and witnesses
 cover the same page, not an additional traversal or an unpaginated graph.
 
 Successful responses carry `graph_coverage` with `scope: "published_relationships"`,
 `source_references: "not_exhaustive"`, and a human-readable `notice`. Text formats
 show the same notice, including compact, root-only and empty-page responses.
-This response metadata and the total exactness field below are unreleased after
-Woods `2.0.0.beta3`; older servers need the same conservative interpretation.
+This response metadata and the total exactness field below are included in Woods
+`2.0.0`; older servers need the same conservative interpretation.
 
 ### Dependency traversal budgets
 
@@ -310,14 +327,14 @@ for stable pages. No wall-clock deadline is used, so cutoffs are deterministic.
 Budgets cover traversal work after per-generation graph loading and cache
 preparation (JSON parsing, typed-edge normalization, node types and database
 metadata). They do not cap that initial load, elapsed time, or total process
-memory. These arguments are unreleased in Woods 2.0.0.beta2; check the connected
+memory. These arguments are included in Woods `2.0.0`; check the connected
 server's tool schema before sending them to an older installation.
 
 ### Traversal explanations
 
 Supporting development versions accept `explain: true` on `dependencies` and
-`dependents`. Check the connected schema first; this option is unreleased after
-2.0.0.beta2. Omitted or false keeps the existing compact response.
+`dependents`. Check the connected schema first; this option is included in Woods
+`2.0.0`. Omitted or false keeps the existing compact response.
 
 The additive `explanation` object contains:
 
@@ -343,7 +360,7 @@ it describes identifier-level reachability, never a uniquely typed path.
 A true value means only that identities along this witness have unambiguous
 types. It does not establish source-reference coverage or observed execution.
 Text labels this `witness types unambiguous=yes/no`; the JSON key and its meaning
-remain unchanged. The text label change is unreleased after `2.0.0.beta3`.
+remain unchanged. The text label change is included in Woods `2.0.0`.
 `types` filters retain the compact traversal's identifier-level semantics: any
 registered type can qualify a name, while edge evidence keeps its actual source
 owner. Multiple relationship kinds between the same endpoints remain separate.

data/docs/MCP_TOOL_COOKBOOK.md

@@ -356,7 +356,7 @@ column.
 Use `lookup` on the returned identifier for source, actions, and routes. Search
 `source_code` for textual matches beyond names. Supporting versions distinguish
 exact totals from a bounded result prefix; `partial` means this is discovery,
-not an exhaustive list. Completeness metadata is unreleased after `2.0.0.beta2`;
+not an exhaustive list. Completeness metadata is included in Woods `2.0.0`;
 see the [search contract](MCP_SERVERS.md#search-completeness).
 
 ---

data/docs/MCP_WORKTREE_SETUP.md

@@ -66,7 +66,19 @@ The published payload's `manifest.json` records the extraction's `git_branch` an
 
 Woods uses worktree-aware Git commands. If a present `.git` cannot be resolved, provenance is `"unknown"`; stale `GIT_BRANCH`/`GIT_SHA` values are not substituted. Those environment variables are fallbacks only when the root has no `.git` or Git is unavailable. Temporal snapshots skip an unknown SHA.
 
-For extraction in a container, make the canonical Git directory and the worktree's pointer resolvable there. Mounting only the private worktree Git directory can leave its shared object store unreachable. Follow the [Git provenance troubleshooting guide](TROUBLESHOOTING.md) for mount and `WOODS_GIT_DIR` guidance, and the [published index layout](INDEX_LAYOUT.md) when locating the manifest.
+For extraction in a container, mount the complete shared Git layout at the
+original path so the worktree's `.git` pointer resolves without an override,
+or select `/mounted-common/worktrees/<id>` with `WOODS_GIT_DIR` inside a
+relocated complete mount. Derive `<id>` from Git metadata, not the branch name.
+Selecting the shared root instead uses the primary checkout's HEAD, affecting
+provenance, per-file history, and incremental paths. Follow the
+[worktree mount and verification steps](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees)
+and the [published index layout](INDEX_LAYOUT.md) when locating the manifest.
+
+Compare the branch and exact SHA in the extraction environment with the intended
+worktree, then verify the published manifest after full extraction. A commit
+alone may not trigger the source-file watcher; use full `woods:extract` when
+current Git history is required.
 
 ## Troubleshooting
 

data/docs/PUBLISHED_INDEX.md

@@ -111,7 +111,7 @@ The reader wraps `Woods::MCP::IndexReader` with `auto_refresh: false`; the unit
 
 ### Actual unit types and directory families
 
-Unreleased after `2.0.0.beta3`: `unit` and `units` accept actual published
+Included in Woods `2.0.0`: `unit` and `units` accept actual published
 `graphql_type`, `graphql_mutation`, `graphql_resolver`, `graphql_query`, and
 `gem_source` types. Enumeration preserves each unit's actual type rather than
 labeling every GraphQL member `graphql` or every gem source `rails_source`.

data/docs/README.md

@@ -10,7 +10,7 @@ Woods extracts runtime-accurate Rails context and serves it to coding agents thr
 | Ask an agent to install or configure Woods | [Agent setup runbook](AGENT_SETUP.md) | A safe, reviewable install with an agent handoff report |
 | Configure an MCP client or Docker path | [MCP servers](MCP_SERVERS.md) | A working Index Server and, if authorized, an optional Console Server |
 | Use Woods tools as an agent | [Agent guide](AGENT_GUIDE.md) | A repeatable query workflow for code context, flows, and blast radius |
-| Keep the index current automatically | [Watch daemon](WATCH_DAEMON.md) | A resident development process that catches up changes and republishes the index |
+| Keep the index current automatically | [Automatic maintenance guide](AUTOMATIC_MAINTENANCE.md) | A setup with supervised indexing, automatic reader refresh, and clear hook ownership |
 | Upgrade from Woods 1.x | [Upgrade to Woods 2.0](UPGRADING_TO_2.md) | A backed-up, re-indexed, verified v2 installation |
 | Diagnose an error | [Troubleshooting](TROUBLESHOOTING.md) | Symptom-to-cause checks for extraction, MCP, embeddings, storage, and Docker |
 | Contribute to Woods | [Contributing](../CONTRIBUTING.md) | A tested change with synchronized docs and plugin guidance |
@@ -41,6 +41,7 @@ and stdio or Streamable HTTP endpoints directly.
 
 ## Index lifecycle
 
+- [Automatic maintenance guide](AUTOMATIC_MAINTENANCE.md): recommended development workflow and a section-by-section map of watcher, indexing, MCP, and hook documentation.
 - [Source freshness](SOURCE_FRESHNESS.md): verify dirty source against a served generation, establish a fresh-process baseline, and understand bounded unknown results.
 
 - [Retrieval guide](RETRIEVAL_GUIDE.md): configure embeddings and understand semantic retrieval, ranking, and token budgets.