woods 2.0.0.beta1 → 2.0.0.beta3

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.beta1/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.beta3/AGENTS.md).
 <!-- release-state:end -->
 
 ## Choose the right channel
@@ -25,6 +25,8 @@ bin/rake spec
 bin/rubocop
 ```
 
+`Gemfile.lock` is gitignored, so a fresh worktree (as opposed to a clone) needs it copied in from an existing checkout before running any `bin/*` command.
+
 Create a branch from current `main`. Keep each pull request to one logical change and preserve unrelated formatting and refactors for separate work.
 
 `main` is the development branch: it holds work for the next release and can run ahead of the latest published gem. Releases are cut from version tags by the guarded workflow in the [release section below](#release-flow); documentation matching a published gem lives on that release's tag.
@@ -44,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.beta1/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.beta3/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
 <!-- release-state:end -->
 
 ### Agent orientation and static self-map
@@ -94,7 +96,25 @@ bin/rubocop
 
 Before requesting review, run the full unit suite and style check unless the PR explains why one cannot run.
 
-Coverage from the default process excludes opt-in Rails, installed-artifact, and live-backend lanes. Report their results separately; a low percentage for subprocess-driven tasks does not establish that they are untested. CI enforces the aggregate line floor and measures branches, but does not enforce a branch floor. Add behavior-based regressions and real optional-gem fixtures for changed extraction paths before proposing higher thresholds.
+Coverage from the default process excludes opt-in Rails, installed-artifact, and live-backend lanes. Report their results separately; a low percentage for subprocess-driven tasks does not establish that they are untested. CI enforces a 90% aggregate line floor and measures branches, but does not enforce a branch floor. The line gate was calibrated against local and CI default-suite results on 2026-09-18; it does not establish per-file coverage or coverage across the opt-in lanes. Add behavior-based regressions and real optional-gem fixtures for changed extraction paths before proposing higher thresholds.
+
+### Pending examples in CI
+
+CI fails when a running example becomes unexpectedly pending, including `skip`,
+`xit`, and pending metadata. `spec/support/pending_policy.rb` records the exact
+file, full description, reason, and unavailable capability for each reviewed
+exception. Current exceptions cover the two optional tiktoken benchmarks, one
+optional Tokenizers example, two Ruby-before-3.2 regexp-timeout examples, one
+procfs example, and three filesystem-permission examples when running as root.
+The Linux CI unit jobs run the real procfs identity example as an unprivileged
+user, so the procfs and root exceptions normally apply only to other environments.
+Opt-in suites excluded by their documented environment gates are not pending
+examples. Focused runs do not need to include every reviewed exception.
+
+Adding a new skip requires review of both its exact entry and capability check;
+matching an existing reason alone is insufficient. Local runs retain normal
+RSpec pending behavior. Exercise the policy and matrix consistency checks with
+`CI=true bin/rspec spec/ci`.
 
 ### Rails version matrix
 
@@ -111,6 +131,44 @@ WOODS_RUN_BOOTED_APP=1 BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile \
   bin/rspec spec/integration/booted_extraction_spec.rb
 ```
 
+The unit suite evaluates every hand-maintained Rails gemfile and checks its
+Appraisal requirements, old-Rails compatibility pins, and CI matrix membership.
+This detects configuration drift; it does not replace the booted rows.
+
+### Exact runtime dependency floors
+
+The separate `minimum-dependencies` CI job runs on Ruby 3.0 with Bundler 2.5.23:
+
+```bash
+gem install bundler -v 2.5.23
+ruby script/test-minimum-dependencies
+```
+
+Run outside `bundle exec`. The harness builds and installs the candidate gem,
+resolves `gemfiles/minimum_runtime.gemfile` independently of the development
+bundle, and verifies every loaded Woods library comes from that installed gem.
+All five direct runtime dependencies are pinned to their advertised gemspec
+floors. Transitive dependencies are compatible solver selections, **not** a
+claim that every transitive version is minimal. CI retains the full resolved
+version/platform list, lockfile, candidate gem and SHA-256 under the
+`minimum-runtime-dependencies` artifact; local output defaults to
+`tmp/minimum-dependencies/`.
+
+The probe exercises lexical retrieval and typed lookup over a synthetic published
+index, MCP SDK dispatch, Prism parsing, and MessagePack snapshots. It also boots
+an actual Rails 6.0.0 API-style app, loads Woods tasks, and checks the real Rails
+middleware stack for disabled Console passthrough, authorized requests, missing
+and incorrect token refusal, and forbidden origins. Static serving is explicitly
+disabled: Rails 6.0.0's own Static middleware predates Ruby 3 keyword forwarding.
+This is a bounded Woods runtime-floor contract, not evidence that arbitrary
+Rails 6.0.0 applications boot on Ruby 3. The booted Rails matrix uses compatible
+patch releases and covers full extraction; enabled database-backed Console and
+optional storage/provider combinations remain in their separate lanes.
+
+The exact-floor job is required by release CI validation. Changing a runtime
+lower bound requires updating its explicit pin and retaining a successful
+installed-artifact run, rather than silently advancing a pin to make CI pass.
+
 When adding a Rails line, update `Appraisals`, the corresponding hand-maintained gemfile, and `.github/workflows/ci.yml`. For Rails below 7.1, copy an existing 6.x gemfile so its sqlite3 and concurrent-ruby compatibility pins are preserved.
 
 ### Live storage and SQL dialects
@@ -125,6 +183,36 @@ WOODS_RUN_LIVE_BACKENDS=1 BUNDLE_GEMFILE=gemfiles/live_backends.gemfile \
 
 The lane expects reachable PostgreSQL/pgvector, MySQL, and Qdrant services. Configure endpoints with `WOODS_PG_URL`, `WOODS_MYSQL_URL`, and `WOODS_QDRANT_URL`. The Console contracts exercise blocked-table enforcement and legitimate SQL on both database dialects. New adapter behavior that depends on a real server belongs in this lane.
 
+### Solid Cache session compatibility
+
+The live-backend job runs `spec/integration/solid_cache_compatibility_spec.rb`
+against SQLite, PostgreSQL, and MySQL. MySQL coverage asserts that the adapter
+has no insert `RETURNING`, checks actual insert ownership (including same-value
+conflicts), exercises concurrent ownership, expiry, conditional deletion, and
+session clear/epoch recovery. A separate case strips only insert-result metadata
+to exercise the older Rails read-back fallback against real MySQL rows.
+
+Solid Cache coordination depends on private APIs. Before declaring a newly
+resolved `solid_cache` version supported:
+
+1. Record the exact Ruby, Active Record, Solid Cache, and database versions.
+2. Run the complete compatibility file against disposable PostgreSQL and MySQL
+   databases, with `WOODS_RUN_LIVE_BACKENDS=1`,
+   `BUNDLE_GEMFILE=gemfiles/live_backends.gemfile`, `WOODS_PG_URL`, and
+   `WOODS_MYSQL_URL` set. The suite recreates `solid_cache_entries`; never point
+   it at an application cache database.
+3. Require every example to pass, including SQLite local-cache bypass, TTL,
+   sharding, missing-private-API errors, and the MySQL ownership cases. Attach
+   the versions and results to the PR; a passing double-based unit suite is
+   insufficient.
+
+The live gemfile resolves `solid_cache ~> 1.0`; this is a dependency selection
+range, not evidence that every version in it has been tested. The baseline
+validated for #228 is Ruby 4.0.6, Solid Cache 1.0.10, Active Record 8.1.3.1,
+SQLite 3.53.2, PostgreSQL 16.15, and MySQL 26.7.0.
+Accepted crash/eviction limits are documented in the
+[configuration reference](docs/CONFIGURATION_REFERENCE.md#solid-cache-session-retention-and-compatibility).
+
 ## Keep public surfaces synchronized
 
 A pull request is incomplete when behavior and user guidance disagree.
@@ -191,8 +279,29 @@ RubyGems treats any letter in a version as a prerelease, so a `~> 1.6` or `~> 2.
 ### During feature work
 
 - Do not edit `lib/woods/version.rb` by hand.
-- Put changelog entries under `## [Unreleased]` only, beneath one of its `###` headings. Duplicate headings are merged at release time, in the order they first appear.
 - Leave the `release-state` fences alone. `release:prepare` rewrites them.
+- Put changelog entries under `## [Unreleased]`, beneath one of its `###` headings, or in an optional `changelog/<type>_<slug>.md` file. Entry files avoid conflicts between parallel branches; inline entries remain supported. Duplicate headings merge at release time, in the order they first appear.
+
+Entry files contain nonempty UTF-8 Markdown without ATX (`#`) or setext
+(underlined) headings, usually a bullet
+and indented continuation lines. For example, `changelog/fixed_watch-restart.md`
+can contain `- Preserve pending work across watch restarts.` Supported types are
+`added`, `build`, `changed`, `dependencies`, `documentation`, `fixed`,
+`performance`, `security`, `testing`, and `upgrade-notes`. Slugs start with a
+lowercase letter or digit and use lowercase letters, digits, hyphens, or
+underscores. Use one unique file per change; do not copy its entry into
+Unreleased as well. Keep entry files directly inside a real `changelog/`
+directory; symlinks and directories masquerading as entries are refused.
+Other file extensions are left untouched.
+
+`release:prepare` appends entry files in filename order after inline Unreleased
+entries, folds them through the same heading merger, and deletes exactly the
+consumed files. It validates every entry and documentation rewrite before
+changing any files; an invalid entry or a later refusal preserves all entries.
+A prepared release has an empty Unreleased section and no entry files. During
+an ordinary beta cycle, entry files may accumulate even with an empty Unreleased section while
+VERSION stays at the previous beta; the tag validator always rejects entry
+files at the candidate release SHA, regardless of inline notes or the version.
 
 ### Preparing a release
 
@@ -205,9 +314,9 @@ One command per transition. It never commits, tags, pushes, or publishes.
 | 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]"` |
 
-`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]` 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: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.
 
-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 refuses: there is nothing new to publish.
+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:
 
@@ -225,17 +334,123 @@ A release is pinned by its tag, never by a branch:
 
 | Step | Command | What guards it |
 |---|---|---|
-| Tag the merge commit | `git tag v<version> <merge-sha> && git push origin v<version>` (lightweight or annotated both work) | `script/validate-release` requires the tag to sit on `main` history, match `Woods::VERSION`, match the dated `CHANGELOG.md` heading, and not be an alpha |
-| Trigger the release workflow | `gh api --method POST repos/lost-in-the/woods/dispatches -f event_type=release -F 'client_payload[tag]=v<version>' -F 'client_payload[ci_run_id]=<id>'` where `<id>` is the green CI run on the tagged SHA (requires Contents write) | `.github/workflows/release.yml` re-validates the named CI run through the API, verifies the artifact digest, and runs secret-free candidate package tests before publishing |
+| Tag the merge commit | `git tag v<version> <merge-sha> && git push origin v<version>` (lightweight or annotated both work) | `script/validate-release` requires the tag to sit on `main` history (or the explicitly approved maintenance history below), match `Woods::VERSION`, match the dated `CHANGELOG.md` heading, and not be an alpha |
+| Trigger the release workflow | `gh api --method POST repos/lost-in-the/woods/dispatches -f event_type=release -F 'client_payload[tag]=v<version>' -F 'client_payload[ci_run_id]=<id>'` where `<id>` is the green CI run the tag push itself started, the one whose branch column reads `v<version>`; main's run on the same commit is refused with `tested ref is main` (requires Contents write) | `.github/workflows/release.yml` re-validates the named CI run through the API, verifies the artifact digest, and runs secret-free candidate package tests before publishing |
 | Verify publication | `gem info woods --remote` shows the new version; for a prerelease, `gem info woods --remote --prerelease`. The README gem badge updates on its own | just before pushing, the workflow re-runs `script/verify-release-tag` so a tag that moved since validation aborts the publish |
 
 Nothing is published from a laptop: the workflow builds and pushes the gem from the validated CI artifact, so the bytes on RubyGems are the bytes CI tested. `rake release` and `rake release:rubygem_push`, which `bundler/gem_tasks` installs, are blocked for that reason.
 
 After a final release publishes, reopen development with `release:reopen` in a follow-up pull request.
 
+### When a dispatch fails
+
+`release-context` and `publish` both check out `github.sha`, the default
+branch's tip at dispatch time, not the tag: `release-context` re-validates the
+named CI run, checks the live `release` environment, and runs
+`script/validate-release`; `publish` runs `script/verify-release-tag` and
+pushes the downloaded artifact. Only `package-test` checks out
+`needs.release-context.outputs.release-sha`, the tag's own commit, because
+that is what CI actually built and tested. The gem bytes `publish` pushes were
+built by CI at `release-sha`; `publish` never rebuilds them.
+
+That split decides the fix for a failed dispatch:
+
+| What failed | Lives in | Fix |
+|---|---|---|
+| `script/validate-release-run`, `script/validate-release`, `script/verify-release-tag`, or the workflow files themselves | main, read at `github.sha` | merge the fix to main, then re-dispatch at the same tag; the tag never moves |
+| Live `release` environment settings (protection rule, admin bypass) | GitHub environment configuration, not the tree | fix the setting directly; no commit or re-dispatch needed |
+| Anything under `spec/` or `lib/` that `package-test` actually runs against the candidate | the tagged commit, read at `release-sha` | a main-only fix does not reach the candidate; merge it, then move the tag to the new main tip and get a fresh CI run on it |
+
+Both failure classes happened in the beta1 dispatch: a `REQUIRED_CI_JOBS`
+prefix left behind by a `ci.yml` job rename was a validator fix that needed
+only a merge and a re-dispatch; two `packaged_gem_spec.rb` smoke failures
+traced to hard-coded `2.0.0` literals needed the tag moved to the commit that
+fixed them, because the candidate job runs the spec file at the tag.
+
+**Moving a tag is acceptable only before publication.** Once `publish` has
+pushed the gem to RubyGems, the tag is the permanent, immutable record of what
+was published; move it before that point only, with
+`git tag -f v<version> <new-sha> && git push --force origin v<version>` run by
+the maintainer, followed by a fresh CI run on the new tag SHA before
+re-dispatching.
+
+### Publishing the GitHub Release entry
+
+The workflow deliberately creates no GitHub Release: the API cannot bind an
+existing tag to an expected commit atomically, so automating it would race the
+tag's own verification. Once `gem info woods --remote` (or `--remote
+--prerelease`) confirms publication, create the entry by hand:
+
+```bash
+gh release create v<version> --verify-tag --notes-file <file>            # release
+gh release create v<version> --verify-tag --prerelease --notes-file <file> # beta or rc
+```
+
+`--verify-tag` refuses if the tag is missing or moved. Write `<file>` as a
+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
+
+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`.
+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.
+
+`script/release_profile.rb` on trusted main owns this exact tag/branch/base and
+its required CI jobs. `MAINTENANCE_APPROVED_SHA` starts as `nil`: publication
+fails closed until a **separate reviewed main PR** pins the exact prepared
+maintenance commit. Neither a dispatch parameter nor candidate code can choose
+another profile, branch, base, SHA or weaker CI requirements. The SHA binds the
+whole reviewed candidate, including its CI definition and installed-package
+tests; review those files as release controls, not just their job names.
+
+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.
+   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
+   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
+   separate main PR. No pin means no maintenance release.
+5. Only after the pin merges, the maintainer may tag that exact commit and wait
+   for its tag-push CI run. Dispatch uses the ordinary tag/run-ID payload.
+   Every exact maintenance matrix row in the trusted profile must succeed;
+   missing, duplicated, skipped or failed rows refuse publication.
+
+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
+CI artifact ID/digest, and protected `release` environment approval. Both Ruby
+package-test rows install that same artifact and run the pinned v1-specific
+`maintenance_packaged_gem_spec.rb` outside the repository load path. The oldest
+Ruby maintenance row explicitly activates MCP 0.23.0, the reviewed security
+floor; the latest row resolves the candidate's supported SDK range. Candidate
+code still executes only in secret-free, read-only jobs. After environment
+approval, maintenance history/publication checks run again before requesting
+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.
+
 ### 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 only branch. There is no stable branch today.
+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.
 
 ### What coding agents may do
 

data/README.md

@@ -15,15 +15,15 @@
 >
 > `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.beta1 is published as a prerelease; `main` documents 2.0.0
+> ### 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.beta1** | [the v2.0.0.beta1 tag](https://github.com/lost-in-the/woods/tree/v2.0.0.beta1) |
+> | 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.beta1 as a prerelease, so `gem "woods", "~> 2.0"` does not resolve it. Install it explicitly with `gem "woods", "2.0.0.beta1"`. The released constraint stays `gem "woods", "~> 1.6"`.
+> 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 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.
@@ -62,6 +62,10 @@ The default setup provides structural code intelligence. It does not require an
 
 ### 1. Install Woods
 
+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.
+
 ```ruby
 # Gemfile
 group :development do

data/SECURITY.md

@@ -60,11 +60,12 @@ Woods runs inside your Rails application and has access to:
 - **Application source code**: extracted and written to the output directory as JSON
 - **Database schema**: column names, types, indexes, and foreign keys (no row data)
 - **Git metadata**: commit history, contributors, file change frequency
-- **Runtime state** (Console MCP Server only), live database queries within a rolled-back transaction
+- **Optional session traces**: session/trace identifiers, request paths and controller/action timelines when session tracing is configured
+- **Live database rows** (Console MCP Server), queries within a rolled-back transaction
 
 ### Output Directory
 
-Extracted data is written to `tmp/woods/` by default. This directory contains your application's source code and schema in structured JSON format. Treat it with the same sensitivity as your source code, do not expose it to untrusted parties.
+Extracted data is written to `tmp/woods/` by default. This directory contains your application's source code and schema in structured JSON format. Source literals, comments and configuration metadata may contain sensitive values. Treat the index with the same sensitivity as your source code; do not expose it to untrusted parties. Optional session stores can be configured under this directory and add request metadata that may be more sensitive than the source itself. Apply the [session tracing access and retention guidance](docs/CONFIGURATION_REFERENCE.md#session-tracer-options) to those stores too.
 
 ### Console Server
 
@@ -80,13 +81,15 @@ If extraction output leaks, what can an attacker do with it?
 
 **What the output contains.** Application source code (inlined concerns, callback-resolved behavior), database schema (column names, types, indexes, foreign keys), route tables, migration history, gem versions, and git metadata (commit history, contributor emails, file change frequency).
 
-**What the output does not contain.** No row-level data from your database. Woods extracts schema only. No environment variables, no `Rails.application.credentials`, no API keys, no session state, no request logs, no customer data.
+**Structural extraction boundaries.** Structural extraction collects schema rather than dumping live database rows, and does not intentionally collect environment variables or the Rails encrypted credential store. This is not a guarantee that output is free of secrets or customer information: extracted source can contain hardcoded values, comments or examples, and Index tools can return that source. Console redaction and export-specific scrubbing do not sanitize the structural index.
+
+**Optional session data.** When configured, session tracing records session/trace identifiers, request paths and controller/action timelines. Request paths and identifiers can contain sensitive user information. The configured session store controls where these records live; configured Index session tools can return them. Session storage and access need their own retention and authorization controls. Console MCP is a separate live-data boundary described above.
 
 | Leak scenario | Attacker gains | Attacker does not gain |
 |---|---|---|
-| `tmp/woods/` directory exfiltrated | Source code + schema equivalent to a git clone + `rails db:schema:dump` | Database rows, secrets, tokens, customer data |
-| MCP Index Server token leaked (HTTP transport) | Read-only query access to the extracted index, no write or execution paths | Shell access, database row data, secrets |
+| `tmp/woods/` directory exfiltrated | Source code, schema and metadata, including sensitive values present in source; session records if their store is configured here | No additional live database or shell access merely from possessing these files |
+| MCP Index Server token leaked (HTTP transport) | Access to published source/metadata and configured session tools, including sensitive content they contain | The packaged default does not boot Rails or provide live database queries or shell execution; custom tool wiring has its own access boundary |
 | Notion sync database compromised | Model and column summaries synced to Notion | Anything not mirrored, source code stays local |
-| Console MCP Server exposed (dev/staging) | Read-only database access through a rolled-back transaction, bounded by TableGate + Redactor + SqlValidator | Write access (rolled back), full credentials (redacted), blocked tables |
+| Console MCP Server exposed (dev/staging) | Live database access constrained by TableGate, credential scanning, Redactor and SqlValidator; this remains admin-trust access | Supported packaged modes expose no write or eval tools; rollback and redaction have the limits described in the Console guide |
 
 **Mitigation.** Treat `tmp/woods/` as source-equivalent, keep it out of world-readable directories and public container images. Rotate `WOODS_MCP_HTTP_TOKEN` on compromise. Keep `console_mcp_enabled = false` in production regardless of environment, since the console layers are defense-in-depth and not primary controls.

data/docs/AGENT_GUIDE.md

@@ -2,6 +2,14 @@
 
 This guide is for coding agents using an already connected Woods MCP server. Woods is evidence from the running Rails application and its extracted graph; it complements file search, tests, git history, and direct source inspection.
 
+Supporting servers also send a concise version of this workflow in MCP
+initialization/discovery instructions, without requiring an installed plugin.
+Check the connected server's version and registered tools; this feature is
+unreleased after `2.0.0.beta2`, and protocol `2024-11-05` omits the field.
+The [initialization contract](MCP_SERVERS.md#initialization-guidance) describes
+availability. This guide remains the detailed reference when instructions are
+absent or the client does not display them.
+
 ## Start every session with status
 
 Call `woods_status` before relying on the index. Check:
@@ -13,6 +21,11 @@ Call `woods_status` before relying on the index. Check:
 
 If status is unhealthy, report the evidence and ask the owner to extract or refresh. Do not fill gaps by asserting that Woods found nothing.
 
+Compare `index.woods_version` (last manifest publisher, unknown for older indexes)
+with `server.version` (the MCP reader). A major-version difference warrants a
+full extraction and upgrade review; a match does not prove every retained unit
+was rewritten. See [manifest writer provenance](PUBLISHED_INDEX.md#manifest-writer-provenance).
+
 ## The default query loop
 
 Use this four-step loop for most codebase questions:
@@ -103,22 +116,48 @@ fields: ["identifier", "source_code", "metadata"]
 
 Start with identifier search. Add source or metadata only when name discovery fails. Restrict types and keep result limits small enough to inspect.
 
+On supporting versions, read `completeness` before calling search exhaustive.
+`result_count` counts returned rows. `result_limit` proves one more match exists;
+`scan_budget` and `regex_timeout` leave that unknown. Only `exhausted` establishes
+an exact total within the requested index/query domain. Narrow types, literal
+prefix/suffix filters, or deep fields when `partial` is true. A detected artifact
+failure remains an error with unknown completeness, never proof of no matches.
+
+This metadata is unreleased after `2.0.0.beta2`; older servers may omit it.
+Do not infer completeness from a full page or missing metadata. See the
+[search response contract](MCP_SERVERS.md#search-completeness).
+
 ## Traverse deliberately
 
 `dependencies` means “what this unit uses.” `dependents` means “what uses this unit.” Both default to bounded breadth-first traversal and accept type or relationship filters.
 
 Start at depth 1 or 2. A deeper unfiltered traversal can obscure the direct evidence that matters. Common relationship values include associations (`belongs_to`, `has_many`, `has_one`), code references, renders, redirects, form actions, and navigation links.
 
-Both return at most 50 nodes and say so with a `Showing N of M (truncated)`
+Both return at most 50 nodes by default and say so with a `Showing N of M (truncated)`
 line. Narrow with `depth`, `types` and `via` before paging with `limit` and
 `offset`: narrowing answers the question, paging only splits the same answer
 across turns. In a multi-database app each row names the unit's database.
 
-Use returned relationship labels as evidence. Do not infer call order from a dependency edge alone.
+A traversal can also stop at its independent node or edge budget. Treat
+`partial`/`partial_reason` as incomplete graph evidence even on the final page;
+paging cannot recover nodes the walk never reached. Check the connected schema
+before using `max_nodes`/`max_edges`, and follow the
+[budget contract](MCP_SERVERS.md#dependency-traversal-budgets).
 
-## Use semantic retrieval only when ready
+When the connected schema supports `explain`, request `explain: true` to see
+recorded source-to-target relationships and a shared shortest witness to each
+row. Report `direct` relationships separately from `transitive` inferred impact.
+Follow `parent`/`edge_id` references; `context: true` ancestors are outside the
+current result page. Unknown labels and ambiguous candidate types stay unknown;
+`typed_path_complete: false` does not establish a uniquely typed path. See the
+[explanation contract](MCP_SERVERS.md#traversal-explanations).
 
-`codebase_retrieve` answers natural-language questions with token-budgeted context. Use it when `woods_status` reports a configured embedding provider and current vector data.
+Use recorded relationship labels as evidence. Do not infer execution or call
+order from a dependency edge alone.
+
+## Use ranked retrieval only when ready
+
+`codebase_retrieve` answers natural-language questions with token-budgeted context. Use it when `woods_status` reports explicit lexical mode over a current published index, or a configured embedding provider and current vector data in semantic mode. Lexical mode explains matching terms/fields and does not infer synonyms absent from the text; a no-match response is not proof of missing behavior.
 
 Important parameters:
 
@@ -202,3 +241,43 @@ Verification: <source/test/history checked or still needed>
 - [Extractor reference](EXTRACTOR_REFERENCE.md): indexed unit and edge contracts.
 - [Retrieval guide](RETRIEVAL_GUIDE.md): embeddings, ranking, and token budgets.
 - [Troubleshooting](TROUBLESHOOTING.md): stale indexes, disabled retrieval, and startup failures.
+
+### Explicit retrieval and discovery scope
+
+On a server whose tool schema advertises them, `packages` and `source_paths` narrow
+`search` and `codebase_retrieve` before candidate limits. These are per-call
+arguments, not configuration settings. Inspect applied scope and completeness;
+a narrow graph query can omit relevant cross-boundary dependencies. See the
+[scope contract](RETRIEVAL_GUIDE.md#explicit-package-and-source-path-scopes) for
+root/nested ownership, path normalization, errors, storage support, and cost.
+
+### Verify source content before relying on freshness
+
+When supported by the installed version, inspect `woods_status.index.source_freshness`.
+Repeated edits can leave the porcelain fingerprint unchanged. A quick-budget
+`unknown` can justify one explicit `source_check: "deep"` call; persistent unknown
+needs the reported limitation resolved, not repeated status polling. Use
+`bundle exec woods-extract full` to establish verified preboot source evidence.
+A named refresh does not certify unrelated consumers or external runtime state.
+Follow [source freshness](SOURCE_FRESHNESS.md) and keep ordinary query scopes narrow.
+
+### Recovering relevant code under a small context budget
+
+Check the installed schemas before requesting `evidence: 'compact'` on retrieval
+or lookup, or `evidence: 'outline'` for API orientation. These modes preserve
+complete selected spans and explicitly report omissions. An outline is not proof
+of implementation behavior. Follow the returned typed `full_evidence` call when
+you need full source; its SHA guard refuses changed source instead of validating
+a different publication accidentally. Published-unit line/byte ranges can include
+synthesized or commented concern source and are not physical file coordinates.
+See the [evidence contract](RETRIEVAL_GUIDE.md#compact-published-evidence-and-api-outlines).
+
+### Optional hook hints
+
+When explicitly enabled on a supporting installed gem, Claude hook context offers
+a small served-generation orientation and post-edit candidate dependents. Treat
+pre-refresh, unknown freshness, truncation and ambiguous identity labels as limits
+on the evidence. Verify direct and inferred downstream candidates using typed
+lookup and `dependents explain:true`; suggested tests do not prove coverage.
+Silence does not establish no impact. See [bounded context hints](WATCH_DAEMON.md#optional-bounded-context-hints)
+for opt-in, independent refresh controls, limits and repeat suppression.

data/docs/AGENT_SETUP.md

@@ -46,7 +46,15 @@ Do not infer permission to configure Console MCP from a request to “set up Woo
 
 ## 3. Install on a branch
 
-Create or switch to the branch requested by the repository owner. Add only the development dependency:
+Create or switch to the branch requested by the repository owner. Select the
+published version using the [installation guide](GETTING_STARTED.md#1-install-the-gem).
+Before stable 2.x is published, use the exact published prerelease constraint
+from the README release table; `~> 2.0` will not select a beta or release candidate.
+Use the selected version's tag documentation and verify its capabilities before
+configuring features described on `main`.
+
+Add only the development dependency. The following constraint applies **after a
+stable 2.x release is published**:
 
 ```ruby
 # Gemfile
@@ -120,6 +128,77 @@ For Docker, extraction runs inside the Rails container. If Woods is installed on
 
 Reconnect the client and call `woods_status`. Confirm a current generation and non-zero unit counts before claiming setup works.
 
+### Managed Claude Code configuration
+
+The development command `woods-agent-config` is unreleased after 2.0.0.beta2.
+Check `bundle exec woods-agent-config --help` in the selected application bundle;
+use the manual client configuration below when it is absent. The supported
+client format is Claude Code (tested with 2.1.267).
+
+Create a private plan, inspect its paths and diff, then apply that same plan:
+
+```bash
+bundle exec woods-agent-config setup --client claude --scope project \
+  --root "$PWD" --instructions CLAUDE.md,AGENTS.md --plan /tmp/woods-setup.json --diff
+bundle exec woods-agent-config apply /tmp/woods-setup.json \
+  --client claude --scope project --root "$PWD"
+```
+
+Choose a new, unused plan filename for each preview. Preview writes only the
+requested plan file; it does not edit managed configuration. Plans contain the
+complete replacement bytes, including unrelated settings, and use mode 0600:
+keep them private and remove them when no longer needed. `show FILE` prints its
+summary; `show FILE --diff` checks the original snapshots and prints a unified
+diff. Applying a changed snapshot fails rather than replacing the new content.
+A repeated identical setup makes no configuration edits.
+
+| Selection | Managed files |
+|---|---|
+| `--scope project` | `<root>/.mcp.json`, explicitly selected `<root>/CLAUDE.md` and/or `AGENTS.md`, `<root>/.woods-agent-config.json` ownership receipt |
+| `--scope user` | `~/.claude.json`, explicitly selected `~/.claude/CLAUDE.md`, application-specific receipt in `~/.claude/` |
+
+With `CLAUDE_CONFIG_DIR`, user scope uses that directory's `.claude.json`,
+`CLAUDE.md`, and receipt instead. Instruction edits are opt-in with
+`--instructions`; existing selections carry forward on update. The command
+configures the Index Server. Client trust and project approval remain Claude
+Code settings; apply does not change them.
+
+Preflight runs the selected installed bundle, validates its index, and checks
+its actual registered capabilities. It does not boot Rails or contact an
+embedding provider. The bundle must already resolve in frozen mode; prepare
+its lockfile separately if Bundler reports a mismatch. Host mode uses the
+application's absolute Gemfile and index paths. `--index tmp/woods` is relative
+to the selected root. For Compose, also select `--mode compose --service web
+--container-root /app`; run the configuration command where Docker Compose can
+access that project. Preflight verifies the index and installed gem inside that
+service. Both host and container subprocesses have time limits.
+
+Use `update --plan FILE` with the same client/scope/root and the desired launch
+options to change the owned entry or instruction selection. Update explicitly
+records the current template and installed-gem evidence; background hooks never
+update configuration. `remove --plan FILE` previews deletion of owned content
+and does not require the application bundle or index to remain available.
+Use `--name NAME` consistently if the installation uses a nondefault server name.
+Apply each operation's saved plan with the same explicit client/scope/root.
+
+Ownership comes from the receipt and exact managed section, not from a server
+named `woods`. Existing unowned names, edited managed content, malformed JSON,
+duplicate markers, symlinks, and concurrent edits cause conflicts. Preserve the
+receipt for future update/removal. Unrelated servers, hooks, settings,
+instruction text, permissions, and line-ending conventions are retained;
+changing JSON may reformat its whitespace.
+
+Writes use atomic replacement per file and a private recovery journal beside
+the receipt. The plan summary names the `.lock` and `.pending` runtime paths;
+a lock file may remain after completion. Multiple files are not one atomic
+transaction. An ordinary write failure restores original files when safe; an
+interruption or concurrent edit can retain the journal. Resolve reported
+conflicts, then use `recover --client claude --scope project --root "$PWD"`
+(or the original user scope). Recovery refuses to overwrite concurrent edits.
+Keep journals private because they contain original configuration bytes. A plan
+whose recovery journal would exceed 8 MiB is refused before any managed file
+is changed; reduce the selected configuration before applying.
+
 ## 7. Verify useful behavior
 
 Use a class known to exist in the application:
@@ -199,6 +278,8 @@ Never report a capability as enabled solely because its schema exists in source.
 
 ## Related guides
 
+- [Edit client adapters](CLIENT_HOOKS.md) for separately opt-in Claude/OpenCode edit hooks; MCP setup does not enable them.
+
 - [Getting started](GETTING_STARTED.md) for the human walkthrough.
 - [MCP servers](MCP_SERVERS.md) for client-specific configuration and server boundaries.
 - [Upgrade to Woods 2.0](UPGRADING_TO_2.md) for an existing 1.x installation.