woods 2.0.0.beta3 → 2.0.0

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,24 +135,44 @@ 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).
 
 ## Traverse deliberately
 
-`dependencies` means “what this unit uses.” `dependents` means “what uses this unit.” Both default to bounded breadth-first traversal and accept type or relationship filters.
+`dependencies` shows recorded relationships from this unit; `dependents` shows
+recorded relationships to it. Both default to bounded breadth-first traversal and
+accept type or relationship filters. They are not exhaustive source-reference or
+call graphs: selective scanning can miss arbitrary method-body constant references,
+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 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.
 
 Both return at most 50 nodes by default and say so with a `Showing N of M (truncated)`
-line. Narrow with `depth`, `types` and `via` before paging with `limit` and
+line for completed walks. Budget-limited answers in supporting versions instead
+say `Showing N of at least M (total unknown: <budget reason>)`. Narrow with `depth`, `types` and `via` before paging with `limit` and
 `offset`: narrowing answers the question, paging only splits the same answer
 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 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).
+
 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. Check the connected schema
+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 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
 before using `max_nodes`/`max_edges`, and follow the
 [budget contract](MCP_SERVERS.md#dependency-traversal-budgets).
 
@@ -149,7 +181,9 @@ recorded source-to-target relationships and a shared shortest witness to each
 row. Report `direct` relationships separately from `transitive` inferred impact.
 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. See the
+`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` (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
@@ -159,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

@@ -40,7 +40,9 @@ If the worktree contains unrelated changes, preserve them. Do not overwrite an e
 
 Use structural-only setup when the user wants code navigation, runtime Rails structure, dependencies, flows, or blast-radius analysis. Fourteen tools register in the normal packaged launch without an embedding provider.
 
-Discuss semantic retrieval only if the user needs natural-language `codebase_retrieve`. The choice depends on whether they prefer local Ollama or hosted OpenAI and which vector store fits their environment. See [Backend matrix](BACKEND_MATRIX.md).
+If the user wants ranked discovery through `codebase_retrieve`, offer [explicit lexical mode](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval) over the published index without a provider or embeddings. Check that the installed version supports it, set `WOODS_RETRIEVAL_MODE=lexical` in the MCP process environment, restart that server, and verify `woods_status.retriever.mode`. Keep structural-only setup as the default unless this mode is requested.
+
+For semantic matching, discuss local Ollama or hosted OpenAI and the appropriate vector store separately; adding a provider still requires authorization. See [Backend matrix](BACKEND_MATRIX.md).
 
 Do not infer permission to configure Console MCP from a request to “set up Woods” or “set up MCP.” The Index Server reads generated code context; the Console Server can read live data.
 
@@ -49,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`.
 
@@ -130,7 +132,7 @@ Reconnect the client and call `woods_status`. Confirm a current generation and n
 
 ### Managed Claude Code configuration
 
-The development command `woods-agent-config` is unreleased after 2.0.0.beta2.
+`woods-agent-config` is available from Woods `2.0.0.beta3`.
 Check `bundle exec woods-agent-config --help` in the selected application bundle;
 use the manual client configuration below when it is absent. The supported
 client format is Claude Code (tested with 2.1.267).
@@ -188,8 +190,16 @@ receipt for future update/removal. Unrelated servers, hooks, settings,
 instruction text, permissions, and line-ending conventions are retained;
 changing JSON may reformat its whitespace.
 
+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
+fresh preview if the saved plan's snapshots changed. Both applications keep
+their own ownership receipts. Do not delete an active coordination lock.
+
 Writes use atomic replacement per file and a private recovery journal beside
-the receipt. The plan summary names the `.lock` and `.pending` runtime paths;
+the receipt. The plan summary names all adjacent `.woods.lock` files, the
+receipt `.lock`, and the `.pending` journal;
 a lock file may remain after completion. Multiple files are not one atomic
 transaction. An ordinary write failure restores original files when safe; an
 interruption or concurrent edit can retain the journal. Resolve reported
@@ -203,26 +213,29 @@ is changed; reduce the selected configuration before applying.
 
 Use a class known to exist in the application:
 
-1. Call `search` to obtain its exact identifier.
-2. Call `lookup` to confirm source and metadata are present.
+1. Call `search` to obtain its exact identifier and type.
+2. Call `lookup` with that identifier and type to confirm source and metadata are present.
 3. Call `dependents` with depth 1 or 2 to confirm graph edges are queryable.
 
-If `codebase_retrieve` reports that semantic search is disabled, that is expected for structural-only setup. Do not configure credentials merely to remove the message.
+If `codebase_retrieve` reports that semantic search is disabled, that is expected for structural-only setup. Do not configure credentials merely to remove the message. If lexical retrieval was requested, verify its mode with `woods_status` and make one `codebase_retrieve` call against the published index.
 
 ## 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.
@@ -263,9 +276,13 @@ Verified capabilities:
 - Index Server connected: yes/no
 - woods_status current: yes/no
 - search/lookup/dependents checked: yes/no
-- semantic retrieval: disabled/enabled (provider)
+- 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:
 ```
@@ -274,7 +291,7 @@ Never report a capability as enabled solely because its schema exists in source.
 
 ## Copyable prompt for an installation agent
 
-> Install Woods 2.x in this Rails repository using `docs/AGENT_SETUP.md`. Start with read-only preflight and preserve unrelated changes. Default to the structural Index Server; do not enable embeddings, Console MCP, HTTP transport, secrets, or purge overrides without asking me. Inspect generated files before migrating, run extraction and validation in the app's normal execution environment, configure a project-scoped MCP server in the same filesystem context as the application bundle and index, and verify `woods_status`, `search`, `lookup`, and `dependents`. Finish with the runbook's handoff report.
+> Install Woods 2.x in this Rails repository using https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md. Select a published version and follow that version's tag documentation and supported capabilities. Start with read-only preflight and preserve unrelated changes. Default to the structural Index Server; do not enable embeddings, Console MCP, HTTP transport, secrets, or purge overrides without asking me. Inspect generated files before migrating, run extraction and validation in the app's normal execution environment, configure a project-scoped MCP server in the same filesystem context as the application bundle and index, and verify `woods_status`, `search`, `lookup` with the discovered identifier and type, and `dependents`. Finish with the runbook's handoff report.
 
 ## Related guides
 

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
@@ -96,6 +102,11 @@ CREATE INDEX IF NOT EXISTS idx_woods_vectors_embedding_hnsw
   ON woods_vectors USING hnsw (embedding vector_cosine_ops);
 ```
 
+**Dimension limit:** Woods uses `vector_cosine_ops` HNSW, limited to 2,000 dimensions.
+The default 3,072-dimensional `text-embedding-3-large` output needs an explicit
+smaller provider output width or another backend. See the
+[pgvector configuration contract](CONFIGURATION_REFERENCE.md#pgvector-postgresql).
+
 **Performance notes:**
 - HNSW: ~5ms search at 10K vectors, ~20ms at 100K. Memory: ~1.5x vector size.
 - For codebase indexing (~1000-5000 units, potentially 5000-20000 chunks), HNSW is appropriate.
@@ -103,7 +114,7 @@ CREATE INDEX IF NOT EXISTS idx_woods_vectors_embedding_hnsw
 
 **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