woods 2.0.0.beta2 → 2.0.0.beta4

data/docs/MCP_WORKTREE_SETUP.md

@@ -1,127 +1,87 @@
 # 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.
+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.
 
-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:
+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.
 
-```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
+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.
 
-### Option 1: List tools from a claude session in the worktree
+## Plugin-provided servers
 
-Open a new Claude Code session with the worktree as the working directory and run:
+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.
 
-```
-/mcp
-```
+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).
 
-This lists all connected MCP servers and their tools. If `woods` and/or `woods-console` appear, registration is working.
+## Verify registration and the served index
 
-### Option 2: Check via the woods status tool
+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.
 
-Ask Claude to call the status tool:
-
-```
-Use woods-console console_status to check what models are available.
-```
-
-If the tool runs successfully, MCP is registered and the console server is reachable.
-
-### Option 3: Inspect the MCP config that Claude Code loaded
-
-From the worktree directory, run:
-
-```bash
-cat .mcp.json
-```
-
-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.
+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.
 
-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.
+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.
 
-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.
+For extraction in a container, make the canonical Git directory and the worktree's pointer resolvable there. Mounting only the private worktree Git directory can leave its shared object store unreachable. Follow the [Git provenance troubleshooting guide](TROUBLESHOOTING.md) for mount and `WOODS_GIT_DIR` guidance, and the [published index layout](INDEX_LAYOUT.md) when locating the manifest.
 
 ## Troubleshooting
 
-**"Unknown tool" or "no MCP server named woods"**
-
-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.
+**Woods or an expected tool is absent**
 
-**Console server starts but returns "unsupported: Not yet implemented in embedded mode" for console_sql / console_query**
+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.
 
-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.
+**The server connects but shows another checkout**
 
-**Extraction output is empty or stale in 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).
 
-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:
-
-```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/NOTION_INTEGRATION.md

@@ -34,6 +34,19 @@ Sync is incremental. A **sync manifest** (`<output_dir>/notion_sync_manifest.jso
 
 Manifest entries for models/columns that vanished from the current extraction are pruned, but **no Notion page is ever deleted** by the sync, there is no delete path. A renamed or removed model just leaves its old page in Notion untouched.
 
+Models and migration dates are loaded by `(identifier, type)`. A same-named
+PORO, library unit, or other extracted type cannot supply a model's table or
+column payload. Public identifiers, page titles, and manifest keys are unchanged.
+If a listed model or migration cannot be read with its exact identity, the
+affected sync refuses before mapping pages or pruning its manifest. Preserve
+the error, validate the index, and regenerate it before retrying; force sync
+does not bypass identity checks. Each public sync method, including standalone
+model or column sync, uses one validated generation snapshot through mapping
+and API calls. Native readers validate the published index before selecting
+model/migration payloads. Custom readers must provide complete published
+enumeration or complete per-bucket listings plus
+`find_unit(identifier, type:)` returning the requested identity.
+
 If the manifest is missing (first run, or a CI cache miss), the exporter falls back to the full lookup/create path for every page and rebuilds the manifest, correct, just more API calls than a steady-state run.
 
 ### Escape hatch

data/docs/OBSIDIAN_INTEGRATION.md

@@ -8,7 +8,7 @@ ways at once:
   Obsidian [Bases](https://help.obsidian.md/bases) table, and drill into a single unit's note with its
   dependencies and dependents as clickable wikilinks.
 - **By agents**: load the entire dependency topology from a single `_woods/` sidecar (one read,
-  no per-note fan-out), with a stable `id → note path` manifest for navigation.
+  no per-note fan-out), with a stable typed-unit → note-path manifest for navigation.
 
 Unlike the Notion and Unblocked exporters, this one writes **local files only**: there is no API
 token, no network call, and no rate limit. An Obsidian vault is just a folder.
@@ -95,6 +95,33 @@ Wikilinks are path-qualified with an alias (`[[models/Account|Account]]`): the t
 sanitized vault path so the link always resolves, and the alias shows the original identifier. The
 note's `# H1` carries the clean identifier so the sanitized filename never shows as the title.
 
+## Sidecar identity and schema versions
+
+A unit keeps its original `id` and `type` in note frontmatter. Different types may
+share an identifier: a database view and a factory called `reports` export to
+`database_views/reports.md` and `factories/reports.md`. Existing unambiguous note
+paths and display aliases stay unchanged.
+
+Check `schema_version` before consuming `_woods/manifest.json`:
+
+- **Version 1:** the graph has no cross-type identifier collisions. The existing
+  `notes[id]` and `paths[path]` maps are unchanged.
+- **Version 2:** `notes[id]` retains the graph's primary type (when exported), and
+  `variants` lists each additional exported unit as
+  `{ "identifier": "reports", "type": "factory", "path": "factories/reports.md" }`.
+  Combine primary entries and variants using **`(identifier, type)`** as identity.
+  `paths[path]` still gives the original identifier, so several paths may return
+  the same value. Resolve a path against both collections; `notes[id]` alone is
+  incomplete. A consumer supporting only version 1 must refuse version 2.
+
+The exporter reads each variant's own outgoing graph edges and derives incoming
+links from them. Persisted targets are bare identifiers: if a target names several
+types, the exporter omits that relationship from note links and counts it in a
+progress diagnostic. It does this even when one sibling is excluded or unreadable.
+Human association links use the same ambiguity rule. Bare PageRank and graph-analysis
+annotations are omitted for ambiguous identifiers, rather than assigned to either
+type. The verbatim graph sidecar retains all original records for inspection.
+
 ## The three visualizer surfaces
 
 | Surface | Best for | Notes |
@@ -114,7 +141,7 @@ credential):
 | `WOODS_OUTPUT` | `config.output_dir` (`tmp/woods`) | extraction directory to read from |
 | `WOODS_OBSIDIAN_VAULT` | `<output>/obsidian_vault` | where to write the vault |
 | `WOODS_OBSIDIAN_INCLUDE_SOURCE` | off | embed each unit's source code (credential-scrubbed) in its note |
-| `WOODS_OBSIDIAN_INCLUDE_FRAMEWORK` | off | include `rails_source` units (large; off by default) |
+| `WOODS_OBSIDIAN_INCLUDE_FRAMEWORK` | off | include `rails_source` and readable `gem_source` units (large; off by default) |
 | `WOODS_OBSIDIAN_FORCE_PURGE` | off | bypass the 30% mass-deletion guard during the stale-note sweep |
 
 ```bash
@@ -141,6 +168,28 @@ The exporter **fully regenerates** the vault on every run (no incremental manife
 cheap). Output is deterministic: re-running against an unchanged extraction produces byte-identical
 notes, so unchanged units never show up in a git diff.
 
+Before writing, Woods renders the output and checks **every destination**. An existing note or index
+must carry `woods_managed: true`; a `.woods-vault` sentinel alone never authorizes replacing your
+notes or settings. Conflicts stop the export before any writes or sweep, appear in `errors`, and make
+`woods:obsidian` exit nonzero. `WOODS_OBSIDIAN_FORCE_PURGE` does not bypass ownership checks.
+Child symlinks, directories in place of files, and special files are refused.
+
+Generated machine assets are tracked by SHA-256 in `_woods/ownership.json`: the three sidecar JSON
+files, three `.obsidian/` JSON settings files, and `Units.base`. Existing assets must match their
+recorded bytes or the newly generated bytes. This receipt does not change the public sidecar manifest
+schema. Modified settings are preserved by refusing the export; the sentinel is not an override.
+
+**Upgrading an older vault:** without a receipt, byte-identical generated assets can be adopted. Run
+once against the same extraction to establish ownership before updating the index. If the index has
+already changed, Woods may refuse the old sidecars because their ownership cannot be proved. Inspect
+and back up the named files before moving them aside, or export into a new directory. Do not remove
+personal content or manufacture a receipt to bypass a conflict.
+
+Preflight prevents known destination conflicts from causing partial exports. This is not a multi-file
+transaction or a lock against concurrent editors: a later I/O failure can leave some generated files
+updated. Such failures report errors, suppress the sweep, and return zero completed-export counts;
+inspect the vault before retrying. Avoid editing the destination while an export runs.
+
 Notes Woods manages carry `woods_managed: true` in their frontmatter. On each run, after all notes are
 written successfully, a **sweep** removes managed notes whose unit no longer exists, so deletions in
 your code propagate. Several guards make the sweep safe to point at a real vault:
@@ -150,21 +199,20 @@ your code propagate. Several guards make the sweep safe to point at a real vault
 - It refuses to delete more than 30% of managed notes at once (the signature of a partial extraction)
   unless `WOODS_OBSIDIAN_FORCE_PURGE=1` is set.
 - It resolves symlinks and confirms every deletion target is inside the vault root.
-- It is skipped entirely if any note failed to write that run (a stale note is harmless; a deleted
-  reviewed note is not).
+- It is skipped entirely if any candidate unit is unreadable or returns a mismatched identity,
+  or any note failed to write. `force_purge` does not bypass this incomplete-export guard.
 
-The same ownership check guards the `.obsidian/` config: Woods will **not** overwrite an existing,
-foreign `.obsidian/` folder, it leaves your Obsidian settings untouched and warns instead.
+In a foreign vault, Woods leaves `.obsidian/` configuration untouched and skips the sweep. Notes and
+sidecars are added only after the same per-file ownership preflight. In a Woods-owned vault, existing
+configuration assets still require a matching ownership receipt or byte-identical generated content.
 
 ## Limitations
 
 - **Bases needs Obsidian ≥ 1.9** (≥ 1.10 for card/list views). The `.base` file is harmless on older
   versions, it simply doesn't render.
-- **`gem_source` units are not exported.** They aren't reachable through the index reader; only
-  `rails_source` is covered by `include_framework`.
 - **Hand-edits diverge.** The vault is meant to be regenerated. Editing a note's properties in
   Obsidian rewrites its frontmatter, after which a re-export will overwrite your changes.
 - **Nested vaults ignore the shipped config.** Open the generated folder as its own vault for graph
   colors, Bases, and link-format settings to apply.
 
-See `docs/AGENT_GUIDE.md` for how an agent consumes the `_woods/` sidecar.
+For MCP-based exploration instead of local vault files, see [the agent guide](AGENT_GUIDE.md).

data/docs/PUBLISHED_INDEX.md

@@ -1,5 +1,8 @@
 # Reading a published index from Ruby
 
+For shell, Python, shipping snapshots, or direct JSON access, use the
+[published filesystem layout contract](INDEX_LAYOUT.md).
+
 `Woods::PublishedIndex` is the stable, read-only API for tools that are not MCP clients: RuboCop cops, CI gate scripts, and the `woods:check:*` tasks. It needs no Rails, opens one published generation, and never moves off it for the life of the reader.
 
 ```ruby
@@ -24,6 +27,58 @@ Woods::PublishedIndex.open(Rails.root.join('tmp/woods')) do |index|
 end
 ```
 
+## Validate a published generation
+
+```ruby
+require 'woods/resilience/index_validator'
+
+report = Woods::Resilience::IndexValidator.new(index_dir: 'tmp/woods').validate
+report.valid? # false when artifact or semantic graph errors were found
+report.errors
+report.warnings
+```
+
+`woods:validate` uses the same checker. Supporting development versions validate
+raw graph relationships as well as JSON, content hashes, and indexed files; see
+the [semantic invariants and limits](INDEX_LAYOUT.md#semantic-graph-validation).
+Errors retain typed identifiers and artifact paths. Writer-version and source-path
+warnings keep their existing advisory behavior.
+
+Each call resolves and pins one published generation for all checks. Concurrent
+publication can advance the pointer, but retention cannot remove the payload
+being validated. The next call sees the new generation. Locks release on success
+and errors; malformed pointers fail instead of falling back to stale root files.
+Legacy flat layouts remain supported but cannot provide immutable-generation
+isolation against in-place writes. Bare type-directory fixtures without a
+manifest retain structural-only validation.
+
+The reusable `Woods::Resilience::GraphInvariantValidator` accepts raw string-keyed
+`graph:` data and typed `index_entries:` and returns an array of errors without
+modifying either input. Callers supplying raw data must keep it within one pinned
+generation and verify the unit artifacts themselves, as `IndexValidator` does.
+Validation is a read-only diagnostic, not automatic repair or proof of runtime
+execution.
+
+## Manifest writer provenance
+
+The published `manifest.json` records `woods_version`, a string naming the Woods gem version
+that last published that manifest. Full extraction, changed incremental runs,
+targeted refreshes, and the static Woods self-map write it. A no-op leaves the
+published manifest and its version unchanged. Resolve the manifest through the
+generation pointer, as Woods readers do.
+
+Older manifests may omit the field or contain `null`; that means unknown.
+`woods_status.index.woods_version` reports this value from the served manifest,
+while `woods_status.server.version` identifies the running MCP reader. The reader
+never substitutes its own version for missing writer provenance.
+
+`woods:validate` warns when a present writer version is malformed or its major
+version differs from the installed validator. The warning is advisory and does
+not invalidate an otherwise structurally valid index. Re-run full extraction
+when investigating a major-version mismatch. Matching versions do not certify
+compatibility: an incremental publisher can retain units written by an older
+version. This field does not replace the [upgrade procedure](UPGRADING_TO_2.md).
+
 ## One generation, pinned for the reader's whole life
 
 Unlike `Woods::MCP::IndexReader`, a `PublishedIndex` never refreshes between calls. It resolves one generation at `.new`/`.open` time and every fact it returns, `units`, the table map, `generation_number`, `external_dependency_checksum`, comes from that one generation for as long as the reader is open. There is no `reload` and no auto-refresh: open a new reader to see a later publish.
@@ -54,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
+
+Unreleased after `2.0.0.beta3`: `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

@@ -36,10 +36,13 @@ and stdio or Streamable HTTP endpoints directly.
 - [MCP tool cookbook](MCP_TOOL_COOKBOOK.md): scenario-based calls with parameters and expected response shapes.
 - [Console MCP setup](CONSOLE_MCP_SETUP.md): Console transports, blocked tables, credential scanning, redaction, SQL validation, and production safeguards.
 - [MCP HTTP transport](MCP_HTTP_TRANSPORT.md): shared/remote Index Server transport, authentication, origins, and protocol details.
+- [Edit client adapters](CLIENT_HOOKS.md): opt-in Claude/OpenCode registration, complete path batches, and recovery.
 - [MCP worktree setup](MCP_WORKTREE_SETUP.md): register Woods correctly when agents work in linked git worktrees.
 
 ## Index lifecycle
 
+- [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.
 - [Embedding models](EMBEDDING_MODELS.md): choose and size local Ollama models.
 - [Upgrade to Woods 2.0](UPGRADING_TO_2.md): identifier changes, atomic payloads, durable-store reconciliation, and rollback.
@@ -48,8 +51,10 @@ and stdio or Streamable HTTP endpoints directly.
 
 - [Why Woods](WHY_WOODS.md): the problems runtime introspection solves.
 - [Internals](INTERNALS.md): extraction, publication, graph, storage, retrieval, and MCP components.
+- [Ruby runtime trace enrichment](RUNTIME_TRACING.md): record observed Ruby callers and merge trace evidence into method units.
 - [Extractor reference](EXTRACTOR_REFERENCE.md): what each extractor produces and the edge cases it handles.
 - [Reading a published index from Ruby](PUBLISHED_INDEX.md): the `Woods::PublishedIndex` Ruby API for cops, gate scripts, and `woods:check:*` tasks (including the moved-message check).
+- [Published index layout](INDEX_LAYOUT.md): the filesystem contract for non-Ruby readers, with Bash/jq and Python examples, retention pins, and snapshot-copy rules.
 - [Evaluation](EVALUATION.md): retrieval scoring, baselines, and the agent-level index on/off ablation.
 - [Backend matrix](BACKEND_MATRIX.md): implemented provider/store combinations and their operational requirements.
 - [Token benchmark](TOKEN_BENCHMARK.md): evidence behind Woods token-estimation defaults.
@@ -89,6 +94,8 @@ Use this map when changing behavior or documentation. Update the owner first; ot
 | Contributor policy | [CONTRIBUTING.md](../CONTRIBUTING.md) |
 | Coding-agent repository instructions | [AGENTS.md](https://github.com/lost-in-the/woods/blob/main/AGENTS.md) |
 | Non-MCP Ruby access to a published index | [PUBLISHED_INDEX.md](PUBLISHED_INDEX.md) |
+| Generation-bound source evidence and fresh extraction | [SOURCE_FRESHNESS.md](SOURCE_FRESHNESS.md) |
+| Published filesystem layout for external readers | [INDEX_LAYOUT.md](INDEX_LAYOUT.md) |
 | Evaluation harnesses | [EVALUATION.md](EVALUATION.md) |
 
 The current public surface is generated from 35 extractors. Counts and capability claims must match `.Codex/release-v2/surface-inventory.json`, which is generated from the code and verified in CI.