woods 2.0.0.beta4 → 2.0.1

data/docs/TROUBLESHOOTING.md

@@ -23,7 +23,7 @@ This guide covers the most common problems encountered when installing, extracti
 | `No such container` | Wrong container name | Check with `docker ps --format '{{.Names}}'` |
 | `JSON parse errors` (MCP) | Rails boot noise on stdout | Remove `puts` calls from initializers |
 | Query timeout | Large table, no scope | Add scope conditions to narrow results |
-| `Extraction failed for …; the previous generation remains active` | A consumer handled a source error during incremental extraction or refresh (unreleased after `2.0.0.beta3`) | Fix the logged source error and retry the [complete batch](INCREMENTAL_EXTRACTION.md#handled-source-errors-and-retry); watch keeps it pending |
+| `Extraction failed for …; the previous generation remains active` | A consumer handled a source error during incremental extraction or refresh (included in Woods `2.0.0`) | Fix the logged source error and retry the [complete batch](INCREMENTAL_EXTRACTION.md#handled-source-errors-and-retry); watch keeps it pending |
 | Empty extraction output | `eager_load!` failure | Check for `NameError` in boot output |
 | Git metadata missing | Shallow clone in CI | Use `fetch-depth: 0` for complete history |
 | Parallel tool calls all fail | MCP client batches calls | Send calls sequentially, validate params first |
@@ -53,13 +53,44 @@ version. See [manifest writer provenance](PUBLISHED_INDEX.md#manifest-writer-pro
 
 If a tool call fails with **"Tool not found: … not available in the installed Woods v…"**, the client is asking for a tool a newer gem provides. Run `bundle update woods` and reconnect the MCP server, then retry.
 
+### Watcher startup or planned restart fails
+
+Managed `woods-watch` startup is **included in Woods `2.0.0`**; record the
+loaded version/path and revision, then verify executable and generator help.
+If changing an initializer stops every Foreman process, replace a bare
+`woods:watch` entry with the [managed setup](WATCH_DAEMON.md#managed-development-startup).
+
+Read launcher logs and `woods_status` supervision records separately from daemon
+liveness and index freshness. `retrying` means the last generation remains usable
+while boot is retried. A parked ownership/protocol conflict requires correcting
+the selected owner or installed command and restarting that owner; do not delete
+claim files or kill PIDs taken from status. No index-visible record exists before
+the first boot resolves the application's output directory.
+
+Unset `WOODS_WATCH_IDLE_TIMEOUT` in managed modes. If the boot deadline is reached,
+diagnose Bundler/initializer startup before increasing `--boot-timeout`; a valid
+long extraction has a separate readiness state and is not bounded by that clock.
+If setup created a Procfile but normal `bin/dev` still only launches Rails, choose
+Puma or explicitly run the selected Foreman command. The generator never rewrites
+`bin/dev` or starts services during preview.
+
+If installation reports a pending transaction, use `woods:watch --operation
+recover` through the Rails generator, initially with `--pretend`; see
+[owned setup recovery](WATCH_DAEMON.md#ownership-updates-and-removal). That Rails
+command boots the application first. For broken initializers use the documented
+direct bundled Ruby helper, which does not boot Rails or require task discovery.
+Both refuse to overwrite intervening edits. A Puma setup refusal for
+`config/puma/development.rb` means the default
+configuration would bypass the generated plugin; select an external/Foreman
+arrangement instead of installing an inactive directive.
+
 ### Semantic graph validation errors
 
 In development versions containing #413, `woods:validate` rejects graphs that
 parse as JSON but disagree with their indexes. Errors name the section and
 identity, for example `reverse["http_api"]: missing "Order"`, a duplicate typed
-variant, or an indexed unit absent from `nodes`. This is unreleased after
-`2.0.0.beta2`; check the installed gem before expecting these diagnostics.
+variant, or an indexed unit absent from `nodes`. This is included in Woods
+`2.0.0`; check the installed gem before expecting these diagnostics.
 
 Keep the failing generation and report the exact errors. Run a full extraction
 in a fresh application process with the intended bundle, then validate again.
@@ -88,7 +119,7 @@ Scoped resets leave corrupt state untouched. Valid state keeps any unrelated
 operation entries, and missing state remains a no-op without creating a file.
 A permission failure must be corrected before repair can succeed.
 
-This recovery is unreleased after `2.0.0.beta2`; check the installed version.
+This recovery is included in Woods `2.0.0`; check the installed version.
 Older versions report corrupt state as nothing to repair. Stop pipeline writers,
 back up the configured guard state's `pipeline_guard.json`, and remove only that
 file before restarting, or upgrade to a version containing the fix.
@@ -160,7 +191,12 @@ For subsequent runs, use incremental mode instead of full extraction:
 bundle exec rake woods:incremental
 ```
 
-Incremental extraction only re-extracts files that changed since the last run. It skips unchanged units and is typically 5-10× faster.
+Incremental extraction dispatches the selected changed paths, including affected
+concern consumers and whole-app extractors whose trigger paths changed. The default
+Git range is `HEAD~1`; pass an explicit range or `CHANGED_FILES` for other batches.
+It can reduce extraction work, but Rails boot, graph rebuilding, and publication
+still contribute to runtime. Measure the improvement in your application; Woods
+does not guarantee a speedup. See the [incremental contract](INCREMENTAL_EXTRACTION.md).
 
 ---
 
@@ -228,7 +264,7 @@ dependents after an incremental run.
 identities when restoring and updating the graph.
 
 **Fix:** Check whether the installed version includes B-193; this fix is
-unreleased. After upgrading to a version containing the fix, run
+included in Woods `2.0.0`. After upgrading to a version containing the fix, run
 `bundle exec rake woods:extract` once to rebuild lost reverse dependencies.
 Loading an already damaged graph does not restore discarded entries. See the
 [incremental graph contract](INCREMENTAL_EXTRACTION.md#the-contract).
@@ -239,7 +275,7 @@ Loading an already damaged graph does not restore discarded entries. See the
 most files as `change_frequency: new` in a shallow CI checkout.
 
 **Cause:** A shallow clone truncates HEAD ancestry. The shallow-checkout guard is
-unreleased after 2.0.0.beta2: current source omits git enrichment and warns once,
+included in Woods `2.0.0`: Woods omits git enrichment and warns once,
 rather than treating the truncated history as complete. If repository depth
 cannot be verified, enrichment is also omitted; check git access and version.
 
@@ -256,12 +292,33 @@ clone), then run full extraction to replace retained metadata:
 Two commits can suffice for an incremental diff, but do not establish the full
 ancestry needed for churn metadata.
 
+### Git executable is missing from the extraction environment
+
+**Symptom:** Extraction logs `Git history unavailable: git executable was not
+found in PATH`, and newly extracted units have no `metadata.git`. Older builds
+can omit this enrichment silently when the executable is missing.
+
+**Fix:** Run `git --version` in the same container and environment that runs
+extraction. Install Git 2.31 or newer there, ensure its executable is on `PATH`,
+then run full `woods:extract` to refresh every unit's history. A working Git
+installation on the host does not provide Git inside an application container.
+
+Extraction continues without inventing zero-commit history. The warning appears
+once per extractor instance when the application has a `.git` entry or an
+explicit `WOODS_GIT_DIR`/`GIT_DIR` setting. A source archive with neither remains
+supported and quiet. `GIT_BRANCH`/`GIT_SHA` provenance fallback is unchanged;
+those values identify a build but cannot supply per-file history.
+
+This diagnostic is emitted during extraction. `woods_status.ready` and a
+manifest Git SHA do not establish that per-unit history was available, and
+`recent_changes` returning no results does not prove no files changed.
+
 ---
 
 ### Git enrichment warns that history could not be read completely
 
-Current source uses an explicit merge-diff mode requiring **Git 2.31 or newer**.
-This is unreleased after 2.0.0.beta2: first confirm the installed Woods version.
+Woods 2.0 uses an explicit merge-diff mode requiring **Git 2.31 or newer**.
+First confirm the installed Woods version.
 Check `git --version` inside the same container/process environment as extraction,
 and upgrade git if it is older. On a supported version, check that the application's
 `HEAD` and object store can be read using the same `WOODS_GIT_DIR` setting.
@@ -293,29 +350,62 @@ When it does not, the git keys are omitted from every unit, provenance records
 `"unknown"`, and one warning names git's own reason. Absent keys mean "not
 known"; they never mean "brand new".
 
-**Fix:** Point `WOODS_GIT_DIR` at the *canonical* git directory, the one the
-worktree's `gitdir:` pointer ultimately leads to, and make sure it is mounted:
+**Fix:** Restore access to both the worktree-specific Git directory and the
+shared objects and refs using the mount layouts below, then run a full
+`woods:extract` to replace retained metadata.
+
+### Git directory mounts for linked worktrees
+
+`WOODS_GIT_DIR` is passed directly to Git's `--git-dir`. It selects that
+directory's `HEAD` for manifest provenance, per-file history, and incremental
+diff ranges. **For a linked worktree, pointing it at the shared `.git` root
+selects the primary checkout's HEAD.** A successful Git command alone does
+not prove Woods is reading the intended branch.
+
+First inspect Git metadata on the host, from the intended worktree:
 
 ```bash
-# docker-compose.yml, mounting the parent repository's git directory
-#   volumes:
-#     - /path/to/repo/.git:/canonical-git:ro
-WOODS_GIT_DIR=/canonical-git bundle exec rake woods:extract
+git -C /path/to/worktree rev-parse --absolute-git-dir
+# Example: /path/to/repo/.git/worktrees/wt
+git -C /path/to/worktree rev-parse --path-format=absolute --git-common-dir
+# Example: /path/to/repo/.git
+git -C /path/to/worktree rev-parse --abbrev-ref HEAD
+git -C /path/to/worktree rev-parse HEAD
 ```
 
-`WOODS_GIT_DIR` wins over whatever the worktree pointer says, and applies to
-every git call Woods makes: per-unit enrichment, `manifest.json` provenance,
-and the diff range `woods:incremental` resolves. All three run through
-`Woods::GitCommand.argv`, so the override cannot reach two of them and miss the
-third.
+The worktree ID in this example is `wt`. Use the ID returned by Git metadata;
+it need not match the branch name. Choose one of these layouts:
+
+- **Same-path mount:** mount the complete shared directory read-only at its
+  original absolute path (`/path/to/repo/.git:/path/to/repo/.git:ro`). With the
+  application's existing `.git` pointer resolvable, leave `WOODS_GIT_DIR`
+  unset and remove conflicting Git-directory overrides from the environment.
+- **Relocated mount:** mount that complete directory read-only at a new path
+  (`/path/to/repo/.git:/mounted-common:ro`), including `objects`, `refs`, and
+  `worktrees`. Select the worktree-specific directory inside it:
+
+  ```bash
+  WOODS_GIT_DIR=/mounted-common/worktrees/wt bundle exec rake woods:extract
+  ```
+
+Mounting only the private worktree directory can leave its `commondir` pointer
+without access to shared objects and refs. Git's own environment variables are
+inherited by the subprocess; check any existing `GIT_DIR` and `GIT_COMMON_DIR`
+settings when diagnosing the effective layout. The complete layouts above
+preserve both worktree identity and shared storage.
+
+In the extraction container, verify the relocated selection against the host
+branch and exact SHA before extracting (replace `/app` and `wt` as needed):
+
+```bash
+git --git-dir=/mounted-common/worktrees/wt --work-tree=/app -C /app rev-parse --abbrev-ref HEAD
+git --git-dir=/mounted-common/worktrees/wt --work-tree=/app -C /app rev-parse HEAD
+```
 
-**`GIT_DIR` alone is not enough for a linked worktree.** Woods honors git's own
-`GIT_DIR` and `GIT_COMMON_DIR` because git does, but setting `GIT_DIR` to a
-worktree's private git directory only moves the failure: the `commondir`
-pointer inside it is relative, so it still resolves to a path that is not
-mounted, and `GIT_COMMON_DIR` does not override it. Either mount the canonical
-git directory at the same absolute path the pointer names, or use
-`WOODS_GIT_DIR`.
+After fixing the selection, run full `woods:extract` and verify the published
+manifest. Incremental extraction can retain older per-file Git metadata.
+A commit alone does not necessarily trigger the source-file watcher; run a
+full extraction when current history and provenance are required.
 
 ---
 
@@ -375,17 +465,23 @@ retries after a later filesystem event.
 
 ### `manifest.json` shows the wrong branch (or `git_branch: "unknown"`) in a worktree
 
-**Symptom:** `git_branch` / `git_sha` in `manifest.json` name a different branch than the worktree is actually on, or report `"unknown"`. The extracted units themselves are correct, only the provenance metadata is off.
+**Symptom:** `git_branch` / `git_sha` in `manifest.json` name a different
+branch or SHA than the intended worktree, or report `"unknown"`.
 
-**Cause:** In a linked git worktree, `.git` is a *file* containing a `gitdir:` pointer to the real git directory, often an absolute host path. When extraction runs where that path can't be resolved (e.g. inside a container where the host path isn't mounted), git can't read the ref. Woods now reports `"unknown"` in that case rather than emitting a stale, misleading value (previously it fell back to a baked `GIT_BRANCH`/`GIT_SHA` build arg).
+**Cause:** An unreachable `.git` file's `gitdir:` pointer prevents Git from
+resolving the worktree's HEAD. An override selecting the shared `.git` root
+instead resolves the primary checkout's HEAD successfully. That wrong selection
+also affects per-file history and HEAD-based incremental ranges.
 
-**Fix:** Make the worktree's git directory reachable from the extraction environment, for example, mount the parent repository (the directory the `gitdir:` pointer references) into the container, or run extraction from a normal (non-worktree) checkout. With the real git directory reachable, `git_branch`/`git_sha` resolve correctly. If the checkout legitimately ships without a `.git` at all (a source tarball, or a Docker `COPY` that excludes it), set `GIT_BRANCH` / `GIT_SHA` explicitly. Woods honors these when there is no `.git` at the root (or no git binary), but suppresses them when a `.git` *is* present but unresolvable (so a stale build arg can't mask a worktree).
+**Fix:** Follow [Git directory mounts for linked worktrees](#git-directory-mounts-for-linked-worktrees),
+compare the selected branch and exact SHA in the extraction environment, then
+run a full extraction. Compare the newly published manifest, not a retained
+generation. A commit without a source edit may leave the watcher idle.
 
-When the canonical git directory is mounted but not at the path the pointer
-names, set `WOODS_GIT_DIR` to where it actually is. It wins over the pointer for
-provenance and for unit-level git metadata both. Setting git's own `GIT_DIR` to
-the worktree's private git directory does not work: its `commondir` pointer is
-relative and resolves outside the mount.
+For a checkout legitimately shipped without `.git` (such as a source tarball),
+`GIT_BRANCH` / `GIT_SHA` can supply provenance. They are fallbacks only when
+`.git` is absent or Git is unavailable; a present but unresolvable `.git`
+reports `"unknown"` instead of substituting stale build arguments.
 
 ---
 
@@ -395,9 +491,9 @@ relative and resolves outside the mount.
 
 ### Index cannot be resolved at startup
 
-**Symptom:** An Index MCP executable exits with `Could not resolve a published Woods index in: /path/to/...` even though extraction completed. This headline is unreleased after `2.0.0.beta3`; older versions say `No manifest.json found`. Both mean the selected index could not resolve its manifest, not that an atomic index needs a root manifest.
+**Symptom:** An Index MCP executable exits with `Could not resolve a published Woods index in: /path/to/...` even though extraction completed. This headline is included in Woods `2.0.0`; older versions say `No manifest.json found`. Both mean the selected index could not resolve its manifest, not that an atomic index needs a root manifest.
 
-Embedded Index MCP startup through `IndexReader` also raises an `ArgumentError` with the selected directory and layout guidance when the marker cannot resolve a manifest, including malformed marker shapes such as `[]` or a numeric `payload` (unreleased after `2.0.0.beta3`). Earlier builds may expose a raw `TypeError` or `NoMethodError` for those shapes. Inspect the marker and preserve the failing index before attempting recovery.
+Embedded Index MCP startup through `IndexReader` also raises an `ArgumentError` with the selected directory and layout guidance when the marker cannot resolve a manifest, including malformed marker shapes such as `[]` or a numeric `payload` (included in Woods `2.0.0`). Earlier builds may expose a raw `TypeError` or `NoMethodError` for those shapes. Inspect the marker and preserve the failing index before attempting recovery.
 
 **Cause:** The selected directory is not the published index root, the published generation cannot be resolved, or the path is not visible to the MCP process. A container path is appropriate for a container process; a host process needs the host-visible path.
 

data/docs/UPGRADING_TO_2.md

@@ -2,14 +2,41 @@
 
 Woods 2.0 changes observable index identifiers, publication layout, vector-store reconciliation, and the supported MCP surface. Plan a clean re-index. Do not upgrade a shared or durable index in place without a backup and a rollback window.
 
-This guide assumes the last v1 release, 1.6.1, and targets 2.0.0.
+This guide covers the supported 1.6.x line and targets 2.0.0. Use the latest
+published 1.6.x security patch as the rollback version.
 
 <!-- release-state:upgrade-availability -->
-> This tree declares 2.0.0.beta4 as a prerelease. After RubyGems lists it, pin it with
-> `gem "woods", "2.0.0.beta4"`; `~> 2.0` resolves only once
-> 2.0.0 is published.
 <!-- release-state:end -->
 
+## 2.0.1 security maintenance update
+
+This maintenance line adds Console request/output policy corrections and isolates
+retrieval contexts between retriever instances. It does not add the graph or
+extraction features under development for 2.1. Confirm the installed package
+version and use its matching tag documentation.
+
+No index or database schema migration is required. Restart Console/MCP processes
+after upgrading. Explicit malformed HTTP origin entries now fail at boot with the
+offending entry named; fix the entry rather than weakening authentication.
+Automatic and manual Console mounts raise `Woods::ConfigurationError` for these
+settings, including invalidly encoded entries. With
+no allowlist configured, the existing loopback defaults remain unchanged. See
+[HTTP origin matching](MCP_HTTP_TRANSPORT.md#browser-origins-dns-rebinding-defense).
+
+Raw `console_sql` now refuses ambiguous protected results and genuinely unknown
+adapter families. PostgreSQL-subclass adapters retain PostgreSQL handling;
+structured Console tools remain available with other adapters. Prefer explicit
+unaliased scalar projections or structured reads when a query is refused.
+[Console setup](CONSOLE_MCP_SETUP.md#maintenance-policy-corrections) describes the
+compatibility boundary. Context caches refill after restart; retired entries
+follow the configured TTL or backend eviction. See
+[retrieval cache options](CONFIGURATION_REFERENCE.md#retrieval-cache-options).
+Rolling back restores the affected behavior.
+
+Polymorphic `belongs_to` association counts remain unsupported in 2.0.1 and
+1.6.4 and return a generic execution error; the 2.1 functional correction is
+not backported.
+
 ## Upgrade outcome
 
 After this runbook you will have:
@@ -21,6 +48,37 @@ After this runbook you will have:
 - an MCP client connected to the v2 packaged tool surface;
 - a documented way back to v1 if verification fails.
 
+### Console read compatibility
+
+For supporting security-patch revisions, any nonempty column or EAV redaction
+policy makes `console_sql` refuse relation and CTE column alias lists, including
+lists on base tables, derived tables, parenthesized `VALUES` sources and table
+functions, regardless of the selected names. Use explicit, unaliased protected
+columns or structured tools.
+Typed EAV lookup includes all registered models with a case-insensitive matching
+final table name, including across schemas. It can therefore mask extra values;
+qualification does not narrow this conservative type set. Sensitive key values
+still require their exact stored or cast spelling.
+
+The 1.6.x function denylist becomes a read-only function allowlist in 2.x.
+Supply one `console_query` expression per `select` array entry: 2.x refuses
+comma-combined entries that 1.6.4 splits. Raw SQL requires a recognized adapter
+family; structured tools remain available on other adapters. Configure binary
+secret columns explicitly for redaction. See the canonical
+[read policy compatibility](CONSOLE_MCP_SETUP.md#read-policy-compatibility) and
+[statement timeouts](CONSOLE_MCP_SETUP.md#statement-timeout) for limits.
+
+Supporting Console HTTP revisions deliberately permit allowlisted non-loopback
+Hosts through the SDK where 2.0.0 could refuse them. Bearer authentication remains
+required. An explicit origin list replaces browser-origin defaults; wildcards
+are not supported. Ruby-configured 2.x origins reject surrounding whitespace
+that 1.6.4 trims; the HTTP executable trims comma-separated environment entries
+on both lines. Review [HTTP origin configuration](MCP_HTTP_TRANSPORT.md#origin-configuration-compatibility).
+
+Context-cache namespace rotation retires entries for normal TTL or backend
+eviction; disabling both can retain them indefinitely. See
+[retrieval cache options](CONFIGURATION_REFERENCE.md#retrieval-cache-options).
+
 ## What changes
 
 | v2 change | What can break | Required response |
@@ -95,7 +153,11 @@ Also back up managed Obsidian/Unblocked destinations before allowing a mass stal
 
 ### 3. Choose a rollback point
 
-Keep the v1 Gemfile/lockfile commit and all durable-store backups until v2 extraction, MCP calls, retrieval, and exports are verified. Downgrading the gem does not translate v2 identifiers back to v1.
+Record and test a Gemfile/lockfile selecting the latest published 1.6.x security
+patch as the rollback bundle. If the current installation is older, verify that
+patched v1 bundle before beginning the v2 migration. Keep its commit and all
+durable-store backups until v2 extraction, MCP calls, retrieval, and exports are
+verified. Downgrading the gem does not translate v2 identifiers back to v1.
 
 ## Upgrade the application
 
@@ -142,7 +204,7 @@ bin/rails woods:validate
 bin/rails woods:stats
 ```
 
-Unreleased after `2.0.0.beta3`: `woods:clean` removes index artifacts but keeps
+Included in Woods `2.0.0`: `woods:clean` removes index artifacts but keeps
 the output directory and its hidden extraction guard. This stable guard lets
 concurrent writers coordinate safely; its presence does not mean an index remains.
 
@@ -331,7 +393,7 @@ Complete every applicable check:
 If verification fails:
 
 1. stop v2 MCP, watcher, embedding, and exporter processes;
-2. restore the v1 Gemfile and lockfile or deploy the recorded v1 commit;
+2. restore the tested, patched v1 Gemfile and lockfile or deploy its recorded commit;
 3. run the v1 `woods:clean` before restoring anything under the configured output directory;
 4. either restore the complete pre-upgrade v1 output-directory backup, or run a fresh v1 extraction and then restore its v1 `dumps/` and configuration artifacts;
 5. restore external vector-store and managed export backups when v2 modified them;

data/docs/WATCH_DAEMON.md

@@ -34,15 +34,160 @@ Ctrl-C to stop.
 | `WOODS_WATCH_CATCH_UP` | `1` | `0` skips the startup reconciliation |
 | `WOODS_WATCH_TRUST_FOREIGN_HOST` | unset | `1` lets a reader trust a fresh foreign-host heartbeat without checking its pid locally; see [cross-host liveness](#cross-host-liveness) |
 
-Run it under a supervisor. When boot-captured configuration changes the daemon
-exits `75` (`EX_TEMPFAIL`) on purpose, see [Restart triggers](#restart-triggers).
+The raw task needs a supervisor that restarts it after exit `75` (`EX_TEMPFAIL`);
+see [Restart triggers](#restart-triggers). Docker restart policies can supply
+this. A bare task in Foreman cannot: Foreman shuts down its process group when a
+child exits. Use the managed launcher below for native Procfile development.
 
-```yaml
-# Procfile.dev
-web:   bin/rails server
-woods: bundle exec rake woods:watch
+### Managed development startup
+
+**Included in Woods `2.0.0` ([#538](https://github.com/lost-in-the/woods/issues/538)).**
+Record the installed gem path and Git revision as well as VERSION; a checkout
+can have new behavior with the last beta's version. Verify both commands before
+using the new setup:
+
+```bash
+bundle exec woods-watch --help
+bin/rails generate woods:watch --help
+```
+
+Choose one lifecycle owner per application index:
+
+| Existing development workflow | Setup |
+|---|---|
+| Rails/Puma, including a `bin/dev` that just starts Rails | Opt-in `puma` mode; the development Puma master starts one separate extraction process, regardless of worker count. |
+| An existing Foreman workflow | `procfile` mode with the exact existing Procfile and selected normal Foreman command. |
+| Docker Compose, Grove, or another supervisor | `external` mode returns the raw task command; configure its lifecycle through the existing supervisor. |
+
+For Puma, preview before applying:
+
+```bash
+bin/rails generate woods:watch --mode puma --pretend
+bin/rails generate woods:watch --mode puma
+```
+
+This adds an executable `bin/woods-watch` and an owned directive to
+`config/puma.rb`. The directive loads the plugin only when the active Woods gem
+contains it. An absent gem or an older version without the plugin leaves Puma
+running without a watcher; this also works for Git/path bundles. The adapter
+separately enforces Puma's finalized development environment.
+Starting a console, task, or production
+Puma does not start a watcher. The watcher still uses another Rails process and its associated memory.
+Puma installation checks the application's installed Puma version (supported
+majors: 6, 7, and 8 on native Unix Ruby) and selects the normal `bin/rails server`
+path using `config/puma.rb`. If `config/puma/development.rb` exists, setup refuses
+because Puma would choose it first. Custom `-C` configurations need an explicit
+external/Foreman arrangement; this generator does not discover or rewrite them.
+
+For an existing Foreman arrangement, select the command you will actually use:
+
+```bash
+bin/rails generate woods:watch --mode procfile --procfile Procfile.dev \
+  --manager-command 'foreman start -f Procfile.dev' --pretend
+```
+
+Repeat without `--pretend` to apply. Preflight checks task discovery and Foreman
+availability with bounded commands; it does not start services. Installation
+preserves `bin/dev` and every unowned service. If `bin/dev` only runs Rails, it
+will still only run Rails: choose Puma mode or explicitly use the selected
+Foreman command. No process-manager gem is installed automatically.
+
+Run setup with the same application environment as normal startup. Preflight
+preserves environment-based Bundler configuration, including `BUNDLE_PATH`,
+`BUNDLE_APP_CONFIG`, and excluded groups, while resetting inherited activation
+state and requesting frozen resolution. Earlier Git builds of this
+installer dropped those settings ([#540](https://github.com/lost-in-the/woods/issues/540)).
+If normal task discovery works but installer preflight cannot find Rails or an
+installed dependency, check the loaded revision and bundle environment before
+reinstalling gems or adding a persistent `.bundle/config` workaround.
+
+Installer refusals return a nonzero exit status with their diagnostic (#544,
+included in Woods `2.0.0`). Earlier Git builds printed the refusal but exited
+successfully, so automation using those builds must also check the diagnostic and
+whether installation actually applied.
+
+Use `--child-command 'bundle exec rails woods:watch'` when that is the
+application's actual Rails entrypoint. Command strings become explicit argument
+vectors; shell pipelines, variable expansion, and shell setup scripts are not
+supported. Do not prepend an `environment` task or an already booted Rails runner.
+
+### Ownership, updates, and removal
+
+The generator records relative owned paths and fingerprints in `.woods-watch.json`.
+Commit it with the generated configuration so a new clone/worktree can update or
+remove that setup. Runtime transaction state stays under `tmp/woods-watch-install/`;
+keep that directory ignored. Changes to owned content or executable permissions
+cause a conflict rather than an overwrite. Review the conflict and restore or
+adapt the owned setup explicitly; do not delete the receipt to force an overwrite.
+
+```bash
+# Change modes or update owned setup (include the selected mode's options).
+bin/rails generate woods:watch --operation update --mode puma --pretend
+# Remove owned startup fragments and wrapper; preserve application edits.
+bin/rails generate woods:watch --operation remove --pretend
 ```
 
+Repeat without `--pretend` to apply. Stop an existing watcher through its current
+manager before changing owners; the generator does not stop running processes.
+Explicit updates refresh owned directives in place, preserving surrounding text
+and the block's newline style. Repeating setup preserves the existing directive.
+Earlier Git builds used a Puma guard that checked only whether Woods was loaded;
+use the update command above with a supporting bundle to install the capability
+guard ([#542](https://github.com/lost-in-the/woods/issues/542), included in Woods
+`2.0.0`). Do not hand-edit the owned block or receipt.
+
+For a permanent downgrade, remove the startup configuration while the supporting
+gem is still installed. The updated Puma guard lets a branch with an older gem
+boot without indexing; it does not make `bin/woods-watch` or a Foreman entry
+compatible with that gem.
+For Docker/Grove, see [automatic maintenance](AUTOMATIC_MAINTENANCE.md).
+
+An interrupted apply retains its local transaction journal. When Rails boots,
+preview recovery with `bin/rails generate woods:watch --operation recover
+--pretend`, then repeat without `--pretend`. The Rails command boots the application
+before invoking the generator; its `--pretend` prevents installation writes,
+not application initialization.
+
+If an initializer prevents Rails boot, run the boot-free recovery helper directly
+from the application root using its bundle:
+
+```bash
+bundle exec ruby -rwoods/watch/installation -e \
+  'puts Woods::Watch::Installation.new(root: Dir.pwd).recover(pretend: true)'
+```
+
+Repeat with `pretend: false` to restore the recorded transaction. Recovery checks
+snapshots and changes only owned files; concurrent edits keep the journal for
+manual resolution. The helper does not load Rails or run task probes. Do not
+delete a pending journal to force setup.
+
+### Managed restart and failure behavior
+
+`woods-watch -- bin/rails woods:watch` stays outside Rails and starts a fresh child
+for each planned restart. It absorbs exit 75 so Foreman/Puma remain running.
+Managed launching requires POSIX process groups and `fork` (Linux/macOS Ruby).
+Other platforms should use the raw task with an external supervisor.
+Boot failures retry with bounded backoff; a failed extraction leaves the last
+good generation readable. `--boot-timeout SECONDS` defaults to 300 seconds and
+bounds boot/handshake, not a valid extraction or writer-lock wait.
+
+Managed mode requires `WOODS_WATCH_IDLE_TIMEOUT` to be unset: automatic maintenance
+needs a resident child. An unexpected clean stop, incompatible child, or another
+owner parks the launcher with a diagnostic until its normal owner restarts it.
+There is no automatic ownership takeover. Managed duplicate prevention is scoped
+to one host/process namespace; do not mix raw and managed writers across different
+containers sharing an index. Use one external owner for that arrangement.
+
+Daemon liveness, completed startup reconciliation, and source freshness remain
+different facts. Managed supervision records under `watch_supervisors/` expose
+starting/retrying/parked state separately in `woods_status`; an alive supervisor
+without a maintaining child does not provide daemon coverage. If the first Rails
+boot fails before resolving the configured index path, diagnostics are logs-only.
+
+Verify startup catch-up, an edit, and an initializer restart through the existing
+MCP connection before declaring automatic maintenance active. With worktree
+management, also verify source and index mounts switch together.
+
 ## One cycle
 
 ```
@@ -169,7 +314,7 @@ is alive, so *alive has to mean covered*.
 The standalone `woods:watch` task snapshots reload/restart inputs before invoking
 Rails' `environment` task. Inputs unchanged across that boundary, including
 carried paths that remain deleted, may be reconciled by a full extraction.
-Unreleased after `2.0.0.beta3`: registered restart inputs deleted while the
+Included in Woods `2.0.0`: registered restart inputs deleted while the
 daemon was stopped also trigger a full extraction after a fresh environment
 boot. Nominal framework paths still use the bounded deletion sweep.
 Changes during environment initialization still require restart. Lock contention,
@@ -283,6 +428,14 @@ Ignored by default: `.git`, `node_modules`, `tmp`, `log`, `coverage`,
 `vendor/bundle`, `public/assets`, `public/packs`, `storage`. That ignore list is
 what keeps a polling scan bounded.
 
+A commit, ref update, or other Git-only change does not necessarily trigger a
+source-file event. The watcher can therefore keep source current while the
+published Git history or provenance still describes an earlier commit. Run full
+`woods:extract` when current Git metadata is required; incremental extraction
+refreshes history only for rewritten units. For containerized linked worktrees,
+verify [Git directory selection](TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees)
+as well as source and index mounts.
+
 Polling and startup catch-up preserve each logical path when multiple directory
 symlinks point to the same source tree. For example, `a_shared/user.rb` and
 `app/models/user.rb` both remain visible; an earlier alias must not hide the path
@@ -293,15 +446,15 @@ aliases in large watched trees. Ignored logical paths are still pruned.
 
 ## Placement
 
-The spike asked for three placements to be compared and one chosen. Every
-collaborator on `Woods::Watch::Daemon` is injected, so all three are reachable
-from the same class, but the default is **(b), a dedicated daemon per
-worktree**:
+Run one dedicated extraction process per active worktree/index. The managed
+Puma adapter and native launcher above retain that separation. Requiring Woods
+or loading its Railtie does not start indexing by itself. Custom integrations
+can use the injected daemon collaborators deliberately:
 
 | Option | Verdict |
 |---|---|
 | **(b) Dedicated daemon**: *recommended default* | One extra booted app per worktree. Isolated: a crash, a restart, or a storm affects only the index. Lifecycle is drivable from worktree hooks. |
-| **(a) Embedded in the dev server** via the Railtie | Marginal memory cost ~0 where a booted app already exists, but couples index freshness to the dev server running and puts extraction on its threads. `Daemon#process` is public precisely so a host can do this deliberately. |
+| **(a) Custom in-process integration** | A host can call public `Daemon#process` deliberately, but must own threading, reloading, and lifecycle. This is not an automatic Railtie feature or the managed Puma adapter. |
 | **(c) Host watcher + in-container session** | Solves bind-mount event unreliability, but with the most moving parts. Forcing the polling backend solves the same problem with none. |
 
 Measured on the fixture app (Ruby 3.3, Rails 8.0):
@@ -652,7 +805,7 @@ hooks (`plugin/hooks/hooks.json`), both shipped disabled:
 Both read `cwd` from the hook payload, so a linked worktree uses its own index.
 Both require an existing `generation.json` and `WOODS_HOOKS_ENABLED=1`;
 `WOODS_HOOKS_DISABLED=1` overrides enablement. The broader refresh task is
-**unreleased after Woods 2.0.0.beta2**. Check the installed gem's task list
+**included in Woods `2.0.0`**. Check the installed gem's task list
 (`bundle exec rake -T woods:hook_refresh`, through the application container
 when appropriate) before enabling this plugin version. An older gem's unknown
 task error leaves queued events in place; installing the plugin does not upgrade
@@ -750,8 +903,10 @@ per-process language-server index does not.
 
 N resident daemons is N booted apps, and most slots are dormant most of the
 time. `idle_timeout` (off by default) stops a daemon after that many seconds
-without a file event, so a slot nobody is working in stops holding ~65 MB. A
-worktree hook or session start revives it.
+without a file event. Revival requires a separately configured supervisor or
+startup hook; the shipped SessionStart hook only checks freshness. Managed
+`woods-watch` rejects this setting because an idle child shutdown would leave
+automatic maintenance inactive until the owner restarts it.
 
 ```ruby
 Woods::Watch::Daemon.new(output_dir: …, idle_timeout: 900).run   # 15 minutes
@@ -813,8 +968,8 @@ supplies batches to it.
 
 ### Optional bounded context hints
 
-Context hints are a separate Claude Code opt-in, **unreleased after Woods
-2.0.0.beta2**. Verify `bundle exec woods-hook-context --help` in the installed
+Context hints are a separate Claude Code opt-in, **included in Woods `2.0.0`**.
+Verify `bundle exec woods-hook-context --help` in the installed
 application bundle before enabling `WOODS_HOOK_CONTEXT_ENABLED=1`. The plugin
 version alone does not establish gem support. `WOODS_HOOKS_DISABLED=1` disables
 both context and refresh; `WOODS_HOOKS_ENABLED` controls only the existing