woods 2.0.0.beta3 → 2.0.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1877858142850cdb2a9802c103198cf5be63439e610ebbc43cd10f97554f10d
-  data.tar.gz: 5bad5ce4acdb04312a53d31414ea0b93b3cb4d7c103209f3172bb84e509278c3
+  metadata.gz: eec7697bb9a6d63c1c22b57ceb68fb302083252c8e593b66d9f8f34ca5368536
+  data.tar.gz: 472e74cdd65897553bc232c683b49c9028614ec801ad855d3dc85b3bcb581aae
 SHA512:
-  metadata.gz: d878e5d2d4f51dcb4fcf4e39af29e78edf23eae756d0db4f2fe3b4c6e77454295d7a6f455d4d1f3aa397d70fb51253be040ca3ec29e17e32bd5d854dd4b434e4
-  data.tar.gz: 37a249bb634be55999c9d6ae1f058cd72a80be48496fc04b93d9d4213fa1355f1c7ff8d2d21abeeabaa8f88846846110a82547572ce74bce90dbb75d18133a0a
+  metadata.gz: 21cef2ca233373593a8f431fdbf5ef8cdd77838b7b62eb5785d854a38be6855b5df33c3c966183ea62caa1505223ca7ccc59f3e6cc7ced856788ba40b375e574
+  data.tar.gz: d4a38ce584e87434bb0b17a9b8609a1ffc57473a75ee9eeeeb8211d17d9fa5aed3f5a7bf411cf1b6caa3ba16a53f642c94f26b8b382b9195582766ce2dfe9065

data/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0.beta4] - 2026-09-22
+
+### Build
+
+- Allow the exact 1.6.3 maintenance tag and branch from the released 1.6.2 base while keeping publication disabled until a separately reviewed candidate SHA is pinned. Preserve all CI, immutable-artifact, package-test and protected-environment release gates.
+
+### Documentation
+
+- Correct watcher retry guidance to include heartbeat-driven recovery, identify
+  session identity corrections as available in 2.0.0.beta3, and align the
+  coding-agent Docker synopsis with the container-first setup guide.
+- Scope orphan results to recorded relationships, document the limits of artifact
+  permission defaults, correct Claude Code worktree registration guidance, and
+  expose embedding-free lexical retrieval in the MCP tool cookbook.
+Update the distributed agent guides to identify Woods 2.0.0.beta3 capabilities and plugin 2.3.36 hook recovery accurately, while preserving installed-version and schema checks.
+- Clarify that beta/RC development retains the last prepared version, source
+  candidates require Git revision evidence, and development reopening applies
+  only after a final release. Release transitions and version ordering are unchanged.
+
+### Fixed
+
+Accept ASCII case variants of the HTTP `Bearer` authentication scheme for Index and Console MCP. Token bytes, constant-time comparison, and existing delimiter rules remain unchanged. (#497)
+- Console SQL validation now distinguishes keyword grammar from identically named functions before applying the read-only function allowlist. SQLite application-defined keyword functions are rejected before execution; ordinary window, predicate, and numeric pagination syntax remains supported.
+- Report malformed generation marker shapes during embedded Index MCP startup as an actionable `ArgumentError` with the selected directory and published-layout guidance, matching executable preflight behavior. Preserve legacy flat and payload indexes and leave later generation-refresh error handling unchanged.
+- Make file-backed session clearing idempotent for Unicode and punctuated IDs, and discard expired history before appending or merging legacy and encoded files. This prevents expired events from becoming visible again through record, read, or listing; live history, disabled TTL, and retention limits retain their existing behavior.
+Dependency and dependent responses now disclose that published relationships are not exhaustive source-reference coverage, including compact and empty answers. Human witness labels say “witness types unambiguous” while preserving the JSON `typed_path_complete` contract. Successful traversal responses add `total_is_exact`; budget-limited text reports a root-inclusive lower bound and its cutoff reason, independently of pagination. (#470, #471)
+GraphQL parent metadata and summary chunks now read the selected declaration's superclass, rather than borrowing a nested or sibling class's parent. Compact qualified declarations preserve their explicit parent; implicit, dynamic, or unavailable parents remain unknown. Identifiers and dependency classification are unchanged.
+- Preserve the published generation when incremental extraction or named refresh encounters handled source errors. Failed consumers no longer replace last-good units with empty or partial output; watch retains the complete batch for retry.
+- Make missing-index startup headlines describe an unresolved published index instead of implying that atomic indexes require a root `manifest.json`; retain the examined path, layout explanation and existing-index-first remedy (#482).
+- Make `woods-mcp-start` resolve generation payload symlinks before checking their manifest, matching the library's index-root containment check. Preflight rejects escaping links and avoids manifest probes through broken links; contained links and symlinked index roots remain supported. The library already rejected escaping payloads before serving the index.
+- Clarify lexical retrieval responses with actual included-source and considered-candidate counts alongside the shortlist limit. Charge count text to the existing estimated context budget across full, compact, outline and scoped results, distinguishing no matches from matching candidates whose sources do not fit without changing ranking or MCP response structure.
+Stabilize mailer output across Rails processes by sorting action-name inventories consistently and labeling direct Proc defaults and callback filters by source location and callable kind. Preserve callback order, duplicate registrations and ordinary default value types without executing callables. Run a full extraction after upgrading to refresh retained mailer records; affected source hashes may change once. (#484)
+- Stabilize mailer object callback labels across boots by reusing the model extractor's guarded default-representation formatter. Preserve custom labels, literal hexadecimal text, callback order, duplicates and conditions; do not execute callbacks or change non-Proc defaults. Run a full extraction after upgrading to refresh retained mailer metadata; stored index schemas are unchanged.
+- Accept `WOODS_OUTPUT` after the explicit path and `WOODS_DIR` in Index MCP startup, while preserving the launcher's no-path error. Missing-index diagnostics now name the examined directory, describe atomic and legacy layouts, and suggest pointing at an existing index before re-extracting.
+- Recommend explicit embedding-free lexical mode in no-provider startup and retrieval messages, including the required MCP environment change and restart; semantic defaults and typed errors are unchanged.
+- Reconcile Rake tasks across all contributing files on incremental changes and deletions, retaining surviving definitions and removing obsolete source from shared tasks.
+Scope PORO and lib `parent_class` metadata and source annotations to the selected declaration. Nested or sibling error classes no longer supply an unrelated superclass; implicit parents remain nil and explicit constant-path parents retain their names (#474).
+- Reject pgvector HNSW `vector` widths above 2,000 before database writes, and reject invalid migration dimensions before creating files. Correct the 3,072-dimensional generator example and document explicit provider output sizing; no vector truncation or implicit conversion is performed (#524).
+- Describe prepared prereleases without claiming RubyGems publication from VERSION alone, and retain the published 1.6.2 maintenance changelog so generated stable-version guidance stays accurate.
+- Preserve actual GraphQL and gem-source types in `Woods::PublishedIndex` typed lookup and enumeration while retaining the `graphql` and `rails_source` family aliases (#518).
+- Enforce `graph_analysis`'s advertised default of 20 rows per section and retain total/offset context on last and empty pages in every renderer. Correct the structure glossary: graph nodes include isolated units, and retriever entry counts depend on mode and store coverage (#519).
+- Coordinate agent configuration apply and recovery on shared managed targets across application roots, preventing concurrent user-scoped installations from overwriting each other. Keep application-specific receipts, refuse stale plans, and report/protect every coordination path in previews (#520).
+- Apply JSON temporal history limits after matching the requested unit, preserving access to retained records across gaps and deletions with SQLite parity (#521).
+- Reconcile reused in-memory vector and metadata stores during full embedding rebuilds, removing vanished units and publishing empty corpora without changing incremental purge guards. Failed embedding preserves the previous promoted dump and checkpoint (#522).
+Validate persisted JSON snapshot shapes before reading history or capturing the next snapshot. Unusable nested unit records and summary fields now warn and skip the entire snapshot, preserving valid legacy records, corrupt-file retention, and caller SHA validation (#492).
+- Use the same JSON snapshot validity checks for reads and retention: reject filename/content SHA mismatches before selecting a capture baseline, and prune corrupt files before valid legacy snapshots with missing or null timestamps. Timestamp-less snapshots remain eligible for ordinary oldest-first retention.
+Expose the paginated dependencies/dependents payload in `structuredContent.data` with every renderer, including packaged stdio and HTTP defaults, while preserving rendered text and existing tool arguments (#481).
+- Stabilize direct Proc/lambda model validation option values in extracted and published metadata using callable kind and source-location labels, without executing them. Preserve validation order, duplicates, conditions and non-Proc values; nested containers are not recursively normalized. Run a full extraction to refresh retained validation metadata; index schemas are unchanged.
+- Reconcile registered initializers deleted during watch downtime with a full extraction after a fresh environment boot, preserving whole-application runtime facts.
+- Keep the stable extraction guard and output directory after `woods:clean`, so a concurrent writer can finish acquiring its lock safely.
+
+### Security
+
+- Redact protected Console fields before serialization, normalize the remaining values to their JSON-compatible representation, and redact and scan again before JSON or Markdown rendering. Symbol values and custom serializers cannot introduce unscanned credentials in the final response, and protected serializers remain uncalled. The direct credential scanner also scans Symbol values while preserving their type.
+- Check resolved relations against the Console blocked-table policy before default model tools fetch records or counts, including association parent lookups; reuse the checked relation so dynamic default scopes are evaluated once.
+- Refuse unsupported SQLite identifier and table-reference syntax before Console SQL execution, preserving blocked-table and function policies; ordinary bare and simple quoted identifiers remain supported.
+- Preserve blocked-table visibility after subqueries and parenthesized JOIN predicates, including quoted aliases, across supported SQL dialects.
+
 ## [2.0.0.beta3] - 2026-09-18
 
 ### Added
@@ -2303,6 +2361,25 @@ derive unit identifiers, which changes the index format's observable contract.
 - Update Inspector transitive dependencies `fast-uri` and `qs` to patched versions
   and audit the pinned Node dependency tree in CI.
 
+## [1.6.2] - 2026-09-18
+
+### Fixed
+
+- Refresh encrypted Rails credentials from disk when rebuilding the Console credential index, update every live scanner, and preserve the last valid index if refresh fails. Each response uses one consistent index snapshot.
+Keep credential scanner refresh snapshots limited to live weakly referenced
+scanners on older Ruby versions, avoiding unsafe receiver access after garbage
+collection while preserving updates to every live Console server.
+Keep JSON on `>= 2.19.9, < 3` so supported Rails encoders can serialize metadata after a fresh bundle resolution; JSON 3 removes their `quirks_mode` option. Bound MessagePack below 2 and Railties below 9, retaining their existing minimum versions and the strict package-build gate.
+- Preserve version-aware missing-tool guidance with MCP 0.23 by installing its dispatch override before the SDK captures request handlers.
+
+### Build
+
+- Add a no-publish, one-off 1.6.2 maintenance preparation flow and installed-package CI. Disable the legacy automatic publisher; publication requires the trusted main maintenance profile and its reviewed candidate SHA.
+
+### Security
+
+- Require MCP 0.23.0 or newer within the 0.x line for upstream transport security fixes; run `bundle update woods mcp` when upgrading. Ruby 3.0 remains supported. The newer SDK removes the old json-schema/addressable dependency chain. Existing Index and Console HTTP origin settings now reach the SDK Host/Origin guards; cross-origin browser access requires the actual configured port.
+
 ## [1.6.1] - 2026-07-22
 
 ### Fixed

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.beta4/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.beta4/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,58 @@ 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 the release information below and confirm it on [RubyGems](https://rubygems.org/gems/woods/versions). If only prereleases are available, use an exact prerelease pin; `~> 2.0` will not select one. Follow the chosen version's tag documentation rather than assuming every feature on `main` is published. If you choose 1.x, use its tag documentation instead of this quickstart.
+
+<details>
+<summary>Release information and Gemfile version constraints</summary>
+
+<!-- release-state:version-banner -->
+> **This tree documents version 2.0.0.** It is a major update from 1.x: read [what changed and how to upgrade](docs/UPGRADING_TO_2.md) before updating. The full history is in the [CHANGELOG](CHANGELOG.md).
+>
+> `main` is the development branch and can run ahead of the latest published gem. The gem badge above shows the latest published version; documentation for a published version lives on its tag.
+>
+> ### Version: this tree declares prerelease 2.0.0.beta4; `main` documents 2.0.0
+>
+> | Line | Version | Documentation |
+> |---|---|---|
+> | Documented here | **2.0.0**, unreleased | this README and the [documentation index](docs/README.md) |
+> | Declared prerelease | **2.0.0.beta4** | [the v2.0.0.beta4 tag](https://github.com/lost-in-the/woods/tree/v2.0.0.beta4) |
+> | Latest published gem | **1.6.2** | [the v1.6.2 tag](https://github.com/lost-in-the/woods/tree/v1.6.2) |
+>
+> RubyGems treats 2.0.0.beta4 as a prerelease, so `gem "woods", "~> 2.0"` does not resolve it. Once published, install it explicitly with `gem "woods", "2.0.0.beta4"`. The released constraint stays `gem "woods", "~> 1.6"`.
+<!-- release-state:end -->
+
+</details>
+
+Expand the release information above, then add its appropriate `gem "woods", …` declaration to your Gemfile's `:development` group and run:
 
 ```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 +87,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 +105,91 @@ 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.
-
-> **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 complete walkthrough, including expected output and first questions to ask, is in [Getting started](docs/GETTING_STARTED.md).
-
-## Let an agent install it
+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.
 
-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:
+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.
 
-```bash
-/plugin marketplace add lost-in-the/plugins
-/plugin install woods-plugin@lost-in-the-plugins
-```
+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).
 
-With any coding agent (no plugin needed), paste this into a session opened at your Rails app's root:
+## Retrieval: with or without embeddings
 
-```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.
-```
-
-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.
-
-## Choose your path
+Exact lookup, pattern search, and graph queries work immediately after extraction. For ranked retrieval through `codebase_retrieve`, choose a mode:
 
-| 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) |
-
-## Upgrading from 1.x
-
-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.
-
-## Optional Claude Code workflows
-
-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.
-
-## Two servers, two trust boundaries
-
-Woods ships two MCP servers. Most users only need the Index Server.
-
-| | Index Server | Console Server |
+| Mode | Setup | What it searches |
 |---|---|---|
-| 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.
+| **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 |
 
-## Optional semantic search
+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`.
 
-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:
-
-```bash
-ollama pull nomic-embed-text
-```
-
-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).
-
-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.
-
-```bash
-bin/rails woods:embed
-```
+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.
 
-Reconnect the Index Server after the first embed, then check `woods_status` before using `codebase_retrieve`.
+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.
 
 ## 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:
+Run a watcher alongside your development processes:
 
 ```bash
 bin/rails woods:watch
 ```
 
-Add it to your development process manager so it starts beside Rails:
+It catches up on changes, publishes complete generations, and lets the Index Server refresh on later tool calls. Use a process supervisor for changes that require the watcher to restart. Without a watcher, run `bin/rails woods:incremental` after edits or `bin/rails woods:extract` for a full rebuild.
 
-```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.**
+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).
 
-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:
+## Two servers, two trust boundaries
 
-```ruby
-step "Woods: refresh", "bin/rails woods:incremental"
-```
+| | Index Server | Console Server |
+|---|---|---|
+| 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 |
 
-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).
+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.
 
-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.
+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).
 
-## What gets indexed
+## What the index can and cannot establish
 
-Woods recognizes the Rails application as a connected system, including:
+- **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.
 
-- 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.
+Use Woods to locate and connect evidence, then confirm the relevant source and tests. The [agent guide](docs/AGENT_GUIDE.md) describes this workflow.
 
-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.
+## Let an agent install it
 
-## Security boundary
+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.
 
-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.
+Claude Code users can optionally install the companion workflows:
 
-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.
+```text
+/plugin marketplace add lost-in-the/plugins
+/plugin install woods-plugin@lost-in-the-plugins
+```
 
-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).