woods 2.0.0.beta3 → 2.0.0

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,
@@ -98,6 +103,23 @@ including inlined code and callback analysis. Multiple runtime mixins sharing a
 file retain separate identities and refresh all their includers. Run a full extraction after upgrading
 to populate these previously missing source mappings.
 
+## Handled source errors and retry
+
+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
+units. The published generation and source provenance remain unchanged,
+including when other files in the batch extracted successfully.
+
+Fix the source error named in the extraction log, then retry the **complete
+batch**, or the same named refresh. The watch daemon reports degraded and keeps
+the failed batch pending for retry. An error on one file does not mark a later
+successful file as failed, but the batch still cannot publish until all handled
+errors are resolved. This does not change full extraction's existing tolerance
+for handled consumer errors; its source-freshness report marks those scopes
+unverified.
+
 ## What a run does, in order
 
 `Extractor#extract_changed` is order-sensitive; each step exists because of the
@@ -109,8 +131,8 @@ step before it.
 2. **Reconcile changed paths.** Every changed path that still exists is handed
    to the file-based extractors that claim it (`PathDispatcher`), and units the
    path no longer produces are dropped. This is what indexes a file the index
-   has never seen, and what lets a task removed from a multi-task `.rake` file
-   actually go away.
+   has never seen, and what removes definitions deleted from a surviving
+   source file. Multi-file Rake tasks use wholesale reconciliation below.
 3. **Re-extract the rest of the blast radius**: units whose own file did not
    change but which depend on something that did.
 4. **Reconcile class-based types** against each extractor's
@@ -208,7 +230,6 @@ automatically.
 | `config/locales/**/*.yml` | i18n |
 | `config/initializers`, `config/environments` | configurations |
 | `db/migrate/*.rb` (top level only) | migrations |
-| `lib/tasks/**/*.rake` | rake_tasks |
 | `lib/**/*.rb` (outside `tasks/`, `generators/`) | libs |
 | `spec/**/*_spec.rb`, `test/**/*_test.rb` | test_mappings |
 
@@ -219,12 +240,13 @@ serializer and decorator extractors, and all matching rules run.
 ### Wholesale re-runs
 
 `PathDispatcher.whole_app_rules` → `Extractor::WHOLE_APP_EXTRACTORS`. These
-extractors have no per-file entry point: they introspect the runtime or scan a
-whole directory in one pass. In an already-booted process re-running them is
+extractors need a complete runtime or directory view, even when a low-level
+per-file reader exists. In an already-booted process re-running them is
 cheap, which is what makes wholesale replacement the right shape.
 
 | Trigger | Re-runs |
 |---|---|
+| `lib/tasks/**/*.rake` | rake_tasks (all definitions of every task) |
 | `config/routes.rb`, `config/routes/**` | routes, engines, **and** controllers, mailers, components, view components, view templates |
 | `Gemfile.lock` | engines, middleware, rails_source (gated by `include_framework_sources`) |
 | `config/application.rb`, `config/initializers/**`, `config/environments/**` | middleware |
@@ -235,7 +257,14 @@ cheap, which is what makes wholesale replacement the right shape.
 | `db/views/**/*.sql` | database_views |
 | any `package.yml`, `packwerk.yml` | packages |
 
-Three of these deserve a note:
+Four of these deserve a note:
+
+- **Rake tasks merge definitions across files.** Any changed or deleted `.rake`
+  file reruns the task extractor over all task files. Removing the primary
+  definition preserves surviving definitions; removing a secondary definition
+  drops its source and dependencies from the shared unit. After upgrading from
+  the old per-file rules, run a full extraction to establish a source-freshness
+  baseline with the new rule fingerprint.
 
 - **Routes cascade.** `ROUTE_CONSUMER_EXTRACTORS` embed the route table, controllers write each action's routes into unit metadata and into the action
   chunks, and everything using `RouteHelperResolver` resolves navigation edges

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.
@@ -180,7 +197,7 @@ failure boundary; they do not prove uniqueness or become `ambiguous_identity` er
 Use `depth: 0` for the request timeline, or inspect candidates with typed `lookup`
 calls. Re-extraction does not remove a legitimate cross-type collision. Successful
 traces retain their existing identifiers and response shape; target identity has
-not been migrated globally. These corrections are unreleased after `2.0.0.beta2`.
+not been migrated globally. These corrections are available in `2.0.0.beta3`.
 
 The server also exposes MCP resources and resource templates for indexed units. Tool descriptions returned by MCP are the parameter-level source of truth; [Agent guide](AGENT_GUIDE.md) explains selection strategy.
 
@@ -192,12 +209,29 @@ error and continues serving the previous aligned generation; it never swaps in a
 partial or empty replacement. Grant write access for live reloads, or restart the MCP
 process after publishing a new embedded index.
 
+### Graph-analysis pages
+
+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
+omitted; pass a limit explicitly when supporting both versions.
+
+JSON responses retain `<section>_total`, `<section>_offset` (when positive), and
+`<section>_truncated: true` whenever a page omits rows before or after it. Markdown,
+plain, and Claude responses show the same total and offset on last and empty
+pages. For example, offset 20 with limit 5 over 25 published orphans shows
+`5 of 25 from offset 20`; offset 100 shows `0 of 25 from offset 100`. An empty
+page does not mean the section has no findings. These totals describe the
+published report arrays, which can themselves be bounded during extraction;
+they do not establish complete source-reference coverage.
+
 ### Search completeness
 
 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` |
 |---|---|---|---|
@@ -229,6 +263,31 @@ Detected missing, unreadable, or corrupt artifacts remain `isError: true` with
 `has_more`, `total_matches`, and `matched_lower_bound`; no successful empty
 result is substituted. Inspect `woods_status` and run `woods:validate`.
 
+### Dependency graph coverage
+
+`dependencies` and `dependents` return relationships recorded in the published
+index, not an exhaustive call graph or source-reference index. Extraction combines
+runtime reflection with selective source scanning; arbitrary method-body constant
+references (including references to generic PORO and library classes) may have no
+edge. No dependents, a test-only dependent, or a completed traversal does not prove
+there are no production callers. Verify important absence claims in source.
+
+Supporting servers expose the annotated, paginated traversal result in
+`structuredContent.data` for every renderer, including the default packaged
+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 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 included in Woods
+`2.0.0`; older servers need the same conservative interpretation.
+
 ### Dependency traversal budgets
 
 `dependencies` and `dependents` walk breadth-first in stored graph order. The
@@ -251,7 +310,16 @@ Exact-budget walks that finish all requested work are complete and have no
 `limit` (default 50) and `offset` only page that discovered result; they never
 change the walk budget or depth. On a partial traversal, `nodes_total`, when
 present for pagination, counts the discovered prefix, **not the full reachable
-graph**. Paging beyond that prefix stays partial. To explore more, narrow
+graph**. Every successful response includes `total_is_exact`: false for a
+budget cutoff, true when the requested walk finishes, even when its page is
+truncated or empty. It is independent of `limit`/`offset` and is present for
+unpaged answers too. Partial text answers say `Showing N of at least M (total
+unknown: node_budget)` (or `edge_budget`), including when no pagination is needed.
+`M` includes the root and counts the admitted prefix; it is a lower bound for the
+requested root, depth, type/relationship filters and published generation, not a
+count of all application callers. Exactness describes that same recorded-graph
+scope and never implies exhaustive source coverage. Paging beyond that prefix
+stays partial. To explore more, narrow
 `depth`/`types`/`via`, choose another root, or increase the traversal budget within
 its maximum. Keep the root, filters, budgets, and published generation unchanged
 for stable pages. No wall-clock deadline is used, so cutoffs are deterministic.
@@ -259,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:
 
@@ -289,6 +357,10 @@ A target name shared by several types has `type: null`,
 record target types, so the response cannot choose among candidates. A witness
 through an ambiguous or unresolved identity sets `typed_path_complete: false`;
 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 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

@@ -64,7 +64,7 @@ The Index Server defines **29 schemas**: the packaged executable registers **14*
 | Snapshot (4) | 4 | Extraction with `enable_snapshots = true` normally creates `woods.sqlite3`, which packaged servers discover. If extraction used the JSON fallback, set `WOODS_SNAPSHOTS=true` on the standalone server. Custom embedded servers pass `snapshot_store:`. Internal SQLite migrations are automatic. Tools: `list_snapshots`, `snapshot_diff`, `unit_history`, `snapshot_detail` |
 | `notion_sync` | 1 | `notion_api_token` + `notion_database_ids` both set |
 
-`codebase_retrieve` is always registered (no `retrieve` alias exists), but only returns results once an embedding provider is configured and `rake woods:embed` has run.
+`codebase_retrieve` is always registered (no `retrieve` alias exists). Default semantic mode requires an embedding provider and a completed `woods:embed` run. Explicit `WOODS_RETRIEVAL_MODE=lexical` ranks published extraction units without a provider or embeddings; set it in the MCP process environment and restart the server. See [embedding-free lexical retrieval](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval).
 
 If an agent reports a missing tool, compare its request with the connected server's registered list and [MCP server boundaries](MCP_SERVERS.md#conditional-index-capabilities). The normal packaged executable does not wire operator or feedback collaborators. **Console Server tools are not all unconditionally registered**: 31 tool schemas exist as an inventory, but only the 9 Tier 1 tools are executable by default, or 11 with `console_embedded_read_tools: true` (adds `console_sql`/`console_query`). Tier 2, Tier 3, and `console_eval` are schema-only in every supported mode; there is no bridge or confirmation flow that unlocks them. See [MCP servers](MCP_SERVERS.md#console-server) for the supported inventory.
 
@@ -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).
 
 ---
@@ -551,7 +551,7 @@ Static tools miss all of these because they only exist after Rails processes the
 }
 ```
 
-**What you'll get:** Units with no dependents, nothing in the codebase references them. Good candidates for removal or investigation.
+**What you'll get:** Units with no recorded dependents in the published graph, excluding types treated as natural entry points. These are candidates for investigation, not proof of dead code. Method-body references and dynamic callers may be missing; verify source references, framework entry points, and runtime usage before removing anything. See [dependency graph coverage](MCP_SERVERS.md#dependency-graph-coverage).
 
 ---
 
@@ -811,7 +811,7 @@ Keys without a recognised suffix fall through to ActiveRecord `where(hash)` equa
 
 ### "Find code related to subscription billing"
 
-**Tool:** `codebase_retrieve` (Index Server, requires embedding provider)
+**Tool:** `codebase_retrieve` (Index Server, semantic or explicit lexical mode)
 
 ```json
 {
@@ -820,7 +820,7 @@ Keys without a recognised suffix fall through to ActiveRecord `where(hash)` equa
 }
 ```
 
-**What you'll get:** A token-budgeted context string of the most semantically relevant units, ranked by hybrid search (semantic + keyword + PageRank). Requires an embedding provider (`embedding_provider: :openai` or `:ollama`) to be configured.
+**What you'll get:** Ranked context within an estimated text-token budget. Default semantic mode uses configured embeddings and hybrid ranking; explicit lexical mode uses field-aware BM25 over published units, without a provider or `woods:embed`. The same query works in either configured mode, though rankings differ. Confirm the active mode with `woods_status.retriever.mode`; see the [retrieval guide](RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval) for setup and budget limits.
 
 ---
 

data/docs/MCP_WORKTREE_SETUP.md

@@ -1,127 +1,99 @@
 # MCP Registration in Git Worktrees
 
-> **Claude Code specific.** This page covers Claude Code's MCP registration model (`/mcp`, `~/.claude/plugins/`); other MCP clients manage per-directory registration their own way.
+> **Claude Code specific.** Other MCP clients manage registration and subagent tool access differently. Use the client's current documentation alongside the Woods [MCP setup guide](MCP_SERVERS.md).
 
-When you work in a git worktree, a separate directory checked out from the same repository, your MCP tools may not be available to subagents running in that directory. This page explains why, how to fix it, and how to confirm the registration took effect.
+A git worktree is a separate checkout. For Woods, verify both which servers a session can access and which checkout's index those servers serve.
 
-## Why Worktree Subagents May Not See Woods Tools
+## Separate sessions and inherited subagents
 
-MCP server registration in Claude Code is controlled by `.mcp.json` files. Claude Code discovers these files by walking up the directory tree from the working directory. It stops at the first `.mcp.json` it finds (or at `~/.claude/settings.json` for global registrations).
+A **new Claude Code session launched in a worktree** can have different MCP registrations from a session in the main checkout:
 
-A git worktree has its own root directory separate from the main repository checkout. When a subagent starts inside the worktree root, it walks up from that path, not from the main repository root. Unless a `.mcp.json` exists inside the worktree directory tree or in an ancestor shared with both checkouts, the subagent sees no MCP servers.
+| Registration scope | Location | Availability |
+|---|---|---|
+| Local | Project entry in `~/.claude.json` | The project where the server was registered |
+| Project | `.mcp.json` in the project root | That project, subject to client approval/settings |
+| User | `mcpServers` in `~/.claude.json` | Across the user's projects |
 
-Example directory layout:
+A tracked `.mcp.json` may already be present in another worktree; a local, untracked file will not be copied by Git. User-level registration can make a server available across checkouts, but its configured paths still determine which index it serves.
 
-```
-~/work/my-app/            ← main checkout, has .mcp.json here
-~/work/my-app-feature/    ← worktree, no .mcp.json, so MCP tools are missing
-```
+An **inherited subagent** receives the parent conversation's MCP tools, subject to tool restrictions. Changing the subagent's working directory does not by itself launch another Woods server or switch the served index. Distinguish this from starting an independent client process in that directory.
+
+See Claude Code's [MCP installation scopes](https://code.claude.com/docs/en/mcp#mcp-installation-scopes) and [subagent tool access](https://code.claude.com/docs/en/sub-agents#available-tools). Do not diagnose registration by assuming the client searches ancestor directories for the nearest `.mcp.json`.
 
-A subagent spawned in `~/work/my-app-feature/` will not find the `.mcp.json` from `~/work/my-app/`.
+## Configure a server for the intended checkout
 
-## Fix: Add a `.mcp.json` to the Worktree Root
+First check `/mcp` in the session that needs Woods. If a suitable server is already connected, verify its index before adding a duplicate registration.
 
-Create a `.mcp.json` in the worktree's root directory with the same woods server entries you use in the main checkout:
+For a host with the application's Ruby bundle installed, a project-root `.mcp.json` can select the bundle and index explicitly:
 
 ```json
 {
   "mcpServers": {
     "woods": {
-      "command": "woods-mcp-start",
-      "args": ["./tmp/woods"]
-    },
-    "woods-console": {
-      "command": "docker",
-      "args": [
-        "compose", "exec", "-T", "app",
-        "bundle", "exec", "rake", "woods:console"
-      ],
-      "cwd": "/absolute/host/path/to/worktree"
+      "command": "bundle",
+      "args": ["exec", "woods-mcp-start", "/absolute/path/to/worktree/tmp/woods"],
+      "env": {
+        "BUNDLE_GEMFILE": "/absolute/path/to/worktree/Gemfile"
+      }
     }
   }
 }
 ```
 
-Adjust the paths and arguments to match your project's setup. In particular:
-
-- `./tmp/woods` is a relative path, it resolves against the worktree root, which is correct if extraction output is written into each worktree separately.
-- If you share a single extraction output directory between checkouts, use the absolute path to the shared output: `"/absolute/path/to/main-checkout/tmp/woods"`.
-- For Docker projects, the `docker compose exec` command works the same from any host path.
-
-## How Plugin Discovery Works
-
-Claude Code also discovers MCP servers registered in plugin manifests. A plugin at `~/.claude/plugins/<plugin-name>/admin-tools/.mcp.json` is loaded globally, its servers are available in any session regardless of working directory.
-
-If your team distributes the woods MCP registration through a shared plugin, the worktree problem does not apply. Check whether woods is already registered this way:
-
-```bash
-ls ~/.claude/plugins/
-# look for a directory containing admin-tools/.mcp.json
-cat ~/.claude/plugins/<plugin-name>/admin-tools/.mcp.json
-```
-
-If you find the woods servers registered there, subagents in any worktree will have access automatically, you do not need a per-worktree `.mcp.json`.
-
-## Verifying MCP Registration for a Subagent
-
-### Option 1: List tools from a claude session in the worktree
-
-Open a new Claude Code session with the worktree as the working directory and run:
-
-```
-/mcp
-```
-
-This lists all connected MCP servers and their tools. If `woods` and/or `woods-console` appear, registration is working.
+Replace both paths with the intended Rails worktree. Preserve other server entries. These absolute paths are machine-specific; do not commit them as shared team defaults. Follow the client's approval/reconnection steps, then verify the connection below.
 
-### Option 2: Check via the woods status tool
+For Docker, use the [container-first setup](DOCKER_SETUP.md#default-run-it-through-the-application-container). Select the intended Compose project and service, and verify that its mounted application directory is the worktree you mean to index. `docker compose exec` targets an existing container; running the command from a different checkout does not change that container's mounts. The index path must be visible inside that container.
 
-Ask Claude to call the status tool:
+Keep a separate output directory for each checkout when you need checkout-specific answers. If you intentionally point at another checkout's index, Woods serves that published content; registration alone does not make it describe the current worktree.
 
-```
-Use woods-console console_status to check what models are available.
-```
+## Plugin-provided servers
 
-If the tool runs successfully, MCP is registered and the console server is reachable.
+An enabled plugin can supply MCP server definitions, but installing a plugin does not establish that a Woods server is connected to the intended checkout. Availability depends on the plugin's configuration, enabled scope, and the client's tool restrictions. Check `/mcp` rather than assuming a fixed path under `~/.claude/plugins/` or global availability.
 
-### Option 3: Inspect the MCP config that Claude Code loaded
+The Woods setup/configuration skills help configure a server; their presence alone is not verification that the Index Server is running. See [agent setup](AGENT_SETUP.md).
 
-From the worktree directory, run:
+## Verify registration and the served index
 
-```bash
-cat .mcp.json
-```
+1. Open `/mcp` in the relevant Claude Code session and inspect the Woods connection and available tools.
+2. Call the Index Server's `woods_status`. Check `index_dir`, generation, and available freshness/provenance information against the intended extraction. A successful connection to the wrong index is still the wrong setup.
+3. Use `search` and typed `lookup` for a known unit from that checkout. When checking a subagent, verify that it can call the inherited tools and is using the same intended index.
 
-If the file exists and contains the woods entries, Claude Code will use it. If the file is missing, check parent directories up to your home directory for any `.mcp.json` that would be discovered.
+The optional Console Server is a separate connection to a booted Rails application. If deliberately enabled, check it with `console_status` and verify its application/container separately. Console access is not required to verify the Index Server.
 
 ## Extraction Provenance in Worktrees (`git_branch` / `git_sha`)
 
-`manifest.json` records the `git_branch` and `git_sha` the extraction ran against. In a linked worktree, `.git` is a **file** containing a `gitdir:` pointer to the real git directory, frequently an absolute host path, rather than a `.git` directory.
-
-Woods resolves provenance with worktree-aware git plumbing (`git -C <root> rev-parse`), so an ordinary worktree reports the correct branch and SHA. When a `.git` is present but the pointed-to git directory **cannot be resolved**: most commonly a worktree extracted inside a container where the host path isn't mounted. Woods records `git_branch: "unknown"` / `git_sha: "unknown"` rather than a stale, misleading value: a baked `GIT_BRANCH`/`GIT_SHA` build arg is **not** trusted here (it could be stale). The env vars are honored only when there is no `.git` at the root at all (a non-repo checkout, e.g. a Docker `COPY` that excludes `.git`) or git is unavailable.
+The published payload's `manifest.json` records the extraction's `git_branch` and `git_sha`. In a linked worktree, `.git` is a file containing a `gitdir:` pointer, often to an absolute host path. That private worktree directory also refers to the parent repository's shared Git data.
 
-To get correct provenance from a containerized worktree, mount the directory the `gitdir:` pointer references (the parent repository's `.git`) into the container so git can resolve it. Temporal snapshots skip an `"unknown"` SHA, so misleading provenance never keys a snapshot.
+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.
 
-## Troubleshooting
+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.
 
-**"Unknown tool" or "no MCP server named woods"**
+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.
 
-The woods MCP server is not registered for this session. Add a `.mcp.json` to the worktree root as shown above, then restart the session.
+## Troubleshooting
 
-**Console server starts but returns "unsupported: Not yet implemented in embedded mode" for console_sql / console_query**
+**Woods or an expected tool is absent**
 
-The console server is registered and reachable, but `embedded_read_tools` is disabled (the default). To enable console_sql and console_query in embedded mode, see the [Console MCP Setup guide](CONSOLE_MCP_SETUP.md), specifically the `embedded_read_tools: true` option for the Rack middleware.
+Check `/mcp` for connection errors, enabled registration scopes, and project approvals. For a subagent, also check its tool restrictions. Compare the requested tool with the [supported tool surface](MCP_SERVERS.md#conditional-index-capabilities); some tools require optional collaborators and are not registered by the packaged server. Do not add duplicate registrations before establishing which case applies.
 
-**Extraction output is empty or stale in the worktree**
+**The server connects but shows another checkout**
 
-Extraction writes to `tmp/woods/` relative to the Rails application root (inside the container). If the worktree's volume mount points to a different host path than the main checkout, run extraction again from the worktree:
+Inspect its configured bundle, index path, Compose project/service, and container mounts. Re-extract from the intended Rails checkout into its own output directory, then reconnect to that index and repeat `woods_status`. See [Docker setup](DOCKER_SETUP.md).
 
-```bash
-docker compose exec app bundle exec rake woods:extract
-```
+**Two registrations use the same server name**
 
-See [DOCKER_SETUP.md](DOCKER_SETUP.md) for the full Docker workflow.
+Check the client's [scope precedence](https://code.claude.com/docs/en/mcp#scope-hierarchy-and-precedence) and the effective connection shown by `/mcp`. Do not assume the two definitions merge or that a project file overrides every other scope.
 
-**Worktree `.mcp.json` conflicts with main checkout `.mcp.json`**
+**Console SQL/query tools are absent or unsupported**
 
-Each file is independent. Claude Code loads the one closest to the working directory. There is no inheritance or merging between them. Keep both files in sync manually, or move the shared configuration into a global plugin manifest.
+Console read-tool availability is configured separately from registration. Follow [Console MCP setup](CONSOLE_MCP_SETUP.md) for the supported 9-tool default and optional 11-tool mode.

data/docs/PUBLISHED_INDEX.md

@@ -109,6 +109,23 @@ The reader wraps `Woods::MCP::IndexReader` with `auto_refresh: false`; the unit
 
 `Woods::MCP::IndexReader#find_unit` keys its identifier map on identifier alone. If two type directories both list the same identifier (a model and a service both named `Foo`, for example), whichever type sorts last in `Woods::MCP::IndexReader::TYPE_DIRS` silently wins, and `unit(identifier)` returns that one. Pass `type:` to read a specific type's unit file directly and skip the collision entirely; `#table_database_map` always does this internally (`type: 'model'`), so a same-named non-model unit can never shadow a model's `table_name`/`database`.
 
+### Actual unit types and directory families
+
+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`.
+Check the loaded Git revision when testing a development checkout.
+
+The existing `graphql` and `rails_source` filters remain directory-family
+aliases: `graphql` selects all four GraphQL types; `rails_source` selects both
+Rails and gem sources. Returned records keep their actual type. Use
+`units(type: 'gem_source')` for gem sources only; to select Rails sources only,
+filter `units(type: 'rails_source')` on each entry's `"type" == "rails_source"`.
+Unknown types return no records, and an explicit GraphQL subtype never matches
+another subtype. Enumeration continues to return index-entry fields, not full
+unit source bodies.
+
 ### `available_generations`: published means published
 
 A generation is listed only when both hold:

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.