woods 2.0.0.beta3 → 2.0.0

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
 
 ```
@@ -96,7 +241,7 @@ partial write:
 
 | Failure | What happens |
 |---|---|
-| Reload raises (`SyntaxError`, `NameError`) | Degraded status naming the reason; index intact at generation N; retried on the next event |
+| Reload raises (`SyntaxError`, `NameError`) | Degraded status naming the reason; index intact at generation N; pending paths retried on the next file event or heartbeat |
 | Extraction raises | Degraded status; generation not advanced |
 | Payload directory can't be opened, over a payload-born index | Degraded status; generation not advanced. An incremental run only writes the units it touched, so there is no complete flat index it could fall back to publishing, see [Payload publishing](#payload-publishing) |
 | Index written but the generation bump failed | Degraded status; paths carried forward. The extractor deliberately does not fail an otherwise-good extraction over an unwritable marker, but the marker *is* what readers refresh on, so the daemon cross-checks that the number moved rather than reporting `running` over an index nothing can see |
@@ -119,17 +264,23 @@ at a known generation, reason attached), `stopped` (nothing is maintaining this
 index). A stale answer is only dangerous when nothing says so.
 
 The file is written world-readable (0644) by design: host-side hooks read it
-through a bind mount. Every other artifact Woods writes stays at 0600.
+through a bind mount. Writes through `Woods::AtomicFile` default to owner-only
+0600 unless the caller supplies another mode. This is not a guarantee for every
+Woods artifact: the SQLite metadata store does not enforce 0600, and a newly
+created database uses 0644 under umask 022. Restrict access to the output
+directory according to the source and metadata it contains.
 
 Note that `SyntaxError` is a `ScriptError`, not a `StandardError`. Rescuing
 only the latter would let a half-typed file kill the daemon.
 
 A cycle that fails to land its work never loses its paths. Lock contention, a
 failed reload, and a raising extraction all carry the batch into `@pending`, and
-the next cycle folds it back in, the files really did change, and no later
-event will mention them again. The retry is not a tight loop: a degraded cycle
-ends the drain and waits for the next event, because the cause needs an edit to
-clear.
+the next cycle folds it back in even if no new event mentions those files.
+A degraded cycle ends the current drain to avoid a tight retry loop. Pending
+paths are retried on the next file event or [heartbeat](#the-heartbeat), so a
+finished contending writer does not require another edit to trigger recovery.
+Heartbeat retries use a separate worker so status updates and lock refresh
+continue while extraction runs.
 
 ### The heartbeat
 
@@ -163,6 +314,9 @@ 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.
+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,
 extraction failure, and publication failure retain the full-reconciliation
 obligation for retry; a successful publish clears it.
@@ -202,8 +356,9 @@ already tolerate the duplicate paths this produces against whatever catch-up
 finds on its own via the tree scan.
 
 Deletions need one extra step, because a deleted file leaves no mtime to scan:
-if any path the index attributes a unit to is gone from disk, the daemon runs
-one cycle with an *empty* change set, which reaches the ghost units through the
+registered restart inputs follow the full-reconciliation rule above. For other
+registered paths gone from disk, a deletion-only startup runs one cycle with an
+*empty* change set, which reaches the ghost units through the
 extractor's bounded deletion sweep. Deliberately empty, naming the paths would
 make the deletions authoritative for every unit type, and some registered paths
 are nominal (on Rails < 7.1, `ActiveRecord::SchemaMigration` registers a
@@ -273,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
@@ -283,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):
@@ -642,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
@@ -740,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
@@ -803,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

data/docs/WHY_WOODS.md

@@ -56,9 +56,11 @@ It describes what the service does, but misses that `order.save!` triggers `afte
 :send_confirmation_email` on `Order`, which itself enqueues `InventoryJob` via
 `after_save :reserve_stock` on `LineItem`.
 
-With Woods, the dependency graph links `CheckoutService` → `Order` → `LineItem` →
-`InventoryJob`. A single retrieval call assembles the full execution picture: the service,
-the models it touches, the callbacks those models fire, and the jobs those callbacks enqueue.
+With Woods, published graph relationships can connect related services, models,
+callbacks, and jobs for retrieval. Arbitrary method-body constant references are
+not exhaustively indexed, so the whole `CheckoutService` → `Order` → `LineItem` →
+`InventoryJob` chain may not be recorded. Inspect the source and any flow evidence,
+including reported ambiguity and traversal limits, before concluding what runs.
 
 ---
 
@@ -175,11 +177,13 @@ Three tools answered "what is in this Rails app" for coding agents in 2026. Wood
 | Rubydex (Shopify) | 0.4.1, announced 2026-05-12 | Rust static index of declarations, references, ancestors; experimental `rdx mcp` | Symbol references across a large tree, fast re-index, reported 15 to 80 percent token reduction | Resolved callbacks, inlined concerns, routes as Rails builds them, database partition, churn |
 | rails-mcp-server | 2.0.0 | Boots the app; `analyze_models`, `get_routes`, `get_schema` | Live model, route, and schema listings over MCP | Callback side effects, request flows, git churn, graph reports, persistent index with generations |
 | ruby-lsp-rails | 0.5.0.beta1 | Runtime server over `rails runner` for the editor | Model columns, association targets, route info at the cursor | A persistent index other tools can read, graph analysis, multi-database facts |
-| Woods | 2.0 | Boots the app once, publishes an atomic JSON generation, serves it without Rails | Resolved runtime behavior on top of structure: inlined concerns, callback side effects, flows, churn, PageRank; database partition and Packwerk boundaries are in progress on this branch | Symbol-level references inside method bodies (Rubydex is the better fit and is complementary) |
+| Woods | 2.0 | Boots the app once, publishes an atomic JSON generation, serves it without Rails | Resolved runtime behavior on top of structure: inlined concerns, callback side effects, flows, churn, PageRank; recorded database partitions and Packwerk boundaries | Symbol-level references inside method bodies (Rubydex is the better fit and is complementary) |
 
 Woods and Rubydex are complementary. Rubydex answers "where is this symbol referenced". Woods answers "what happens when this runs, and what does it touch". An agent can use both: Rubydex for references, Woods for behavior, boundaries, and blast radius.
 
-The database-partition layer, in progress on this branch, is the one place Woods will be alone. Rubydex is static, and the other two resolve associations without saying which database each side lives on. See [Extractor reference](EXTRACTOR_REFERENCE.md#modelextractor) for the fields.
+Woods records database-partition metadata on models and Packwerk package ownership
+and boundaries. See [Extractor reference](EXTRACTOR_REFERENCE.md#modelextractor)
+for the fields and their coverage limits.
 
 ---
 

data/exe/woods-console

@@ -21,14 +21,14 @@
 # Check if the rake task already captured stdout for us.
 protocol_out = $woods_protocol_out # rubocop:disable Style/GlobalVars
 
-unless protocol_out
-  # Running via rails runner — capture stdout ourselves.
-  protocol_out = $stdout.dup
-  $stdout.reopen($stderr)
-end
+# Running via rails runner — capture stdout ourselves.
+protocol_out ||= $stdout.dup
+# Keep application logs and writes on stderr for the entire server lifetime.
+$stdout.reopen($stderr)
 
 require 'woods'
 require 'woods/console/server'
+require 'woods/console/stdio_transport'
 
 unless Woods.configuration.console_mcp_enabled
   warn 'Woods Console MCP is disabled. Set ' \
@@ -132,9 +132,11 @@ server = Woods::Console::Server.build_embedded(
   model_reflections: model_reflections
 )
 
-# Restore the protocol output for MCP transport.
-$stdout.reopen(protocol_out)
-protocol_out.close unless protocol_out.closed?
-
-transport = MCP::Server::Transports::StdioTransport.new(server)
-transport.open
+# Only the transport writes to the saved pipe. Restoring process stdout here
+# would also redirect Rails loggers and runtime puts back into the protocol.
+transport = Woods::Console::StdioTransport.new(server, output: protocol_out)
+begin
+  transport.open
+ensure
+  protocol_out.close unless protocol_out.closed?
+end

data/exe/woods-mcp-start

@@ -7,7 +7,7 @@
 # same as when launched directly. RubyGems loads gem executables as Ruby, so
 # this wrapper must remain a Ruby program when packaged.
 
-index_dir = ARGV[0] || ENV.fetch('WOODS_DIR', nil)
+index_dir = ARGV[0] || ENV.fetch('WOODS_DIR', nil) || ENV.fetch('WOODS_OUTPUT', nil)
 
 if index_dir.nil? || index_dir.empty?
   warn 'Error: No index directory specified.'
@@ -15,9 +15,13 @@ if index_dir.nil? || index_dir.empty?
   exit 1
 end
 
+index_dir = File.expand_path(index_dir)
+path_remedy = 'Point at the existing index with an explicit path, WOODS_DIR, or WOODS_OUTPUT. ' \
+              'If no index exists, run `bundle exec rake woods:extract` in your Rails app.'
+
 unless File.directory?(index_dir)
   warn "Error: Index directory does not exist: #{index_dir}"
-  warn 'Run extraction first: bundle exec rake woods:extract'
+  warn path_remedy
   exit 1
 end
 
@@ -27,7 +31,7 @@ end
 # whole library just to check one file is wasted work on every boot. A
 # payload-born index has no manifest.json at the root — it lives under the
 # directory generation.json's `payload` pointer names — so the pointer is
-# followed here too, with the same escape guard, before concluding the
+# followed here too, with the same realpath containment check, before concluding the
 # directory holds no index. woods-mcp re-checks this properly through
 # Bootstrapper regardless; this is just an early, friendlier exit.
 def manifest_present?(index_dir)
@@ -39,20 +43,21 @@ def manifest_present?(index_dir)
   require 'json'
   require_relative '../lib/woods/atomic_file'
   payload_name = JSON.parse(Woods::AtomicFile.read(generation_path))['payload']
-  return false if payload_name.nil? || payload_name.empty?
+  return false unless payload_name.is_a?(String) && !payload_name.empty?
 
-  root = File.expand_path(index_dir)
-  candidate = File.expand_path(File.join(root, payload_name))
+  root = File.realpath(index_dir)
+  candidate = File.realpath(payload_name, root)
   return false unless candidate.start_with?("#{root}#{File::SEPARATOR}")
 
   File.file?(File.join(candidate, 'manifest.json'))
-rescue JSON::ParserError, SystemCallError
+rescue JSON::ParserError, SystemCallError, TypeError, NoMethodError
   false
 end
 
 unless manifest_present?(index_dir)
-  warn "Error: No manifest.json in: #{index_dir}"
-  warn 'Run extraction first: bundle exec rake woods:extract'
+  warn "Error: Could not resolve a published Woods index in: #{index_dir}"
+  warn 'Expected generation.json pointing to a payload manifest.json, or a legacy flat manifest.json.'
+  warn path_remedy
   exit 1
 end
 

data/exe/woods-watch

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'woods/watch/cli'
+exit Woods::Watch::CLI.new.run(ARGV)

data/lib/generators/woods/pgvector_generator.rb

@@ -2,6 +2,7 @@
 
 require 'rails/generators'
 require 'rails/generators/active_record'
+require 'woods/storage/pgvector'
 
 module Woods
   module Generators
@@ -15,7 +16,7 @@ module Woods
     #
     # Usage:
     #   rails generate woods:pgvector
-    #   rails generate woods:pgvector --dimensions 3072
+    #   rails generate woods:pgvector --dimensions 768
     #
     class PgvectorGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
@@ -25,11 +26,16 @@ module Woods
       desc 'Creates the woods_vectors table (pgvector column + HNSW index) used by the Woods vector store'
 
       class_option :dimensions, type: :numeric, default: 1536,
-                                desc: 'Vector dimensions (1536 for text-embedding-3-small, 3072 for large)'
+                                desc: 'Vector dimensions (1-2000; default 1536 for text-embedding-3-small)'
 
       # @return [void]
       def create_migration_file
         @dimensions = options[:dimensions]
+        maximum = Woods::Storage::VectorStore::Pgvector::MAX_HNSW_DIMENSIONS
+        unless @dimensions.is_a?(Integer) && @dimensions.between?(1, maximum)
+          raise ArgumentError, "dimensions must be a positive Integer no greater than #{maximum} for pgvector HNSW"
+        end
+
         migration_template(
           'add_pgvector_to_woods.rb.erb',
           'db/migrate/add_pgvector_to_woods.rb'

data/lib/generators/woods/watch_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'woods/watch/installation'
+
+module Woods
+  module Generators
+    # Reversible opt-in startup integration; never rewrites an application's bin/dev.
+    class WatchGenerator < Rails::Generators::Base
+      desc 'Install, update, or remove owned Woods watcher startup configuration'
+
+      class_option :mode, type: :string, desc: 'Explicit startup mode: procfile, puma, or external'
+      class_option :operation, type: :string, default: 'setup', desc: 'setup, update, remove, or recover'
+      class_option :procfile, type: :string, default: 'Procfile.dev', desc: 'Existing root-level Foreman Procfile'
+      class_option :manager_command, type: :string,
+                                     desc: 'Normal Foreman startup argv, e.g. foreman start -f Procfile.dev'
+      class_option :child_command, type: :string, default: 'bin/rails woods:watch',
+                                   desc: 'Application task command, parsed as argv (no shell evaluation)'
+
+      # Rails generators otherwise print Thor errors and return a successful status.
+      # @return [Boolean] whether a refused installation fails the CLI command
+      def self.exit_on_failure?
+        true
+      end
+
+      # @return [void]
+      def configure_watcher
+        operation = behavior == :revoke ? 'remove' : options[:operation]
+        installation = build_installation(operation)
+        if operation == 'recover'
+          say installation.recover(pretend: options[:pretend])
+          return
+        end
+        plan = installation.plan
+        say JSON.pretty_generate(plan.summary)
+        return if options[:pretend]
+
+        say installation.apply(plan)
+        say installation.handoff unless operation == 'remove'
+      rescue Woods::Watch::Installation::Conflict => e
+        raise Thor::Error, e.message
+      end
+
+      private
+
+      def build_installation(operation)
+        Woods::Watch::Installation.new(root: destination_root, mode: options[:mode], operation: operation,
+                                       procfile: options[:procfile], manager_command: options[:manager_command],
+                                       child_command: options[:child_command])
+      end
+    end
+  end
+end

data/lib/puma/plugin/woods.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative '../../woods/watch/puma_adapter'
+
+Puma::Plugin.create do
+  def start(launcher)
+    @woods_adapter ||= Woods::Watch::PumaAdapter.new(launcher)
+    @woods_adapter.install
+  end
+end

data/lib/tasks/woods.rake

@@ -123,6 +123,9 @@ namespace :woods do
 
   desc 'Watch the app and keep the index current (resident daemon)'
   task :watch do
+    require 'woods/watch/managed_child'
+    managed_child = Woods::Watch::ManagedChild.from_env
+    managed_child&.call(:task_loaded, woods_version: Woods::VERSION)
     # Observe inputs before Rails initializes. A snapshot taken in Daemon.new
     # would silently bless edits made while initializers were running.
     require 'woods/watch/boot_snapshot'
@@ -130,6 +133,11 @@ namespace :woods do
     fresh_environment = !environment.already_invoked && !Rails.application.initialized?
     boot_snapshot = Woods::Watch::BootSnapshot.new(root: Rails.root) if fresh_environment
     environment.invoke
+    if managed_child && !Rails.env.development?
+      managed_child.call(:terminal, reason: 'unsupported_environment')
+      warn 'Managed Woods watching requires the finalized Rails development environment.'
+      next
+    end
     # Both, and the extractor is not optional. The daemon's default
     # extractor_factory names Woods::Extractor lazily, so omitting this require
     # loaded and started cleanly and then NameError'd on the first real cycle —
@@ -140,6 +148,7 @@ namespace :woods do
     require 'woods/watch/daemon'
 
     output_dir = ENV.fetch('WOODS_OUTPUT', Woods.configuration.output_dir)
+    managed_child&.call(:identity, root: File.expand_path(Rails.root.to_s), index: File.expand_path(output_dir.to_s))
 
     poll_interval = begin
       Float(ENV.fetch('WOODS_WATCH_POLL_INTERVAL', Woods::Watch::Watcher::DEFAULT_POLL_INTERVAL))
@@ -162,6 +171,8 @@ namespace :woods do
       idle_timeout: ENV.fetch('WOODS_WATCH_IDLE_TIMEOUT', nil) && Float(ENV.fetch('WOODS_WATCH_IDLE_TIMEOUT')),
       catch_up: ENV['WOODS_WATCH_CATCH_UP'] != '0',
       boot_snapshot: boot_snapshot,
+      lifecycle: managed_child,
+      conservative_claims: !managed_child.nil?,
       logger: Rails.logger
     )
 
@@ -182,6 +193,7 @@ namespace :woods do
     puts
 
     reason = daemon.run
+    managed_child&.call(:terminal, reason: reason.to_s)
 
     if reason == :restart_required
       # Boot-captured state changed; Rails cannot reload it. Exit non-zero so
@@ -192,6 +204,8 @@ namespace :woods do
     end
 
     puts 'Watcher stopped.'
+  ensure
+    managed_child&.close
   end
 
   desc 'Keep watch over the woods — resident index daemon (alias for watch)'

data/lib/woods/agent_configuration/applier.rb

@@ -50,8 +50,10 @@ module Woods
         "#{@layout.receipt_path}.pending"
       end
 
-      def with_lock
-        path = "#{@layout.receipt_path}.lock"
+      def with_lock(paths = @layout.lock_paths, &operation)
+        return operation.call if paths.empty?
+
+        path, *remaining = paths
         Document.validate_path!(path)
         FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
         File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600) do |lock|
@@ -61,7 +63,7 @@ module Woods
                   'Another Woods configuration operation is active; retry after it finishes'
           end
 
-          yield
+          with_lock(remaining, &operation)
         ensure
           lock&.flock(File::LOCK_UN)
         end

data/lib/woods/agent_configuration/cli.rb

@@ -78,12 +78,12 @@ module Woods
         write_plan(path, plan, layout)
         PlanDiff.show(plan, @stderr) if options[:diff]
         plan.summary.merge('plan_file' => File.expand_path(path),
-                           'runtime_files' => ["#{layout.receipt_path}.lock", "#{layout.receipt_path}.pending"])
+                           'runtime_files' => layout.runtime_paths)
       end
 
       def write_plan(path, plan, layout)
         target = File.expand_path(path)
-        protected_paths = layout.allowed_paths + ["#{layout.receipt_path}.lock", "#{layout.receipt_path}.pending"]
+        protected_paths = layout.allowed_paths + layout.runtime_paths
         raise Conflict, 'Plan output must differ from every managed/runtime target' if protected_paths.include?(target)
 
         Document.validate_path!(target)

data/lib/woods/agent_configuration/layout.rb

@@ -50,6 +50,19 @@ module Woods
         end
       end
 
+      # Lock actual managed targets, since user-scoped paths can be shared
+      # by different applications. Keep the receipt lock name for existing
+      # same-application callers; receipts and recovery journals stay separate.
+      def lock_paths
+        allowed_paths.map do |path|
+          path == receipt_path ? "#{path}.lock" : "#{path}.woods.lock"
+        end.sort
+      end
+
+      def runtime_paths
+        lock_paths + ["#{receipt_path}.pending"]
+      end
+
       def identity
         { 'client' => 'claude', 'scope' => scope, 'root' => root, 'config_dir' => config_dir,
           'config_path' => config_path, 'receipt_path' => receipt_path }