woods 2.0.0.beta3 → 2.0.0

data/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to Woods
 
 <!-- release-state:contributing-intro -->
-Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta3/AGENTS.md).
+Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.0.0/AGENTS.md).
 <!-- release-state:end -->
 
 ## Choose the right channel
@@ -46,7 +46,7 @@ Create a branch from current `main`. Keep each pull request to one logical chang
 | `plugin/skills/` | Distributed Woods skills (setup/upgrade, MCP configuration, investigation, agent enablement, diagnosis) |
 
 <!-- release-state:contributing-architecture -->
-Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta3/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
+Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.0.0/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
 <!-- release-state:end -->
 
 ### Agent orientation and static self-map
@@ -263,7 +263,7 @@ By contributing, you agree that your contribution is licensed under the [MIT Lic
 
 ## Release flow
 
-`main` is the development branch and never claims a released version. Between releases it carries the alpha development marker. Every release, including a beta or a release candidate, is an explicit commit plus a tag, cut by one rake task and published only by the guarded workflow.
+`main` is the development branch. It carries an alpha marker before the first prerelease of a version line and after reopening development following a final release. During beta/RC iteration, it retains the last prepared prerelease version until the next `release:prepare`. Every published release is identified by its exact tagged commit; later commits on `main` are not that release even if `Woods::VERSION` is unchanged.
 
 | State | `Woods::VERSION` | Tagged | On RubyGems | Documentation links point at |
 |---|---|---|---|---|
@@ -274,7 +274,9 @@ By contributing, you agree that your contribution is licensed under the [MIT Lic
 
 RubyGems treats any letter in a version as a prerelease, so a `~> 1.6` or `~> 2.0` constraint never resolves a beta or a release candidate. Adopting one is explicit: `gem "woods", "2.0.0.beta1"`.
 
-`spec/release_v2/version_state_spec.rb` enforces this table on every commit. VERSION is either an alpha or the changelog carries its dated heading, and the four `release-state` documentation fences match the state VERSION declares.
+`spec/release_v2/version_state_spec.rb` verifies that VERSION is either an alpha or the changelog carries its dated heading, and that the four `release-state` documentation fences match the state VERSION declares. Those checks do not establish that a checkout is the published release.
+
+For Git-sourced candidates, record the locked Git revision, loaded gem path, and working-tree changes alongside `Woods::VERSION`. Version-only preflight establishes the declared version, not whether a particular post-tag fix is present. Match capability claims to the pinned commit or published tag. Generated release-state links continue to describe the prepared version; use the candidate commit when linking evidence about unreleased changes.
 
 ### During feature work
 
@@ -312,10 +314,12 @@ One command per transition. It never commits, tags, pushes, or publishes.
 | Alpha to the first beta | `bin/rake "release:prepare[2.0.0.beta1]"` |
 | Beta to the next beta or a release candidate | `bin/rake "release:prepare[2.0.0.rc1]"` |
 | Release candidate to the release | `bin/rake "release:prepare[2.0.0]"` |
-| After the release publishes, reopen development | `bin/rake "release:reopen[2.1.0.alpha]"` |
+| After a final release publishes, reopen development | `bin/rake "release:reopen[2.1.0.alpha]"` |
 
 `release:prepare` refuses a dirty working tree, a version that moves backwards, a version whose base is not the line `main` is developing, and an alpha target. It then bumps VERSION, folds `## [Unreleased]` and optional entry files into `## [<version>] - <date>` with one block per `###` heading, restates the fences, regenerates the surface inventory, and prints the tag and dispatch commands. Every rewrite is computed before any of it is written, so a refusal leaves the working tree untouched.
 
+`release:reopen` accepts only a final release and a strictly later alpha. It does not reopen a beta/RC or move the same version line backwards to alpha. Continue prerelease development with Unreleased notes or changelog fragments, then use `release:prepare` for the next forward beta, RC, or final when authorized.
+
 A final release also absorbs every prerelease section of its own base version. Cutting `2.0.0` folds `## [2.0.0.beta1]` and `## [2.0.0.rc1]` into `## [2.0.0] - <date>` and removes their headings, prerelease entries first and anything written after them second, so the notes a user reads for 2.0.0 are the whole story rather than three fragments. An empty `## [Unreleased]` is therefore legitimate for a final release cut straight from a release candidate. A beta or a release candidate has nothing to absorb, so an empty Unreleased section without entry files refuses: there is nothing new to publish.
 
 Review the diff and run the release contracts:
@@ -391,12 +395,12 @@ short body that links `CHANGELOG.md` at the tag itself (not at `main`) and
 anchors straight to that version's dated heading, so the note a reader lands
 on always matches the bytes RubyGems published.
 
-### One-off 1.6.2 security maintenance release
+### One-off 1.6.3 security maintenance release
 
 The [security policy](SECURITY.md#supported-versions) supports 1.6.x security
 fixes until 2027-02-20. While main develops v2, the sole maintenance exception
-is `v1.6.2` from the short-lived `release/1.6.2` branch, descending from the
-immutable v1.6.1 commit `73423a42644176b09961be373e13648c94690933`.
+is `v1.6.3` from the short-lived `release/1.6.3` branch, descending from the
+immutable v1.6.2 commit `4b40e17fd68122a70ccf00d9d2ffb8af42171d3d`.
 This is a stable patch, separate from the next v2 prerelease; it does not declare
 v2 final or establish a general-purpose maintenance publishing path.
 
@@ -413,15 +417,15 @@ The preparation order is:
 1. Merge the main-side maintenance policy/tooling PR. Before creating the remote
    target, confirm its effective branch rules require pull requests and prevent
    force pushes and deletion; configure those rules before creating the target. The GitHub
-   rules API can check `release/1.6.2` before the branch exists.
-2. Create that target from the immutable v1.6.1 commit. Review the narrow security
-   backport and its legacy preparation adapter against that line. Disable the
-   inherited automatic tag-push publisher before any maintenance tag exists.
-3. Use the legacy adapter's `release:reopen[1.6.2.alpha]` and
-   `release:prepare[1.6.2]` transitions in clean, separately reviewed commits.
+   rules API can check `release/1.6.3` before the branch exists.
+2. Create that target from the immutable v1.6.2 commit. Review the narrow security
+   backport and its legacy preparation adapter against that line. Confirm the
+   inherited automatic tag-push publisher remains disabled before any maintenance tag exists.
+3. Use the legacy adapter's `release:reopen[1.6.3.alpha]` and
+   `release:prepare[1.6.3]` transitions in clean, separately reviewed commits.
    The adapter owns the legacy documentation profile; do not copy v2 fences or
    surface claims into v1, and never hand-edit VERSION.
-4. Review and merge the prepared candidate into `release/1.6.2`. Require passing
+4. Review and merge the prepared candidate into `release/1.6.3`. Require passing
    unit, booted Rails, installed-package, lint, coverage, security and build
    jobs. Review the complete CI and package-test implementation at that SHA.
    Then pin that **exact final commit** in `MAINTENANCE_APPROVED_SHA` through the
@@ -431,6 +435,14 @@ The preparation order is:
    Every exact maintenance matrix row in the trusted profile must succeed;
    missing, duplicated, skipped or failed rows refuse publication.
 
+[Temporary security-advisory forks](https://docs.github.com/en/code-security/tutorials/fix-reported-vulnerabilities/collaborate-in-a-fork)
+do not run CI or enforce destination branch protections when the advisory is
+merged. Review and test those patches privately, then require the upstream CI
+matrix triggered by the push to `release/1.6.3` before pinning its prepared SHA.
+A private test report cannot replace the upstream tag-push run and immutable
+artifact required for publication. Keep the advisory unpublished until the fixed
+gems are available.
+
 The validators require the approved SHA to remain reachable from the freshly
 fetched maintenance branch and to descend from the fixed legacy base. They retain
 exact tag/VERSION/changelog checks, the unpublished-version check, one immutable
@@ -446,11 +458,11 @@ RubyGems credentials; the remote tag is checked again immediately before push.
 A candidate fix or changed prepared SHA requires a new reviewed main pin and a
 fresh tag-push CI run. Updating main's tooling alone never authorizes different
 candidate bytes. Main's v2 release contract remains unchanged. Do not create or
-push tags, dispatch, publish, or claim 1.6.2 is available during preparation.
+push tags, dispatch, publish, or claim 1.6.3 is available during preparation.
 
 ### Stable branches
 
-A stable branch is `N-M-stable`, cut from the release tag. Create one only when a released line needs a patch after a newer major has shipped on `main`; until then, `main` is the development branch. The explicitly approved short-lived `release/1.6.2` security exception above does not establish an `N-M-stable` branch.
+A stable branch is `N-M-stable`, cut from the release tag. Create one only when a released line needs a patch after a newer major has shipped on `main`; until then, `main` is the development branch. The explicitly approved short-lived `release/1.6.3` security exception above does not establish an `N-M-stable` branch.
 
 ### What coding agents may do
 

data/README.md

@@ -4,38 +4,23 @@
 
 # Woods
 
-**Give AI coding agents a runtime-accurate map of your Rails application.**
+**Give coding agents the Rails context that source files alone leave out.**
 
 [![Gem Version](https://img.shields.io/gem/v/woods)](https://rubygems.org/gems/woods)
 [![CI](https://github.com/lost-in-the/woods/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/lost-in-the/woods/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
-<!-- release-state:version-banner -->
-> **This tree documents version 2.0.0.** It is a major update from 1.x: read [what changed and how to upgrade](docs/UPGRADING_TO_2.md) before updating. The full history is in the [CHANGELOG](CHANGELOG.md).
->
-> `main` is the development branch and can run ahead of the latest published gem. The gem badge above shows the latest published version; documentation for a published version lives on its tag.
->
-> ### Version: 2.0.0.beta3 is published as a prerelease; `main` documents 2.0.0
->
-> | Line | Version | Documentation |
-> |---|---|---|
-> | Documented here | **2.0.0**, unreleased | this README and the [documentation index](docs/README.md) |
-> | Latest prerelease | **2.0.0.beta3** | [the v2.0.0.beta3 tag](https://github.com/lost-in-the/woods/tree/v2.0.0.beta3) |
-> | Latest published gem | **1.6.1** | [the v1.6.1 tag](https://github.com/lost-in-the/woods/tree/v1.6.1) |
->
-> RubyGems treats 2.0.0.beta3 as a prerelease, so `gem "woods", "~> 2.0"` does not resolve it. Install it explicitly with `gem "woods", "2.0.0.beta3"`. The released constraint stays `gem "woods", "~> 1.6"`.
-<!-- release-state:end -->
+Woods boots your Rails application, extracts its resolved structure, and publishes an index that coding agents can query through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). It brings together database schema, associations, callbacks, concerns, routes, and source code so an agent can inspect how Rails assembles your application.
 
-Woods boots your Rails app, extracts the behavior Rails assembles at runtime, and serves it to AI tools through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Agents can inspect resolved routes, schema, associations, callbacks, included concerns, dependencies, and execution flows instead of guessing from source files alone.
+Supports **Ruby 3.0+ and Rails 6.0–8.x**, using a Ruby version supported by your Rails release. The application must boot and connect to its database. Structural queries need no embedding provider or vector database.
 
-Woods 2.0 supports Ruby 3.0 or later and Rails 6.0 through 8.x. It connects AI coding tools and agents through MCP.
+[Get started](#five-minute-setup) · [Documentation](docs/README.md) · [Agent setup](docs/AGENT_SETUP.md) · [Upgrade from 1.x](docs/UPGRADING_TO_2.md)
 
 ## What Woods adds
 
-A Rails model rarely lives in one file. Its real behavior can include database schema, generated methods, framework defaults, and concerns loaded from elsewhere:
+Consider a model whose behavior is spread across Rails, the database, and a concern:
 
 ```ruby
-# app/models/order.rb
 class Order < ApplicationRecord
   include Auditable
   belongs_to :customer
@@ -43,44 +28,40 @@ class Order < ApplicationRecord
 end
 ```
 
-Woods turns that runtime class into one connected unit with:
+Woods can give an agent one unit containing its columns and indexes, association metadata, resolved callbacks, and included concern source. Recorded relationships connect that unit to other parts of the application.
 
-- column types, indexes, and foreign keys from the live database;
-- associations, validations, scopes, enums, and resolved callbacks;
-- source from included concerns, kept beside the owning class;
-- callback side effects such as jobs, mailers, and columns written;
-- forward dependencies and reverse dependents;
-- route, controller, view, job, and service relationships.
+An agent can then ask:
 
-The result is a codebase index an agent can query by exact name, pattern, dependency path, graph structure, or natural language.
+> Find the Order model, inspect its callbacks and associations, and show its recorded dependents. Cite the indexed evidence and check source code for callers the graph may miss.
 
-Still weighing it? [Why Woods](docs/WHY_WOODS.md) makes the case against grep, cloud indexers, and IDE language servers.
+Models are one part of the index: Woods also extracts controllers, routes, jobs, mailers, views, components, GraphQL types, service objects, tests, and more. See the [extractor reference](docs/EXTRACTOR_REFERENCE.md) for coverage and the [agent guide](docs/AGENT_GUIDE.md) for query examples.
 
 ## Five-minute setup
 
-The default setup provides structural code intelligence. It does not require an embedding provider, vector database, or access to live application records.
+For agent-led setup, use the [agent installation option](#let-an-agent-install-it) and its runbook. For a new manual installation, follow the steps below.
 
-### 1. Install Woods
+**Already using Woods?** If you are upgrading from 1.x, follow the [upgrade guide](docs/UPGRADING_TO_2.md). For an existing 2.x installation, go directly to [retrieval modes](#retrieval-with-or-without-embeddings), [MCP configuration](docs/MCP_SERVERS.md), or the [configuration reference](docs/CONFIGURATION_REFERENCE.md). Preserve your initializer, index path, provider settings, and other client entries. Changing only the MCP launch configuration or retrieval mode does not require rerunning the installer or rebuilding the structural index.
 
-First [choose a version that is published on RubyGems](docs/GETTING_STARTED.md#1-install-the-gem).
-The example below requires a stable 2.x release; beta and release-candidate
-installations need an exact published prerelease pin from that guide.
+Run installation and extraction commands from your Rails application root in its normal development environment. **Using Docker?** Follow [Docker setup](docs/DOCKER_SETUP.md) first: run those commands inside the application container and use paths visible to the process that runs MCP.
 
-```ruby
-# Gemfile
-group :development do
-  gem "woods", "~> 2.0"
-end
-```
+### 1. Install and configure
+
+These steps are for **Woods 2.x**. Choose a published 2.x version from [RubyGems](https://rubygems.org/gems/woods/versions). If only prereleases are available, use an exact prerelease pin; `~> 2.0` will not select one. Follow the chosen version's tag documentation rather than assuming every feature on `main` is published. If you choose 1.x, use its tag documentation instead of this quickstart.
+
+<!-- release-state:version-banner -->
+<!-- release-state:end -->
+
+Once a stable 2.x release is published, add `gem "woods", "~> 2.0"` to your Gemfile's `:development` group. For a prerelease, use its exact published version instead. Then run:
 
 ```bash
 bundle install
+bundle exec ruby -rwoods/version -e 'puts Woods::VERSION'
 bin/rails generate woods:install
 ```
 
-**Do not run the generated migration for a new default installation.** The generator creates an annotated `config/initializers/woods.rb` plus a legacy application migration for `woods_units`, `woods_edges`, and `woods_embeddings`. Woods 2's shipped structural index and storage backends do not use those application tables. Remove the migration before continuing; keep and run it only when deliberately preserving an older/custom integration that uses them.
+**For a new default installation, remove the generated `db/migrate/*_create_woods_tables.rb` migration without running it.** Those legacy application tables are unused by the shipped index and storage backends. Keep the generated `config/initializers/woods.rb`; its defaults are sufficient. Only retain the migration for a deliberate older/custom integration. See [Getting started](docs/GETTING_STARTED.md#2-generate-and-review-configuration).
 
-### 2. Extract and verify the codebase
+### 2. Extract and validate
 
 ```bash
 bin/rails woods:extract
@@ -88,11 +69,11 @@ bin/rails woods:validate
 bin/rails woods:stats
 ```
 
-Extraction must run where Rails can boot. The default index lives at `tmp/woods/`.
+Run these where your Rails application can boot. The default output is `tmp/woods/`; keep this generated directory out of source control.
 
-### 3. Connect the Index Server
+### 3. Connect your MCP client
 
-Add this to your MCP client's project configuration. The configuration location varies by client:
+Adapt this example to your MCP client's project configuration format, using your application path and preserving other server entries. See [client configuration locations](docs/MCP_SERVERS.md#client-configuration-locations) for guidance:
 
 ```json
 {
@@ -106,175 +87,94 @@ Add this to your MCP client's project configuration. The configuration location
 }
 ```
 
-Restart or reconnect your MCP client, then ask it to call `woods_status`. A ready response with non-zero unit counts confirms the path from Rails extraction to the MCP client.
-
-The Index Server reads the published index from disk. It does not boot Rails or query application records.
+Reconnect the client and ask it to call `woods_status`. Confirm the index path and non-zero unit counts. Then use `search` to discover a known class and `lookup` with its identifier **and type** to inspect it.
 
-> **Using Docker?** Run Rails commands inside the application container. If Woods is installed only there, launch the Index Server through that container too; a host-side server requires a host Ruby bundle and host-visible index. Follow [Docker setup](docs/DOCKER_SETUP.md).
+The Index Server reads the published index without booting Rails or querying application records. See [MCP servers](docs/MCP_SERVERS.md) for client-specific configuration and HTTP transport.
 
-The complete walkthrough, including expected output and first questions to ask, is in [Getting started](docs/GETTING_STARTED.md).
-
-## Let an agent install it
+If Woods is installed only inside Docker, launch MCP through that container too. Host-side launch needs a host bundle and a host-visible index; see the [Docker process and path rule](docs/MCP_SERVERS.md#docker-process-and-path-rule).
 
-Woods is built to be agent-operated, and the fastest path is handing installation to the coding agent that will use it. Claude Code users can install the distributed skills once — they trigger on install, upgrade, configuration, investigation, and diagnosis on their own:
+## Retrieval: with or without embeddings
 
-```bash
-/plugin marketplace add lost-in-the/plugins
-/plugin install woods-plugin@lost-in-the-plugins
-```
+Exact lookup, pattern search, and graph queries work immediately after extraction. For ranked retrieval through `codebase_retrieve`, choose a mode:
 
-With any coding agent (no plugin needed), paste this into a session opened at your Rails app's root:
-
-```text
-Install or upgrade the woods gem in this Rails application by following
-https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md.
-Structural setup only: add the gem to the development group, run the
-installer, extract and validate the index, and register the Index MCP
-server for this app. Do not run the generated legacy migration, and do
-not add embedding providers, vector databases, Console/live-data access,
-or secrets without asking me first. If woods 1.x is already installed,
-follow the upgrade runbook in docs/UPGRADING_TO_2.md instead and plan a
-clean re-index. Finish by reporting the installed version, files
-changed, commands run, and one verified woods_status call through the
-registered MCP server.
-```
+| Mode | Setup | What it searches |
+|---|---|---|
+| **Lexical** | Set `WOODS_RETRIEVAL_MODE=lexical` in the MCP process environment and restart the server | Published extraction units, ranked by field-aware keyword matching; no provider or embeddings |
+| **Semantic** (default mode) | Configure a local or hosted embedding provider, then run `bin/rails woods:embed` | Embedded code context, ranked by semantic similarity |
 
-The runbook holds the agent to the same guardrails the skills enforce: a version preflight, minimal diffs, and explicit approval before anything beyond the structural index. Prefer doing it by hand? The five-minute setup above is the same procedure as commands.
+For the stdio configuration above, add `"env": {"WOODS_RETRIEVAL_MODE": "lexical"}` inside the `woods` server entry to choose lexical mode. Confirm the active retriever with `woods_status`.
 
-## Choose your path
+To switch back to semantic retrieval, remove the lexical environment override or set `WOODS_RETRIEVAL_MODE=semantic`, configure the provider and embedding artifacts, then restart the MCP server and verify `woods_status`. Switching to lexical does not delete existing vectors or provider configuration.
 
-| Goal | Start here |
-|---|---|
-| Install Woods yourself | [Getting started](docs/GETTING_STARTED.md) |
-| Ask a coding agent to install Woods safely | [Agent setup runbook](docs/AGENT_SETUP.md) |
-| Configure an MCP client, Docker, or HTTP | [MCP servers](docs/MCP_SERVERS.md) |
-| Teach an agent how to query Woods effectively | [Agent guide](docs/AGENT_GUIDE.md) |
-| Add semantic search with OpenAI or local Ollama | [Retrieval guide](docs/RETRIEVAL_GUIDE.md) |
-| Query live Rails data through the optional Console Server | [Console MCP setup and security](docs/CONSOLE_MCP_SETUP.md) |
-| Keep the index current automatically while coding | [Watch daemon](docs/WATCH_DAEMON.md) |
-| Upgrade an existing 1.x installation | [Upgrade to Woods 2.0](docs/UPGRADING_TO_2.md) |
-| Diagnose a failure | [Troubleshooting](docs/TROUBLESHOOTING.md) |
+The [lexical guide](docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval) and [semantic setup](docs/RETRIEVAL_GUIDE.md#configuring-retrieval) cover configuration, ranking, and response budgets. Lexical matching depends on shared vocabulary; semantic mode requires the configured provider and embedding artifacts.
 
-## Upgrading from 1.x
+## Keeping the index current
 
-Woods 2.0 is a major release: identifiers, the on-disk layout, the MCP surface, and task failure posture all changed. [Upgrade to Woods 2.0](docs/UPGRADING_TO_2.md) holds the full what-changed table, the step-by-step runbook with backups and rollback, and an agent-operated upgrade prompt.
+Run one watcher through your normal development startup. It catches up on
+changes, publishes complete generations, and lets the Index Server refresh on
+later tool calls. The [startup guide](docs/WATCH_DAEMON.md#managed-development-startup)
+covers Puma, existing Foreman workflows, and Docker/Grove supervision. Managed
+startup requires a supporting gem; **check installed capabilities**. Older packages run the raw
+`bin/rails woods:watch` task under an external restart-capable supervisor.
 
-## Optional Claude Code workflows
+Without a watcher, run `bin/rails woods:incremental` after edits or
+`bin/rails woods:extract` for a full rebuild. MCP registration alone does not
+enable automatic maintenance.
 
-Woods itself is MCP-client and model independent. The separately packaged Woods plugin (install commands under [Let an agent install it](#let-an-agent-install-it)) gives Claude Code five guided skills: setup and upgrade, MCP configuration, index-driven investigation, repository agent enablement, and diagnosis. Other MCP clients do not need it; follow the human or agent runbooks linked above and configure either stdio or Streamable HTTP directly.
+Incremental cost depends on the affected code and relationships; broad changes can cost as much as a full extraction. Semantic embeddings have a separate update step. See [Watch daemon](docs/WATCH_DAEMON.md), [incremental extraction](docs/INCREMENTAL_EXTRACTION.md), and [source freshness](docs/SOURCE_FRESHNESS.md).
 
 ## Two servers, two trust boundaries
 
-Woods ships two MCP servers. Most users only need the Index Server.
-
 | | Index Server | Console Server |
 |---|---|---|
-| Purpose | Query pre-extracted code context | Query live Rails models and schema |
-| Data source | Files under `tmp/woods/` | A booted Rails process and its database |
-| Default tools | 14 | 9 |
-| Optional tools | Semantic retrieval activates after embedding; advanced Ruby embeddings can wire more collaborators | `console_sql` and `console_query` raise the total to 11 when explicitly enabled |
-| Default posture | Read-only index | Disabled; live-data access requires deliberate setup |
-
-The 14 Index tools cover health, exact lookup, search, dependency traversal, flow tracing, graph analysis, framework source, change recency, and optional semantic retrieval. The Console Server exposes nine supported model/schema tools by default. Nineteen Tier 2/3 Console schemas (9 Tier 2, 10 Tier 3) and `console_eval` exist as source inventory but do not register in any supported mode.
-
-See [MCP servers](docs/MCP_SERVERS.md) for the callable tool lists and client configuration.
-
-## Optional semantic search
-
-Exact search, lookup, graph traversal, and flow tools work after extraction alone. Natural-language retrieval through `codebase_retrieve` also needs embeddings:
-
-```ruby
-# config/initializers/woods.rb
-Woods.configure_with_preset(:local)
-```
-
-The `:local` preset uses SQLite metadata, in-memory vectors persisted under the index, and a local Ollama service. It needs the `sqlite3` gem in the application bundle plus an installed, running Ollama service, but no cloud API key. Pull the default model before the first embed:
+| Purpose | Inspect extracted code context | Query live Rails models and schema |
+| Reads | Published index files | A booted application and its database |
+| Packaged tools | 14; retrieval usable when configured | 9; 11 with embedded read tools enabled |
+| Setup | The workflow above | Optional, disabled by default |
 
-```bash
-ollama pull nomic-embed-text
-```
+Extraction itself boots and eager-loads your application, so its boot-time behavior still runs. Treat the generated index as confidential application source. Enabling hosted embeddings sends the embedded content to that provider. MCP responses also contain application source, which your client may send to its model provider even when Woods uses lexical retrieval or local embeddings.
 
-MySQL/PostgreSQL applications that do not bundle `sqlite3` can use `:shared_filesystem` for local persisted stores instead. PostgreSQL/OpenAI, Qdrant/OpenAI, and shared-filesystem configurations are documented in the [backend matrix](docs/BACKEND_MATRIX.md) and [configuration reference](docs/CONFIGURATION_REFERENCE.md).
+The optional Console Server can access live data. Review its [setup and security model](docs/CONSOLE_MCP_SETUP.md) before enabling it. Report vulnerabilities privately through [SECURITY.md](SECURITY.md).
 
-For dense Ruby source, add `gem "tokenizers", "~> 0.5"` for exact WordPiece token counting. Without it, Woods uses a character estimate that can over-pack some Ollama chunks.
+## What the index can and cannot establish
 
-```bash
-bin/rails woods:embed
-```
+- **It is a snapshot.** Check freshness against your working tree before relying on it for a change.
+- **Relationships are recorded evidence, not a complete call graph.** Arbitrary method-body constant references are not exhaustively indexed. No recorded dependents does not prove that a class has no callers or is safe to delete.
+- **A traced flow is not proof of execution.** Follow the tool's evidence and limits, and verify behavior in the application when it matters.
 
-Reconnect the Index Server after the first embed, then check `woods_status` before using `codebase_retrieve`.
+Use Woods to locate and connect evidence, then confirm the relevant source and tests. The [agent guide](docs/AGENT_GUIDE.md) describes this workflow.
 
-## Keeping the index current
-
-Run a full extraction after installation or broad configuration changes:
-
-```bash
-bin/rails woods:extract
-```
-
-For automatic maintenance during development, run the watcher as a dedicated process:
+## Let an agent install it
 
-```bash
-bin/rails woods:watch
-```
+Use the [agent setup runbook](docs/AGENT_SETUP.md) for a copyable installation prompt and verification checklist. Woods works with MCP-capable clients independently of a specific model or editor.
 
-Add it to your development process manager so it starts beside Rails:
+Claude Code users can optionally install the companion workflows:
 
 ```text
-# Procfile.dev
-web:   bin/rails server
-woods: bundle exec rake woods:watch
-```
-
-The watcher catches up changes made while it was stopped, batches new file changes, reloads Rails code when safe, and publishes complete generations atomically. The Index Server notices a new generation on its next tool call and refreshes itself. **After the initial extraction, ordinary code changes need no manual re-extraction or MCP restart.**
-
-Changes to boot-captured state, including dependencies, initializers, database configuration, credentials, or schema, make the watcher exit with status 75 so a process supervisor can restart it cleanly. If semantic retrieval is enabled, the watcher keeps structural context current; run `bin/rails woods:embed_incremental` to update vectors.
-
-In CI on Rails 8.1, add one step to `config/ci.rb` so the index the gates read matches the commit under test:
-
-```ruby
-step "Woods: refresh", "bin/rails woods:incremental"
+/plugin marketplace add lost-in-the/plugins
+/plugin install woods-plugin@lost-in-the-plugins
 ```
 
-Claude Code users with the Woods plugin can opt into the same refresh from a `PostToolUse` hook, plus a `SessionStart` warning scoped to commit timestamps (it does not see uncommitted edits or an older checkout). Both ship disabled; set `WOODS_HOOKS_ENABLED=1` to turn them on. See [Watch daemon](docs/WATCH_DAEMON.md#hooks-for-agent-sessions).
-
-Without a resident watcher, run `bin/rails woods:incremental` after changes. See [Watch daemon](docs/WATCH_DAEMON.md) for Docker polling, failure behavior, and restart triggers.
-
-## What gets indexed
-
-Woods recognizes the Rails application as a connected system, including:
-
-- models, concerns, controllers, routes, middleware, and engines;
-- services, interactors, commands, jobs, mailers, and scheduled work;
-- ERB views, Phlex components, ViewComponents, and navigation edges;
-- GraphQL types, mutations, resolvers, and fields;
-- policies, serializers, decorators, validators, state machines, and events;
-- migrations, database views, factories, tests, configuration, and installed framework source.
-
-Read the [extractor reference](docs/EXTRACTOR_REFERENCE.md) for the complete per-type contract and [internals](docs/INTERNALS.md) for how extraction, storage, retrieval, and MCP fit together.
-
-## Security boundary
-
-Woods extraction reads application code, resolved Rails configuration, and database schema. Treat the generated index as source code: do not publish it unless the source itself may be published.
-
-The optional Console Server has a larger trust boundary because it can read live application data. It is disabled by default and adds table blocking, credential scanning, column redaction, SQL validation, and rolled-back transactions when enabled. Those controls reduce risk; they do not turn production data access into a harmless default. Review [Console MCP security](docs/CONSOLE_MCP_SETUP.md#safety-model) before enabling it.
-
-Report vulnerabilities privately through [SECURITY.md](SECURITY.md).
+The plugin guides installation, MCP configuration, investigation, repository agent setup, and diagnosis. It is distributed separately from the gem.
 
 ## Documentation
 
-Use the [documentation index](docs/README.md) to find guides by task or audience. Frequently used references include:
+| Task | Guide |
+|---|---|
+| Install and verify | [Getting started](docs/GETTING_STARTED.md) |
+| Configure clients, Docker, or HTTP | [MCP servers](docs/MCP_SERVERS.md) |
+| Query effectively | [Agent guide](docs/AGENT_GUIDE.md) and [tool cookbook](docs/MCP_TOOL_COOKBOOK.md) |
+| Configure Woods | [Configuration reference](docs/CONFIGURATION_REFERENCE.md) |
+| Choose retrieval and storage | [Retrieval guide](docs/RETRIEVAL_GUIDE.md) and [backend matrix](docs/BACKEND_MATRIX.md) |
+| Upgrade from 1.x | [Upgrade guide](docs/UPGRADING_TO_2.md) |
+| Diagnose a failure | [Troubleshooting](docs/TROUBLESHOOTING.md) |
 
-- [Configuration reference](docs/CONFIGURATION_REFERENCE.md)
-- [MCP tool cookbook](docs/MCP_TOOL_COOKBOOK.md)
-- [FAQ](docs/FAQ.md)
-- [Troubleshooting](docs/TROUBLESHOOTING.md)
-- [Upgrade to Woods 2.0](docs/UPGRADING_TO_2.md)
+See the [documentation index](docs/README.md) for all guides and canonical reference pages.
 
 ## Contributing
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. Coding agents working in the source repository should also read [AGENTS.md](https://github.com/lost-in-the/woods/blob/main/AGENTS.md).
+Use [GitHub issues](https://github.com/lost-in-the/woods/issues) for bugs and feature requests. Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request; coding agents should also read [AGENTS.md](https://github.com/lost-in-the/woods/blob/main/AGENTS.md).
 
 ## License
 
-Woods is available under the [MIT License](LICENSE.txt).
+[MIT](LICENSE.txt).