woods 1.6.0 → 2.0.0.beta1

data/lib/woods.rb

@@ -22,6 +22,8 @@
 #   end
 #
 require_relative 'woods/version'
+# Configuration's `component_paths` default lives with the discovery it feeds.
+require_relative 'woods/extractors/component_discovery'
 
 module Woods
   class Error < StandardError; end
@@ -120,8 +122,13 @@ module Woods
   # ════════════════════════════════════════════════════════════════════════
 
   class Configuration # rubocop:disable Metrics/ClassLength
-    attr_accessor :embedding_model, :include_framework_sources, :gem_configs,
-                  :vector_store, :metadata_store, :graph_store, :embedding_provider, :log_level,
+    # The set every full extraction always runs, regardless of `extractors=`.
+    # See the {#extractors=} YARD note: this knob does not gate extraction.
+    DEFAULT_EXTRACTORS = %i[models controllers services components view_components jobs mailers graphql
+                            serializers managers policies validators rails_source].freeze
+
+    attr_accessor :include_framework_sources, :gem_configs,
+                  :vector_store, :metadata_store, :graph_store, :embedding_provider,
                   :vector_store_options, :metadata_store_options, :embedding_options,
                   :concurrent_extraction, :precompute_flows, :extract_navigation_edges, :enable_snapshots,
                   :session_tracer_enabled, :session_tracer_allow_production,
@@ -137,19 +144,19 @@ module Woods
                   :notion_api_token, :notion_database_ids,
                   :unblocked_api_token, :unblocked_collection_id, :unblocked_repo_url,
                   :cache_store, :cache_options,
-                  :dump_retention_count
-    attr_reader :max_context_tokens, :similarity_threshold, :extractors, :pretty_json, :context_format,
-                :cache_enabled
+                  :dump_retention_count, :component_paths
+    attr_reader :embedding_model, :max_context_tokens, :similarity_threshold, :extractors, :pretty_json,
+                :context_format, :cache_enabled, :volatile_dependency_ratio
 
     def initialize # rubocop:disable Metrics/MethodLength
       @output_dir = nil # Resolved lazily; Rails.root is nil at require time
       @embedding_model = 'text-embedding-3-small'
+      @embedding_model_explicit = false
       @max_context_tokens = 8000
       @similarity_threshold = 0.7
       @include_framework_sources = true
       @gem_configs = {}
-      @extractors = %i[models controllers services components view_components jobs mailers graphql serializers
-                       managers policies validators rails_source]
+      @extractors = DEFAULT_EXTRACTORS.dup
       @pretty_json = true
       @concurrent_extraction = false
       @precompute_flows = false
@@ -197,6 +204,19 @@ module Woods
       @cache_store = nil      # :redis, :solid_cache, :memory, or a CacheStore instance
       @cache_options = {}     # { redis: client, cache: store, ttl: { embeddings: 86400, ... } }
       @dump_retention_count = 3
+      @volatile_dependency_ratio = 3.0
+      # Directories the component extractors walk before reading `descendants`,
+      # relative to Rails.root. See Extractors::ComponentDiscovery.
+      @component_paths = Extractors::ComponentDiscovery::DEFAULT_COMPONENT_PATHS.dup
+    end
+
+    def embedding_model=(value)
+      @embedding_model = value
+      @embedding_model_explicit = true
+    end
+
+    def embedding_model_explicit?
+      @embedding_model_explicit
     end
 
     # @return [Pathname, String] Output directory, defaulting to Rails.root/tmp/woods
@@ -235,6 +255,10 @@ module Woods
       @similarity_threshold = float_val
     end
 
+    # Accepted for forward compatibility. Extraction always runs all 34
+    # extractors; this array is not consulted anywhere in the extraction
+    # path. Setting it to anything other than {DEFAULT_EXTRACTORS} warns.
+    #
     # @param value [Array<Symbol>] List of extractor names
     # @raise [ConfigurationError] if value is not an Array of Symbols
     def extractors=(value)
@@ -242,6 +266,11 @@ module Woods
         raise ConfigurationError, "extractors must be an Array of Symbols, got #{value.inspect}"
       end
 
+      if value.sort_by(&:to_s) != DEFAULT_EXTRACTORS.sort_by(&:to_s)
+        warn 'config.extractors is accepted for forward compatibility but extractor selection is not ' \
+             'implemented; all extractors run.'
+      end
+
       @extractors = value
     end
 
@@ -270,12 +299,27 @@ module Woods
       @cache_enabled = value
     end
 
-    # Add a gem to be indexed
+    # Commit-count ratio above which {Woods::GraphAnalyzer#volatile_dependencies}
+    # reports an edge. Stored as a Float.
+    #
+    # @param value [Numeric] must be greater than 1
+    # @raise [ConfigurationError] otherwise
+    def volatile_dependency_ratio=(value)
+      unless value.is_a?(Numeric) && value > 1
+        raise ConfigurationError, "volatile_dependency_ratio must be a number greater than 1, got #{value.inspect}"
+      end
+
+      @volatile_dependency_ratio = value.to_f
+    end
+
+    # Accepted for forward compatibility. Nothing reads {gem_configs}; gem
+    # source indexing is not implemented.
     #
     # @param gem_name [String] Name of the gem
     # @param paths [Array<String>] Relative paths within the gem to index
     # @param priority [Symbol] :high, :medium, or :low
     def add_gem(gem_name, paths:, priority: :medium)
+      warn 'config.add_gem is accepted for forward compatibility but gem configs are not used.'
       @gem_configs[gem_name] = { paths: paths, priority: priority }
     end
 
@@ -305,7 +349,7 @@ module Woods
 
     # Configure the module using a named preset and optional block customization.
     #
-    # Valid preset names: :local, :postgresql, :production
+    # Valid preset names: :local, :shared_filesystem, :postgresql, :production
     #
     # @param name [Symbol] Preset name
     # @yield [config] Optional block for further customization after preset is applied

data/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "woods-plugin",
+  "description": "Woods user guides for Claude Code: set up, upgrade, configure MCP servers for, investigate codebases with, enable a repository's agents on, and diagnose the Woods Rails code-intelligence gem.",
+  "version": "2.3.0",
+  "author": {
+    "name": "lost-in-the"
+  },
+  "homepage": "https://github.com/lost-in-the/woods",
+  "repository": "https://github.com/lost-in-the/woods",
+  "license": "MIT",
+  "keywords": [
+    "rails",
+    "woods",
+    "mcp",
+    "code-intelligence",
+    "agent"
+  ]
+}

data/plugin/hooks/hooks.json

@@ -0,0 +1,29 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/woods-post-edit.sh\"",
+            "async": true,
+            "timeout": 600
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/woods-session-start.sh\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  }
+}

data/plugin/hooks/woods-post-edit.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# Woods PostToolUse hook (#280): after an edit to a graph-changing path,
+# refresh the index with `woods:incremental` in the background.
+#
+# Reads `cwd` from the hook payload, not CLAUDE_PROJECT_DIR, so a session in
+# a linked worktree refreshes that worktree's own index. Runs only when an
+# index already exists there. `woods:incremental` stands down under a
+# running watch daemon and takes the extraction lock itself; the lock here
+# only stops this hook from queueing one rake process per keystroke.
+#
+# Opt-in: this hook is shipped disabled. It does nothing until
+# WOODS_HOOKS_ENABLED=1 is set (see docs/WATCH_DAEMON.md and the woods-setup
+# skill for where to set it). WOODS_HOOKS_DISABLED=1 turns it back off even
+# after it has been enabled, without touching the enable setting.
+#
+# Lock contention must not drop an edit. A hook invocation that finds the
+# run lock busy appends its path to hook-pending.txt and returns immediately
+# instead of waiting; whichever invocation is holding the run lock drains
+# that file in a loop, passing every path collected on each drain as one
+# CHANGED_FILES batch, until a drain comes back empty. The one narrow gap
+# this leaves: an append that lands after the holder's last (empty) drain
+# but before it releases the run lock sits in the file, unprocessed, until
+# the next graph-changing edit triggers a hook that both appends it and
+# then wins the now-free run lock itself. That edit is delayed, not lost,
+# and the SessionStart hook's staleness warning is the backstop for it.
+#
+# The mkdir-based lock fallback has no kernel-enforced release: a `flock`
+# held by a killed process is freed automatically, but a lock *directory*
+# a killed process made is not. A hook killed mid-drain (OOM, a `kill -9`,
+# the host restarting) leaves `hook.lock.d` or `hook-pending.lock.d` behind
+# forever, so every later hook either skips draining permanently (the run
+# lock) or spins until the 600s hook timeout on every single invocation
+# (the pending lock, which blocks). Both lock directories are therefore
+# reclaimed once their mtime is older than WOODS_HOOK_LOCK_STALE_SECONDS: a
+# fresh lock directory is still respected as busy.
+#
+# Knobs:
+#   WOODS_HOOK_RAKE      command prefix, default "bundle exec rake"
+#                        (Docker: "docker compose exec -T app bundle exec rake")
+#   WOODS_OUTPUT         index directory override, same variable
+#                        woods:incremental/woods:watch_status already read;
+#                        default tmp/woods under the payload's cwd
+#   WOODS_HOOKS_ENABLED  set to 1 to turn the hook on
+#   WOODS_HOOKS_DISABLED set to 1 to turn it back off
+#   WOODS_HOOK_LOCK_STALE_SECONDS
+#                        age (mtime) after which a leftover mkdir-based lock
+#                        directory is reclaimed instead of respected as busy;
+#                        default 1800 (a few multiples of the 600s hook
+#                        timeout). Only the mkdir fallback needs this;
+#                        flock has no equivalent problem.
+set -u
+
+[ "${WOODS_HOOKS_DISABLED:-0}" = "1" ] && exit 0
+[ "${WOODS_HOOKS_ENABLED:-0}" = "1" ] || exit 0
+
+payload="$(cat)"
+
+# $1: dotted key path. Prefers jq, falls back to ruby, else gives up quietly.
+field() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$payload" | jq -r ".$1 // empty"
+  elif command -v ruby >/dev/null 2>&1; then
+    printf '%s' "$payload" | ruby -rjson -e '
+      value = JSON.parse($stdin.read)
+      ARGV[0].split(".").each { |key| value = value.is_a?(Hash) ? value[key] : nil }
+      print value.to_s' -- "$1"
+  else
+    printf ''
+  fi
+}
+
+cwd="$(field cwd)"
+file="$(field tool_input.file_path)"
+[ -z "$cwd" ] && exit 0
+[ -z "$file" ] && exit 0
+
+# Same no-boot resolution woods:watch_status uses: an explicit WOODS_OUTPUT
+# wins outright (absolute or relative to cwd), otherwise tmp/woods under cwd.
+# This is the config's own override knob, not a second hardcoded path.
+configured_output="${WOODS_OUTPUT:-tmp/woods}"
+case "$configured_output" in
+  /*) tmp_dir="$configured_output" ;;
+  *) tmp_dir="$cwd/$configured_output" ;;
+esac
+
+[ -f "$tmp_dir/generation.json" ] || exit 0
+
+case "$file" in
+  "$cwd"/*) rel="${file#"$cwd"/}" ;;
+  /*) exit 0 ;;
+  *) rel="$file" ;;
+esac
+
+case "$rel" in
+  app/models/*|config/routes.rb|config/routes/*|db/migrate/*|db/*_migrate/*|db/schema.rb|db/structure.sql|package.yml|*/package.yml|packwerk.yml) ;;
+  *) exit 0 ;;
+esac
+
+rake="${WOODS_HOOK_RAKE:-bundle exec rake}"
+log="$tmp_dir/hook.log"
+pending_file="$tmp_dir/hook-pending.txt"
+pending_lock="$tmp_dir/hook-pending.lock"
+pending_lock_dir="$tmp_dir/hook-pending.lock.d"
+run_lock="$tmp_dir/hook.lock"
+run_lock_dir="$tmp_dir/hook.lock.d"
+
+mkdir -p "$tmp_dir" 2>/dev/null || true
+
+have_flock() { command -v flock >/dev/null 2>&1; }
+
+# mtime of a directory in epoch seconds, GNU stat then BSD stat, empty if
+# neither exists (treated as "not stale": fail closed, keep waiting rather
+# than reclaim on a guess).
+dir_mtime() {
+  stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null
+}
+
+# True when $1 is an mkdir-based lock directory old enough that it can only
+# be a crash leftover, never a legitimately still-running hook (a hook run
+# is one rake invocation, bounded by the 600s hook timeout).
+lock_dir_stale() {
+  mtime="$(dir_mtime "$1")"
+  [ -z "$mtime" ] && return 1
+  now="$(date +%s)"
+  age=$((now - mtime))
+  [ "$age" -gt "${WOODS_HOOK_LOCK_STALE_SECONDS:-1800}" ]
+}
+
+# Blocking mkdir-based lock acquire: waits for $1, reclaiming it once stale
+# rather than waiting for a crashed holder that will never release it.
+acquire_mkdir_lock() {
+  while ! mkdir "$1" 2>/dev/null; do
+    if lock_dir_stale "$1"; then
+      rmdir "$1" 2>/dev/null || true
+      continue
+    fi
+    sleep 0.1
+  done
+}
+
+release_mkdir_lock() {
+  rmdir "$1" 2>/dev/null || true
+}
+
+# Non-blocking mkdir-based lock attempt: one reclaim retry when stale, no
+# wait otherwise (contention here means "someone else is already draining,"
+# not "someone crashed").
+try_acquire_mkdir_lock() {
+  mkdir "$1" 2>/dev/null && return 0
+  if lock_dir_stale "$1"; then
+    rmdir "$1" 2>/dev/null || true
+    mkdir "$1" 2>/dev/null && return 0
+  fi
+  return 1
+}
+
+# Append one path to the pending file. Blocking: the critical section is a
+# single append, so any wait here is brief regardless of who else holds it.
+append_pending() {
+  if have_flock; then
+    exec 7>"$pending_lock"
+    flock 7
+    printf '%s\n' "$1" >>"$pending_file"
+    flock -u 7
+    exec 7>&-
+  else
+    acquire_mkdir_lock "$pending_lock_dir"
+    printf '%s\n' "$1" >>"$pending_file"
+    release_mkdir_lock "$pending_lock_dir"
+  fi
+}
+
+# Print and clear whatever is currently pending, empty output if nothing is.
+drain_pending() {
+  if have_flock; then
+    exec 7>"$pending_lock"
+    flock 7
+    if [ -s "$pending_file" ]; then
+      cat "$pending_file"
+      : >"$pending_file"
+    fi
+    flock -u 7
+    exec 7>&-
+  else
+    acquire_mkdir_lock "$pending_lock_dir"
+    if [ -s "$pending_file" ]; then
+      cat "$pending_file"
+      : >"$pending_file"
+    fi
+    release_mkdir_lock "$pending_lock_dir"
+  fi
+}
+
+run_incremental() {
+  # A drain can return several paths at once; CHANGED_FILES takes a
+  # comma-separated list (see lib/tasks/woods.rake).
+  changed="$(printf '%s\n' "$1" | tr '\n' ',' | sed 's/,$//')"
+  # shellcheck disable=SC2086
+  ( cd "$cwd" && CHANGED_FILES="$changed" $rake woods:incremental ) >>"$log" 2>&1
+}
+
+drain_until_empty() {
+  while :; do
+    batch="$(drain_pending)"
+    [ -z "$batch" ] && break
+    run_incremental "$batch"
+  done
+}
+
+append_pending "$rel"
+
+if have_flock; then
+  exec 8>"$run_lock"
+  if flock -n 8; then
+    drain_until_empty
+    flock -u 8
+  fi
+  exec 8>&-
+else
+  if try_acquire_mkdir_lock "$run_lock_dir"; then
+    drain_until_empty
+    release_mkdir_lock "$run_lock_dir"
+  fi
+fi
+
+exit 0

data/plugin/hooks/woods-session-start.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Woods SessionStart hook (#280): say so when the published generation is
+# older than the last commit. Stdout from a SessionStart hook is added to
+# the session context, so the agent sees the warning before it trusts the
+# index.
+#
+# This check only compares two commit-adjacent timestamps: the generation's
+# `updated_at` and `git log -1`'s commit time. It says nothing about
+# uncommitted edits (the index can be stale against a dirty working tree
+# with no stale commit to detect) or about a checkout sitting on an older
+# commit than the one that produced the generation (the timestamp comparison
+# can read as fresh there even though the code and the index disagree). Read
+# a quiet run as "not behind the last commit," not as "definitely current."
+#
+# Opt-in: shipped disabled. Nothing prints until WOODS_HOOKS_ENABLED=1 is
+# set; WOODS_HOOKS_DISABLED=1 turns it back off without touching that
+# setting.
+set -u
+
+[ "${WOODS_HOOKS_DISABLED:-0}" = "1" ] && exit 0
+[ "${WOODS_HOOKS_ENABLED:-0}" = "1" ] || exit 0
+
+payload="$(cat)"
+
+field() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$payload" | jq -r ".$1 // empty"
+  elif command -v ruby >/dev/null 2>&1; then
+    printf '%s' "$payload" | ruby -rjson -e '
+      value = JSON.parse($stdin.read)
+      ARGV[0].split(".").each { |key| value = value.is_a?(Hash) ? value[key] : nil }
+      print value.to_s' -- "$1"
+  else
+    printf ''
+  fi
+}
+
+cwd="$(field cwd)"
+[ -z "$cwd" ] && exit 0
+
+# Same no-boot resolution the PostToolUse hook and woods:watch_status use:
+# WOODS_OUTPUT overrides outright, otherwise tmp/woods under cwd.
+configured_output="${WOODS_OUTPUT:-tmp/woods}"
+case "$configured_output" in
+  /*) tmp_dir="$configured_output" ;;
+  *) tmp_dir="$cwd/$configured_output" ;;
+esac
+
+marker="$tmp_dir/generation.json"
+[ -f "$marker" ] || exit 0
+
+if command -v jq >/dev/null 2>&1; then
+  updated="$(jq -r '.updated_at // empty' "$marker")"
+  number="$(jq -r '.number // empty' "$marker")"
+elif command -v ruby >/dev/null 2>&1; then
+  updated="$(ruby -rjson -e 'print JSON.parse(File.read(ARGV[0]))["updated_at"].to_s' -- "$marker")"
+  number="$(ruby -rjson -e 'print JSON.parse(File.read(ARGV[0]))["number"].to_s' -- "$marker")"
+else
+  exit 0
+fi
+[ -z "$updated" ] && exit 0
+
+last_commit="$(git -C "$cwd" log -1 --format=%cI 2>/dev/null)"
+[ -z "$last_commit" ] && exit 0
+
+stale=0
+if command -v ruby >/dev/null 2>&1; then
+  ruby -rtime -e 'exit(Time.parse(ARGV[0]) < Time.parse(ARGV[1]) ? 1 : 0)' -- "$updated" "$last_commit" || stale=1
+elif date -d "$updated" +%s >/dev/null 2>&1; then
+  [ "$(date -d "$updated" +%s)" -lt "$(date -d "$last_commit" +%s)" ] && stale=1
+fi
+
+if [ "$stale" = "1" ]; then
+  echo "Woods index is stale: generation ${number:-?} was published at $updated, before the last commit at $last_commit." \
+       "Run bin/rails woods:incremental (or start bin/rails woods:watch) before trusting woods answers."
+fi
+exit 0

data/plugin/skills/woods-agent-enable/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: woods-agent-enable
+description: Make a repository's coding agents use the Woods index by default — wire the MCP server into project configuration, add index-first guidance to CLAUDE.md/AGENTS.md, and optionally create a project skill. Use when a user wants agents to "know" their Rails codebase, asks to add Woods to a team's agent setup or repository instructions, or wants codebase intelligence available in every session without per-user installs.
+---
+
+# Enable Woods for a repository's agents
+
+Installing the gem gives one operator an index; this skill gives every future agent session one. Wiring is three small, reviewable changes to the host repository. Each edits shared, checked-in files, so propose the diff and get approval before writing, match the repository's existing conventions, and leave unrelated content untouched.
+
+## Preflight
+
+Confirm Woods actually works before advertising it to every future session:
+
+```bash
+bundle info woods
+bin/rails woods:validate
+bin/rails woods:stats
+```
+
+A missing gem or index means setup comes first (woods-setup). Record the index path and whether the app runs on the host or in Docker — the MCP entry must use the command shape that matches (woods-mcp-config has the shapes).
+
+## 1. Project MCP configuration
+
+Add the Index Server to the repository's checked-in MCP configuration (`.mcp.json` for Claude Code; adapt to the team's client) using the Index-only shape from woods-mcp-config, so every clone gets the server without per-user setup. Do not wire Console MCP at the project level: it is live-data access and stays a per-user, explicitly authorized opt-in.
+
+## 2. Index-first guidance in the agent instructions
+
+Add a short section to the repository's agent instructions (CLAUDE.md, AGENTS.md, or the team's equivalent). Keep it to the contract, not a tool manual — the connected server's own tool list is the manual:
+
+```markdown
+## Codebase index (Woods)
+
+A Woods MCP server ("woods") serves a runtime-accurate index of this app.
+Call `woods_status` first; for structural questions prefer `search` →
+`lookup` → `dependencies`/`dependents`/`trace_flow` over broad file reading
+or grep. "Not found" is evidence about the index, not the code — check
+generation freshness before concluding. After changing files, refresh with
+`bin/rails woods:incremental` (or run the `woods:watch` daemon).
+```
+
+Adjust names and commands to the app (Docker prefix, custom index path, task aliases). If the repository already documents agent tooling, extend that section rather than adding a competing one.
+
+## 3. Optional: a project skill
+
+When the team wants stronger triggering than standing instructions provide, create a repository-level skill (for Claude Code: `.claude/skills/<app>-codebase/SKILL.md`) whose description names the application and its domains, and whose body applies the woods-investigate workflow to this codebase specifically: the entry-point identifiers worth knowing, domain cluster names, and local conventions. Seed that content from real `domain_clusters` and `pagerank` output rather than inventing it, and note in the skill that the index — not the skill text — is the source of truth as the app evolves.
+
+## Handoff
+
+Report the files changed, the MCP entry added, and one verified end-to-end call (`woods_status` through the configured client, not a raw JSON-RPC probe). Remind the owner that agent sessions pick up the changes on their next start, and that the index only stays useful if extraction stays current.
+
+Canonical guides: [AGENT_SETUP.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md), [AGENT_GUIDE.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_GUIDE.md).

data/plugin/skills/woods-diagnose/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: woods-diagnose
+description: Diagnose Woods failures layer by layer — Rails boot, published index, MCP process and path, semantic retrieval, Console — changing nothing until the failing layer is identified. Use when Woods extraction, index validation, an MCP connection, retrieval, storage, or Console access fails or looks stale, or when expected tools are missing from a connected server.
+---
+
+# Woods diagnosis
+
+Change nothing until the failing layer is identified. Diagnose the installed version:
+
+```bash
+bundle info woods
+git status --short --branch
+```
+
+This skill describes the Woods 2.x line; the authoritative minimum version lives in the marketplace entry. Diagnose against capabilities the recorded installed version actually provides.
+
+## 1. Check Rails
+
+```bash
+bundle exec rails runner 'puts Rails.application.class.name'
+bundle exec rails runner 'Rails.application.eager_load!; puts "eager load ok"'
+```
+
+Use the application's normal Docker command and environment variables when applicable. Fix boot/eager-load failures before Woods.
+
+## 2. Check the published index
+
+```bash
+bin/rails woods:validate
+bin/rails woods:stats
+```
+
+If missing or stale, run the narrow maintenance path justified by the evidence: `woods:incremental` for known file changes or `woods:extract` for first run, broad change, upgrade, or drift. Woods tasks understand `generation.json`; do not assume `manifest.json` is at the root.
+
+If a one-shot extraction raises `Could not publish generation`, the candidate
+payload was written but never made visible; readers still serve the previous
+complete generation. Fix the named filesystem, permission, space, or mount
+failure and rerun the same task. Never edit `generation.json` or point a reader
+at the unreachable payload by hand.
+
+## 3. Check the MCP process and path
+
+Compare the client config with the exact command, absolute `cwd`, bundle, and index path visible to that process. Run the configured executable manually to read stderr. For a host bundle:
+
+```bash
+bundle exec woods-mcp-start ./tmp/woods
+```
+
+Then reconnect through the MCP client and call `woods_status`. Use client-native tool inspection after initialization. Expect 14 packaged Index tools, not all conditional schemas.
+
+For Docker-only bundles, test the configured container command instead, for example `docker compose exec -T app bundle exec woods-mcp /app/tmp/woods`. Use the container path for a container process and a host path only for a host process.
+
+## 4. Check semantic retrieval
+
+Only diagnose this layer when structural tools work and `codebase_retrieve` fails. Check `woods_status`, configured provider/model/vector store, provider reachability, and whether `woods:embed` completed.
+
+- OpenAI: verify the key exists without printing it.
+- Ollama: verify the service and configured model locally.
+- Stale vectors or missing same-name types: follow the installed version's upgrade guide and run the documented embed refresh; do not rename public identifiers or edit vector IDs by hand.
+- Dimension mismatch: rebuild into a store matching the configured model; do not suppress the preflight.
+- Purge guard: back up and inspect the proposed deletion; never set `WOODS_ALLOW_PURGE` without explicit approval.
+
+## 5. Check Console separately
+
+Console failures are live Rails/config/security failures, not Index failures. Verify authorized environment, Rails boot, `WOODS_CONSOLE_CONFIG` or direct `cwd`, blocked-table policy, credentials, and stderr.
+
+For MySQL SQL refusals, inspect the executing session's `sql_mode` and the installed version's Console guide. Do not change quote modes to bypass a security refusal.
+
+Nine tools are normal. Eleven appear only with `console_embedded_read_tools`. Do not chase Tier 2/3 or `console_eval`; they do not register in supported packaged modes. Never work around redaction, credential scanning, SQL validation, or a block.
+
+## Report
+
+Return the first failing layer, commands/evidence, root-cause hypothesis, whether any file changed, and the smallest next action. If a fix is requested, change one thing and rerun the failing check before proceeding.
+
+Canonical guide: [TROUBLESHOOTING.md](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md).

data/plugin/skills/woods-investigate/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: woods-investigate
+description: Answer codebase questions from the Woods index — search, lookup, dependency and dependents traversal, flow tracing, and graph analysis, with verification rules. Use when auditing, code-reviewing, investigating, debugging, onboarding onto, or assessing change impact in a Rails application where a Woods MCP server is connected; query the index before broad file reading or grep.
+---
+
+# Woods investigation
+
+Woods is runtime evidence: resolved routes, schema, associations, callbacks, inlined concerns, dependencies, and execution flows extracted from the booted application. Use it to answer structural questions with less noise than file search, then verify important claims in source.
+
+## Preflight
+
+Call `woods_status` before relying on the index. Require a ready index with a current generation and non-zero counts for the types you need; use `codebase_retrieve` only when status reports retrieval enabled. If status is unhealthy or the generation predates the code under review, report that and ask the owner to run `woods:incremental` or `woods:extract` — do not present "not found" as proof the code does not exist.
+
+## The default loop
+
+1. **Discover** with `search` when the exact identifier is unknown (regex `query`, or safer `exact_prefix`/`exact_suffix` for namespaced names; restrict `types`).
+2. **Inspect** the best match with `lookup`.
+3. **Traverse** with `dependencies` (what it uses), `dependents` (what uses it), or `trace_flow`, starting at depth 1–2 with filters.
+4. **Verify** important claims against the returned source paths and current repository files.
+
+Identifiers are namespaced and typed; never invent one from a filename when `search` can return the exact value.
+
+## By task shape
+
+- **Code review / change impact**: `lookup` the changed unit, then `dependents` at depth 1 before going deeper. Group results by relationship type and layer; report direct dependents separately from inferred downstream impact. A graph edge is not test coverage — select tests from mappings and repository search.
+- **Audit / architecture assessment**: `graph_analysis` for orphans, dead ends, hubs, cycles, bridges, cross-database edges, volatile dependencies, and undeclared package edges; `domain_clusters` for architectural domains; `pagerank` for high-impact units worth reading first.
+- **Investigating behavior / debugging**: `trace_flow` from the user-visible entry point (route, controller action, job, mailer, service), `lookup` at ambiguous steps, and verify anything conditional or dynamically dispatched in source and tests — do not infer call order from a dependency edge.
+- **Onboarding**: `structure` for the codebase overview, `lookup` and `dependencies`/`dependents` for a unit's neighborhood, and `domain_clusters` for the domain map, then the default loop on the units that matter.
+- **Conceptual questions**: `codebase_retrieve` when status says ready; govern with `budget` (never `limit`), then verify key units with `lookup`.
+
+## Boundaries
+
+The normal packaged Index Server registers 14 tools; conditional schemas register only when their wiring is configured — use the connected server's own tool list, never the source inventory. Console MCP is authorized live-data access, not another code-search mode; use Index tools for structure. Never work around a block, validation error, or redaction.
+
+## Report evidence
+
+Name the tools and exact identifiers used, cite the source paths Woods returned, separate direct Woods evidence from inference, and state generation/staleness caveats. Say when a claim still needs source or test verification.
+
+Canonical guides: [AGENT_GUIDE.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_GUIDE.md), [MCP_TOOL_COOKBOOK.md](https://github.com/lost-in-the/woods/blob/main/docs/MCP_TOOL_COOKBOOK.md).