woods 2.0.0.beta4 → 2.0.1

data/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to Woods
 
 <!-- release-state:contributing-intro -->
-Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta4/AGENTS.md).
+Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.0.1/AGENTS.md).
 <!-- release-state:end -->
 
 ## Choose the right channel
@@ -46,7 +46,7 @@ Create a branch from current `main`. Keep each pull request to one logical chang
 | `plugin/skills/` | Distributed Woods skills (setup/upgrade, MCP configuration, investigation, agent enablement, diagnosis) |
 
 <!-- release-state:contributing-architecture -->
-Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta4/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
+Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.0.1/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
 <!-- release-state:end -->
 
 ### Agent orientation and static self-map
@@ -460,6 +460,16 @@ fresh tag-push CI run. Updating main's tooling alone never authorizes different
 candidate bytes. Main's v2 release contract remains unchanged. Do not create or
 push tags, dispatch, publish, or claim 1.6.3 is available during preparation.
 
+### 2.0.1 maintenance CI contract
+
+The 2.0.1 candidate uses trusted main's reviewed maintenance profile, not this
+candidate's copy of the release tooling. That profile intentionally omits
+`exact_ci_jobs` and `package_spec`: validation uses the normal v2 required-job
+list and `spec/integration/packaged_gem_spec.rb`, rather than the legacy matrix
+or package spec. The 1.6.4 profile is separate and has no C-locale artifact-reader
+CI lane. Candidate evidence must identify the actual jobs and artifacts tested;
+profile approval and publication remain maintainer steps.
+
 ### Stable branches
 
 A stable branch is `N-M-stable`, cut from the release tag. Create one only when a released line needs a patch after a newer major has shipped on `main`; until then, `main` is the development branch. The explicitly approved short-lived `release/1.6.3` security exception above does not establish an `N-M-stable` branch.

data/README.md

@@ -46,30 +46,12 @@ Run installation and extraction commands from your Rails application root in its
 
 ### 1. Install and configure
 
-These steps are for **Woods 2.x**. Choose a published 2.x version from the release information below and confirm it on [RubyGems](https://rubygems.org/gems/woods/versions). If only prereleases are available, use an exact prerelease pin; `~> 2.0` will not select one. Follow the chosen version's tag documentation rather than assuming every feature on `main` is published. If you choose 1.x, use its tag documentation instead of this quickstart.
-
-<details>
-<summary>Release information and Gemfile version constraints</summary>
+These steps are for **Woods 2.x**. Choose a published 2.x version from [RubyGems](https://rubygems.org/gems/woods/versions). If only prereleases are available, use an exact prerelease pin; `~> 2.0` will not select one. Follow the chosen version's tag documentation rather than assuming every feature on `main` is published. If you choose 1.x, use its tag documentation instead of this quickstart.
 
 <!-- release-state:version-banner -->
-> **This tree documents version 2.0.0.** It is a major update from 1.x: read [what changed and how to upgrade](docs/UPGRADING_TO_2.md) before updating. The full history is in the [CHANGELOG](CHANGELOG.md).
->
-> `main` is the development branch and can run ahead of the latest published gem. The gem badge above shows the latest published version; documentation for a published version lives on its tag.
->
-> ### Version: this tree declares prerelease 2.0.0.beta4; `main` documents 2.0.0
->
-> | Line | Version | Documentation |
-> |---|---|---|
-> | Documented here | **2.0.0**, unreleased | this README and the [documentation index](docs/README.md) |
-> | Declared prerelease | **2.0.0.beta4** | [the v2.0.0.beta4 tag](https://github.com/lost-in-the/woods/tree/v2.0.0.beta4) |
-> | Latest published gem | **1.6.2** | [the v1.6.2 tag](https://github.com/lost-in-the/woods/tree/v1.6.2) |
->
-> RubyGems treats 2.0.0.beta4 as a prerelease, so `gem "woods", "~> 2.0"` does not resolve it. Once published, install it explicitly with `gem "woods", "2.0.0.beta4"`. The released constraint stays `gem "woods", "~> 1.6"`.
 <!-- release-state:end -->
 
-</details>
-
-Expand the release information above, then add its appropriate `gem "woods", …` declaration to your Gemfile's `:development` group and run:
+Once a stable 2.x release is published, add `gem "woods", "~> 2.0"` to your Gemfile's `:development` group. For a prerelease, use its exact published version instead. Then run:
 
 ```bash
 bundle install
@@ -128,13 +110,16 @@ The [lexical guide](docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval) an
 
 ## Keeping the index current
 
-Run a watcher alongside your development processes:
-
-```bash
-bin/rails woods:watch
-```
+Run one watcher through your normal development startup. It catches up on
+changes, publishes complete generations, and lets the Index Server refresh on
+later tool calls. The [startup guide](docs/WATCH_DAEMON.md#managed-development-startup)
+covers Puma, existing Foreman workflows, and Docker/Grove supervision. Managed
+startup requires a supporting gem; **check installed capabilities**. Older packages run the raw
+`bin/rails woods:watch` task under an external restart-capable supervisor.
 
-It catches up on changes, publishes complete generations, and lets the Index Server refresh on later tool calls. Use a process supervisor for changes that require the watcher to restart. Without a watcher, run `bin/rails woods:incremental` after edits or `bin/rails woods:extract` for a full rebuild.
+Without a watcher, run `bin/rails woods:incremental` after edits or
+`bin/rails woods:extract` for a full rebuild. MCP registration alone does not
+enable automatic maintenance.
 
 Incremental cost depends on the affected code and relationships; broad changes can cost as much as a full extraction. Semantic embeddings have a separate update step. See [Watch daemon](docs/WATCH_DAEMON.md), [incremental extraction](docs/INCREMENTAL_EXTRACTION.md), and [source freshness](docs/SOURCE_FRESHNESS.md).
 

data/docs/AGENT_GUIDE.md

@@ -5,7 +5,7 @@ This guide is for coding agents using an already connected Woods MCP server. Woo
 Supporting servers also send a concise version of this workflow in MCP
 initialization/discovery instructions, without requiring an installed plugin.
 Check the connected server's version and registered tools; this feature is
-unreleased after `2.0.0.beta2`, and protocol `2024-11-05` omits the field.
+included in Woods `2.0.0`, and protocol `2024-11-05` omits the field.
 The [initialization contract](MCP_SERVERS.md#initialization-guidance) describes
 availability. This guide remains the detailed reference when instructions are
 absent or the client does not display them.
@@ -16,7 +16,7 @@ Call `woods_status` before relying on the index. Check:
 
 - the index is ready and has a current generation;
 - unit counts are non-zero for relevant types;
-- retrieval is enabled before choosing `codebase_retrieve`;
+- the retrieval mode and its data are usable before choosing `codebase_retrieve`;
 - warnings do not indicate a stale or partial index.
 
 If status is unhealthy, report the evidence and ask the owner to extract or refresh. Do not fill gaps by asserting that Woods found nothing.
@@ -35,7 +35,9 @@ Use this four-step loop for most codebase questions:
 3. **Traverse** from that identifier with `dependencies`, `dependents`, or `trace_flow`.
 4. **Verify** important claims against the returned source paths and current repository files.
 
-Identifiers are namespaced and typed. Never invent one from a filename when `search` can return the exact value.
+Identifiers are namespaced and typed. Never invent one from a filename when
+`search` can return the exact value. Carry both the returned `identifier` and
+`type` into `lookup`; the same identifier can belong to more than one unit type.
 
 ## Pick the smallest useful tool
 
@@ -54,7 +56,7 @@ Identifiers are namespaced and typed. Never invent one from a filename when `sea
 | Find dependencies that change faster than their dependents | `graph_analysis` with `analysis: "volatile_dependencies"` | `recent_changes` |
 | See a Packwerk boundary before calling across it | `graph_analysis` with `analysis: "undeclared_package_edges"` | `lookup` on the package unit |
 | Find central or high-impact units | `pagerank` | `dependents` |
-| Ask a conceptual question | `codebase_retrieve` if status says ready | `lookup` and graph tools |
+| Ask a conceptual question | `codebase_retrieve` after checking its retrieval mode and data | `lookup` and graph tools |
 | Refresh after a published extraction | `reload` | `woods_status` |
 
 Do not start with a broad graph or semantic query when an exact search will answer the question with less noise.
@@ -64,7 +66,7 @@ Do not start with a broad graph or semantic query when an exact search will answ
 ### Understand a model
 
 1. `search(query: "^Order$", types: ["model"])`
-2. `lookup(identifier: <returned identifier>)`
+2. `lookup(identifier: <returned identifier>, type: <returned type>)`
 3. Read resolved schema, associations, validations, scopes, enums, callbacks, and included concerns.
 4. `dependencies(identifier: ..., depth: 1)` for collaborators.
 5. `dependents(identifier: ..., depth: 1)` for callers and affected features.
@@ -74,11 +76,21 @@ Woods may inline concern behavior beside the owning model. Distinguish the resol
 ### Trace a feature flow
 
 1. Search for the route, controller action, job, mailer, or service at the user-visible entry point.
-2. Call `trace_flow` on the exact identifier.
+2. Call `trace_flow(entry_point: "UnitIdentifier#method")` for a method on that exact indexed unit, or use `UnitIdentifier` for the whole unit. For example, use `CheckoutService#order` for its `order` method.
 3. Inspect important or ambiguous nodes with `lookup`.
 4. Follow missing branches with `dependencies` and a narrow `via` filter when useful.
 5. Verify behavior that depends on conditions, dynamic dispatch, or runtime data in source and tests.
 
+Bare names identify units, not methods across the application. For example,
+`trace_flow(entry_point: "order")` selects the indexed `order` unit, which may
+be a FactoryBot factory in `spec/factories/`. Find the owning class with
+`search` and `lookup`, then pass its identifier with `#order`.
+
+Flow assembly derives operations from source. A receiverless local call such
+as `order` inside `CheckoutService#call` may remain visible without expanding
+the local method body. Follow it in source or trace `CheckoutService#order`
+explicitly. A flow is not proof of runtime execution or exhaustive call coverage.
+
 ### Assess change impact
 
 1. Search and look up the unit being changed.
@@ -123,7 +135,7 @@ an exact total within the requested index/query domain. Narrow types, literal
 prefix/suffix filters, or deep fields when `partial` is true. A detected artifact
 failure remains an error with unknown completeness, never proof of no matches.
 
-This metadata is unreleased after `2.0.0.beta2`; older servers may omit it.
+This metadata is included in Woods `2.0.0`; older servers may omit it.
 Do not infer completeness from a full page or missing metadata. See the
 [search response contract](MCP_SERVERS.md#search-completeness).
 
@@ -136,7 +148,7 @@ call graphs: selective scanning can miss arbitrary method-body constant referenc
 including generic PORO and library targets. No dependents or test-only dependents
 do not establish absence of production callers. Check source before claiming absence.
 The `graph_coverage` notice makes this scope explicit in supporting responses;
-that metadata is unreleased after `2.0.0.beta3`.
+that metadata is included in Woods `2.0.0`.
 
 Start at depth 1 or 2. A deeper unfiltered traversal can obscure the direct evidence that matters. Common relationship values include associations (`belongs_to`, `has_many`, `has_one`), code references, renders, redirects, form actions, and navigation links.
 
@@ -148,8 +160,8 @@ across turns. In a multi-database app each row names the unit's database.
 
 On supporting servers, inspect `structuredContent.data` for traversal nodes,
 `graph_coverage`, exactness, budgets and optional explanation witnesses, regardless
-of the text renderer. This packaged stdio/HTTP payload is unreleased after
-`2.0.0.beta3`; check the actual response and use its text when structured data is
+of the text renderer. This packaged stdio/HTTP payload is included in Woods
+`2.0.0`; check the actual response and use its text when structured data is
 absent. There is no traversal `format` argument. See the
 [response contract](MCP_SERVERS.md#dependency-graph-coverage).
 
@@ -157,7 +169,7 @@ A traversal can also stop at its independent node or edge budget. Treat
 `partial`/`partial_reason` as incomplete graph evidence even on the final page;
 paging cannot recover nodes the walk never reached. Supporting responses include
 `total_is_exact: false` for a cutoff and true for a finished walk, independently of
-pagination. This field is unreleased after `2.0.0.beta3`; on older servers inspect
+pagination. This field is included in Woods `2.0.0`; on older servers inspect
 `partial` directly. `nodes_total` remains the root-inclusive admitted prefix count,
 not the full reachable total when partial. Even an exact count covers only the
 requested root, depth, filters and published graph generation. Check the connected schema
@@ -171,7 +183,7 @@ Follow `parent`/`edge_id` references; `context: true` ancestors are outside the
 current result page. Unknown labels and ambiguous candidate types stay unknown;
 `typed_path_complete: false` does not establish a uniquely typed path. True means
 only unambiguous witness types, not complete source coverage. Supporting text
-responses label this `witness types unambiguous` (unreleased after `2.0.0.beta3`). See the
+responses label this `witness types unambiguous` (included in Woods `2.0.0`). See the
 [explanation contract](MCP_SERVERS.md#traversal-explanations).
 
 Use recorded relationship labels as evidence. Do not infer execution or call
@@ -181,6 +193,13 @@ order from a dependency edge alone.
 
 `codebase_retrieve` answers natural-language questions with token-budgeted context. Use it when `woods_status` reports explicit lexical mode over a current published index, or a configured embedding provider and current vector data in semantic mode. Lexical mode explains matching terms/fields and does not infer synonyms absent from the text; a no-match response is not proof of missing behavior.
 
+Top-level `ready` describes the structural index. Bootstrap `hydrated` does not
+prove that semantic stores contain data. When supported, inspect
+`retriever.corpus`; missing or unknown counts require checking embedding
+artifacts. Known-empty stores need embedding or an explicit switch to lexical
+mode. Positive record counts do not prove complete application coverage. See
+[semantic corpus diagnostics](RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
+
 Important parameters:
 
 - `query`: the conceptual question;

data/docs/AGENT_SETUP.md

@@ -51,7 +51,7 @@ Do not infer permission to configure Console MCP from a request to “set up Woo
 Create or switch to the branch requested by the repository owner. Select the
 published version using the [installation guide](GETTING_STARTED.md#1-install-the-gem).
 Before stable 2.x is published, use the exact published prerelease constraint
-from the README release table; `~> 2.0` will not select a beta or release candidate.
+from RubyGems; `~> 2.0` will not select a beta or release candidate.
 Use the selected version's tag documentation and verify its capabilities before
 configuring features described on `main`.
 
@@ -190,7 +190,7 @@ receipt for future update/removal. Unrelated servers, hooks, settings,
 instruction text, permissions, and line-ending conventions are retained;
 changing JSON may reformat its whitespace.
 
-Unreleased after `2.0.0.beta3`: apply and recovery coordinate on the actual
+Included in Woods `2.0.0`: apply and recovery coordinate on the actual
 managed file paths, including user configuration and shared instruction files.
 Two application roots sharing those files cannot apply overlapping plans at the
 same time. A competing operation reports a conflict; after it finishes, create a
@@ -221,18 +221,21 @@ If `codebase_retrieve` reports that semantic search is disabled, that is expecte
 
 ## 8. Offer automatic index maintenance
 
-Ask whether the owner wants Woods added to the development process manager. If authorized, use the repository's existing Procfile or equivalent convention:
-
-```text
-web:   bin/rails server
-woods: bundle exec rake woods:watch
-```
+Within the owner's setup authorization, select one development startup owner.
+Follow [managed startup](WATCH_DAEMON.md#managed-development-startup): Puma for
+simple Rails startup, a verified existing Foreman command/Procfile, or the existing
+external Docker/Grove supervisor. The launcher/generator are **included in Woods
+`2.0.0`**; check installed `woods-watch --help` and generator help first.
+Preserve `bin/dev`; a file that only starts Rails does not consume a Procfile.
+For older gems use their raw task with a restart-capable external supervisor,
+not a bare Foreman entry.
 
 The watcher catches up missed changes, maintains the structural index as files change, and publishes generations the Index MCP server detects automatically. Ordinary edits then need no manual re-extraction or MCP restart. It should run in development, not production.
 
 Report these boundaries in the handoff:
 
-- boot-captured changes make the watcher exit 75 and require supervisor restart;
+- raw tasks exit 75 for boot-captured changes; managed launchers absorb that restart;
+- managed mode rejects idle TTL and parks ownership conflicts without taking over;
 - container bind mounts may require `WOODS_WATCH_POLL=1`;
 - semantic vectors still require `woods:embed_incremental`;
 - without a resident watcher, the fallback is `woods:incremental` after changes.
@@ -275,7 +278,11 @@ Verified capabilities:
 - search/lookup/dependents checked: yes/no
 - retrieval: disabled/lexical/semantic (provider when semantic)
 - Console MCP: disabled/enabled (authorization)
-- automatic structural updates: disabled/enabled (process manager)
+- automatic structural updates: disabled/enabled (owner and actual startup command)
+- served root/index and completed startup catch-up:
+- edit and planned restart observed through existing MCP connection:
+- worktree/Grove switching verified (if applicable):
+- post-edit hooks / session freshness checks / context hints: separate enablement
 
 Follow-up or unresolved risk:
 ```

data/docs/AUTOMATIC_MAINTENANCE.md

@@ -0,0 +1,222 @@
+# Woods with minimal manual maintenance
+
+**Recommended development setup:** create a baseline index, run one supervised
+watcher per active application/worktree index, and let your MCP client launch the
+Index Server. The watcher publishes changes; an already connected Index Server
+reads the new generation on its next call. Ordinary edits then need no manual
+extraction or MCP restart.
+
+This page maps that workflow to its canonical documentation. The raw watcher and
+hooks are available in Woods `2.0.0.beta4`; the managed launcher, installation
+generator, and Puma adapter are **included in Woods `2.0.0`**. Check the
+installed gem/revision and plugin separately. Installing the gem or registering
+an MCP connection does **not** enable automatic index maintenance.
+
+## 1. Where each part is documented
+
+| What you need | Documentation section | What it defines |
+|---|---|---|
+| First extraction and validation | [Getting started: extract](GETTING_STARTED.md#3-extract-the-application) and [validate](GETTING_STARTED.md#4-validate-and-inspect-the-index) | Establish a usable baseline before connecting tools. |
+| The simplest automatic workflow | [Getting started: keep the index current](GETTING_STARTED.md#keep-the-index-current) | Watcher beside Rails, process-manager example, automatic reader refresh. |
+| Agent-operated installation | [Agent setup: automatic maintenance](AGENT_SETUP.md#8-offer-automatic-index-maintenance) | Add a watcher using the application's existing development process convention. |
+| Starting and supervising the watcher | [Managed development startup](WATCH_DAEMON.md#managed-development-startup), [raw task](WATCH_DAEMON.md#running-it), and [restart triggers](WATCH_DAEMON.md#restart-triggers) | Native/Puma installation, external supervision, and restart after exit 75. |
+| Updating or removing automatic startup | [Owned installation](WATCH_DAEMON.md#ownership-updates-and-removal) | Portable receipt, preserved application files, explicit updates/removal, and worktree-safe ownership. |
+| Catching changes made while stopped | [Watch daemon: startup reconciliation](WATCH_DAEMON.md#startup-is-not-a-clean-slate) | Catch-up before normal watching, including missed changes and deletions. |
+| Running inside Docker | [Docker: extraction](DOCKER_SETUP.md#extraction) and [index persistence](DOCKER_SETUP.md#index-persistence) | Container-side execution, polling, shared paths, and persistent output. |
+| Connecting the reader | [MCP: stdio client](MCP_SERVERS.md#configure-a-stdio-client) and [Docker process/path rule](MCP_SERVERS.md#docker-process-and-path-rule) | Client-owned process startup and paths visible to that process. |
+| Seeing new generations without reconnecting | [Watch daemon: freshness contract](WATCH_DAEMON.md#the-freshness-contract) | Publication and automatic reader refresh. |
+| Optional refresh after agent edits | [Edit client adapters](CLIENT_HOOKS.md) and [hook operation](WATCH_DAEMON.md#hooks-for-agent-sessions) | Registration, supported edit events, durable queue, retries, and Docker execution. |
+| Session checks and optional context hints | [Source freshness: containers and hooks](SOURCE_FRESHNESS.md#containers-and-hooks) and [bounded context hints](WATCH_DAEMON.md#optional-bounded-context-hints) | Freshness warnings and separately enabled context delivery. |
+| Defaults and environment variables | [Watch settings](CONFIGURATION_REFERENCE.md#watch-daemon-woodswatch) and [plugin hook settings](CONFIGURATION_REFERENCE.md#opt-in-plugin-refresh-hooks) | Authoritative variable names, defaults, and enablement rules. |
+| Worktrees and separate containers | [Multiple worktrees](WATCH_DAEMON.md#multiple-worktrees), [cross-host liveness](WATCH_DAEMON.md#cross-host-liveness), and [MCP worktree setup](MCP_WORKTREE_SETUP.md) | Separate index ownership, reader registration, and heartbeat trust. |
+| Grove-managed worktree switching | [Grove integration below](#grove-coordinate-the-watcher-with-worktree-switches) and [Grove's external Docker integration](https://github.com/lost-in-the/grove/blob/cf833e65c6d2525b0fafa91ebeea9be6455decdb/plugins/docker/README.md#external-mode) | Include the watcher in the services Grove starts against the selected worktree. |
+| Diagnosing stale or uncertain answers | [Source freshness: read the result](SOURCE_FRESHNESS.md#read-the-result) and [troubleshooting](TROUBLESHOOTING.md#source-freshness-is-unknown-or-drifted) | Distinguish content drift, incomplete evidence, age, and daemon health. |
+
+## 2. What starts what
+
+| Component | Started by | Responsibility |
+|---|---|---|
+| Rails application | Your development process manager or Compose | Runs the application; a configured development Puma adapter also starts Woods' separate launcher. |
+| Managed `woods-watch` | Selected Foreman command or opt-in Puma adapter | Owns a fresh extraction child and handles planned restarts without stopping Rails. |
+| `woods:watch` | A separately configured supervisor/service | Boots Rails, catches up missed changes, watches files, and publishes structural generations. |
+| Index MCP over stdio | Your editor or agent's MCP client | Reads the published index. It does not boot Rails or launch a watcher. |
+| Post-edit refresh hook | A supported client edit event, after opt-in | Requests extraction for relevant edits; an active watcher can cause it to defer. |
+| Session-start hook | A supported client session event, after opt-in | Checks source freshness and warns. It does not extract or revive a stopped watcher. |
+| Optional context hook | Supported client events, after separate opt-in | Supplies bounded orientation or impact hints. It does not enable refresh. |
+
+```mermaid
+flowchart LR
+  Supervisor[Development supervisor] --> Watcher[Woods watcher]
+  Files[Application file changes] --> Watcher
+  Watcher --> Index[Published generation]
+  Client[MCP client session] --> Reader[Index MCP process]
+  Index -->|Read on subsequent calls| Reader
+```
+
+Console MCP is a separate, optional live-data tool. Its HTTP transport can be
+mounted in Rails when enabled, but that does not maintain the structural index.
+See [the server distinction](MCP_SERVERS.md#choose-a-server).
+
+## 3. Recommended setup for daily work
+
+1. **Create and validate the initial index.** Follow the first two links in the
+   table. If verified fresh-boot provenance matters, use the
+   [fresh-process extraction launcher](SOURCE_FRESHNESS.md#establish-a-fresh-baseline).
+2. **Add a resident watcher to development startup.** Follow the canonical
+   [mode selection and preview](WATCH_DAEMON.md#managed-development-startup): Puma
+   for simple Rails startup, verified Foreman for an existing Procfile workflow,
+   or the existing external supervisor for Docker/Grove. Preserve `bin/dev` and
+   record the actual startup command. Keep catch-up enabled and idle TTL unset.
+3. **Make writer and reader share the intended index.** In Docker, preserve the
+   application's required source, bundle, configuration, and git mounts. Persist
+   the index across container replacement. Use polling when bind-mount events
+   are unreliable. Follow the linked Docker guide instead of copying a generic
+   service that might replace required inherited settings.
+4. **Register the Index MCP client once for the correct worktree.** The client
+   starts the reader for its session. A container-based launcher requires its
+   target container to be running; registering MCP does not start Docker.
+5. **Prove one automatic update.** Make a reversible edit, observe successful
+   publication, and query the changed unit through the existing MCP connection.
+   Repeat once across watcher restart and worktree switch if those are routine.
+
+For sustained work, the resident watcher detects changes to supported application
+files regardless of which editor or agent made them. Do not enable post-edit
+refresh hooks merely to make the watcher faster: hooks can defer to it and retain
+queued events.
+
+The watcher maintains the structural index. Semantic vectors need their own
+`woods:embed_incremental` workflow. For provider-free ranked retrieval, consider
+[explicit lexical mode](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval), which
+uses published extraction units without a separate embedding pipeline.
+
+### Docker: verify the resolved service
+
+Inspect the result of `docker compose config` using the same files, environment,
+and active worktree as normal startup. Keep resolved secrets out of shared logs.
+
+- **Preserve inherited settings.** Within a YAML anchor merge, an explicit
+  `volumes:` or `environment:` key replaces that inherited value. Across Compose
+  files, volume entries merge by container target. A separate override can add
+  the index mount while retaining the base service's application and bundle
+  mounts. Verify the resolved result, including any inherited ports or web-only
+  healthcheck. See Docker's [YAML fragments](https://docs.docker.com/reference/compose-file/fragments/)
+  and [Compose-file merge rules](https://docs.docker.com/reference/compose-file/merge/).
+- **Choose restart behavior deliberately.** `on-failure` restarts exit 75, but
+  does not restart the container after the Docker daemon restarts. For recovery
+  after Docker/OrbStack restarts while respecting an intentional stop, use
+  `unless-stopped`. See [Docker restart policies](https://docs.docker.com/engine/containers/start-containers-automatically/).
+- **Check database readiness.** The short `depends_on` form orders startup; it
+  does not wait for the database to accept connections. Use the application's
+  existing readiness convention, such as `service_healthy` with a database
+  healthcheck, and reference the Compose service key. See
+  [Compose startup order](https://docs.docker.com/compose/how-tos/startup-order/).
+- **Verify catch-up and worktree switching.** A running container does not prove
+  its first extraction finished. Confirm successful publication and the intended
+  source/index paths before calling the setup current. Recreate the watcher with
+  the other application services when the active worktree changes.
+
+Use the application's actual Rails task entrypoint. An application whose root
+`Rakefile` wraps Docker may require `bundle exec rails woods:watch` instead of
+`bundle exec rake woods:watch`; verify the command inside the application container.
+
+### Grove: coordinate the watcher with worktree switches
+
+When using [Grove](https://github.com/lost-in-the/grove) with an external Compose
+stack, Grove supplies the worktree-switch lifecycle. Its Docker integration
+persists the selected worktree in the configured environment file and runs
+`docker compose up -d` for the configured services. Compose recreates services
+whose resolved configuration changed, including changed bind-mount paths.
+
+- Add the watcher service to the existing
+  `[plugins.docker.external].services` list in `.grove/config.toml`, preserving
+  the other entries. The service must also exist in the Compose configuration.
+- Keep the application's source mount and index mount tied to the same
+  worktree variable configured by `env_var`. Confirm the MCP launcher reads
+  that worktree's index too.
+- Check `plugins.docker.enabled`, `auto_start`, `auto_stop`, and
+  `switch.container_switch`. With automatic lifecycle enabled, a normal
+  `grove to <worktree>` switch stops the configured old services and brings them
+  up against the selected tree. Updating the environment file alone does not
+  reconfigure an already running container.
+- If using isolated agent stacks, check their separate
+  `[plugins.docker.external.agent].services` list and Compose template as well;
+  the shared stack's watcher configuration is not sufficient for those slots.
+
+The ownership chain is **Grove selects the worktree and starts its services →
+Docker supervises the watcher → Woods catches up and publishes file changes**.
+The MCP client starts the reader, which reloads published generations. This setup
+needs no additional Woods-starting Grove hook when its Docker integration already
+manages the watcher. Verify a switch by observing an edit in the new tree while
+the previous tree's index stays unchanged.
+
+See Grove's [Docker lifecycle documentation](https://github.com/lost-in-the/grove/blob/cf833e65c6d2525b0fafa91ebeea9be6455decdb/plugins/docker/README.md#hook-integration)
+and [external-stack configuration examples](https://github.com/lost-in-the/grove/blob/cf833e65c6d2525b0fafa91ebeea9be6455decdb/docs/CONFIGURATION_REFERENCE.md#rails-project-with-external-docker).
+These links pin the Grove revision checked for this guide; compare with
+`grove version` when diagnosing a different installation.
+
+### Cross-container status is different from an extraction lock
+
+When a watcher and a status-checking process share an index but have different
+hostnames, `WOODS_WATCH_TRUST_FOREIGN_HOST=1` lets that process use the watcher's
+fresh heartbeat. Set it inside the relevant MCP/task container or pass it through
+the launcher; setting it only in the host shell or watcher does not configure
+other containers. This is bounded heartbeat trust, not proof the remote process
+still exists: a stopped daemon can remain believable for up to 15 minutes.
+
+| Operation | Effect of the running watcher |
+|---|---|
+| Ordinary Index MCP reads | Read published generations without acquiring the extraction writer lock. Foreign-host trust is not required to read or reload an index. |
+| `woods_status` / `woods:watch_status` | Foreign-host trust affects daemon liveness reporting. A live but degraded daemon is not evidence that updates are succeeding. |
+| `woods:incremental` | Can stand down when a trusted running daemon covers the index; a degraded daemon does not provide that coverage. |
+| Post-edit hook refresh | Can defer with exit 75 while retaining its queued work. |
+| Manual `woods:extract` or named refresh | Acquires the shared writer lock. An idle watcher does not hold it; an active extraction can make the manual task wait. |
+
+The default writer-lock wait is up to 600 seconds, configurable with
+`WOODS_LOCK_WAIT`; failure to acquire it exits nonzero. It is not a mandatory
+delay whenever a watcher exists. Heartbeat trust does not bypass the lock.
+See [writer coordination](WATCH_DAEMON.md#within-one-worktree-writers-serialize)
+and [cross-host liveness](WATCH_DAEMON.md#cross-host-liveness).
+
+## 4. When hooks are useful instead
+
+Post-edit hooks suit occasional agent edits when keeping another Rails process
+resident is undesirable. They cover the registered client events, not arbitrary
+shell commands, git operations, or edits from another application. They are not
+a substitute for a watcher when all filesystem changes need automatic coverage.
+
+Follow [client registration](CLIENT_HOOKS.md), then verify:
+
+- `WOODS_HOOKS_ENABLED=1` reaches the process launching the client;
+  `WOODS_HOOKS_DISABLED=1` overrides it.
+- The installed gem supports the hook task and a baseline index already exists.
+- `WOODS_HOOK_RAKE` runs in the application's real environment; Docker-only
+  bundles need a container command prefix or wrapper.
+- The hook can see the intended index and map edits to the correct application.
+- A supported edit produces a successful publication, not just a hook callback.
+  Inspect `hook.log` and `hook-pending/` when work is deferred or fails.
+
+`WOODS_HOOK_CONTEXT_ENABLED` is a separate opt-in. Neither context hints nor a
+quiet session-start check establish that anything is refreshing the index.
+Use the settings and recovery links above for the full contract.
+
+## 5. A low-interaction setup is complete when
+
+- Development startup starts the intended watcher through its supervisor.
+- Missed changes are reconciled when the watcher starts again.
+- Edits, creates, and deletes appear through the existing MCP connection.
+- A worktree switch changes both the watched source and the served index.
+- A failed edit retains the last good generation and reports the degraded state;
+  correction allows recovery without discarding the index.
+- The handoff separately records watcher supervision, post-edit hooks, session
+  checks, context hints, MCP registration, and any embedding refresh workflow.
+
+Check `woods_status` before relying on indexed facts. Daemon liveness and an old
+publication timestamp do not by themselves establish source freshness. Even a
+working watcher can report `unknown` source evidence, including an unverified
+boot boundary; read the reason before deciding what to refresh. See
+[source-freshness scope](SOURCE_FRESHNESS.md#scope-and-partial-extraction).
+
+Automatic revival after a raw task's idle shutdown requires a separately
+configured supervisor or startup hook; the shipped SessionStart hook does not
+do it. Managed mode rejects idle TTL. Confirm the selected startup integration
+and a successful publication before claiming automatic maintenance is active.

data/docs/BACKEND_MATRIX.md

@@ -35,14 +35,20 @@ The shape determines the capability matrix:
 
 ### Database compatibility
 
-The vector store you can use depends on the primary database your Rails app uses. MySQL stacks **must** pair with an external vector backend; PostgreSQL stacks have the option of running pgvector inside the same database.
+Vector storage is independent of the application's primary database. Structural
+MCP tools and explicit lexical retrieval need no vector backend. For semantic
+retrieval, any supported application database can use `:in_memory`, Qdrant, or
+pgvector through a live PostgreSQL connection.
 
-| Primary database | Supported vector stores | Required? |
+| Primary database | Supported vector stores | PostgreSQL connection for pgvector |
 |---|---|---|
-| **MySQL / Percona / MariaDB / Aurora MySQL** | `:qdrant` (external); `:in_memory` (local dev only) | Yes. MySQL has no native vector extension |
-| **PostgreSQL / Aurora PostgreSQL** | `:pgvector` (in-database), `:qdrant`; `:in_memory` (local dev only) | No, `:pgvector` runs inside the same database |
+| **MySQL / Percona / MariaDB / Aurora MySQL** | `:pgvector`, `:qdrant`, `:in_memory` | Separate PostgreSQL database |
+| **PostgreSQL / Aurora PostgreSQL** | `:pgvector`, `:qdrant`, `:in_memory` | Application connection or a separate PostgreSQL database |
 
-**Why MySQL needs an external backend.** MySQL ships no equivalent of the `pgvector` extension. Approximate-nearest-neighbour search over arbitrary float vectors is not part of InnoDB / MyISAM and cannot be added via plugin. Woods does not emulate vector search in MySQL, the gem only ships adapters that delegate to a real vector engine. The shipped pairing for MySQL apps is `:qdrant` for vectors with Woods' own `:sqlite` metadata store; Woods never stores metadata in your application database.
+Woods has no MySQL vector adapter. A MySQL application can use the `:local`
+preset, Qdrant, or a separate PostgreSQL connection for pgvector. Woods' metadata
+store remains a separate choice: SQLite or in-memory. The pgvector row's JSON
+metadata does not replace that store.
 
 ### pgvector (PostgreSQL extension)
 
@@ -52,7 +58,7 @@ The vector store you can use depends on the primary database your Rails app uses
 
 **Strengths:**
 - Zero additional infrastructure if you're on PostgreSQL
-- Transactional consistency with metadata (same database)
+- Stores each vector and its per-vector JSON metadata in one PostgreSQL row
 - Familiar SQL interface, works with ActiveRecord
 - Supports HNSW indexing
 - Backed by strong open-source community
@@ -108,7 +114,7 @@ smaller provider output width or another backend. See the
 
 **When to use:** PostgreSQL is your primary database, you value simplicity, and scale is under ~50K vectors.
 
-**When to avoid:** MySQL is your primary database (can't use pgvector), you need sub-millisecond search, or you're indexing multiple large codebases.
+**When to avoid:** You do not want to operate PostgreSQL, you need sub-millisecond search, or you're indexing multiple large codebases.
 
 ---
 

data/docs/CLIENT_HOOKS.md

@@ -2,7 +2,7 @@
 
 Edit hooks are optional. MCP reads and `woods:watch` work independently of them.
 Check the installed gem exposes `woods:hook_refresh` before enabling these
-unreleased adapters; updating the plugin does not update the application gem.
+adapters included in Woods `2.0.0`; updating the plugin does not update the application gem.
 Start the client from the Rails application root, with an existing index.
 
 ## Supported client contracts