woods 1.6.1 → 2.0.0.beta2

data/lib/woods.rb

@@ -22,6 +22,10 @@
 #   end
 #
 require_relative 'woods/version'
+# Configuration's `component_paths` default lives with the discovery it feeds.
+require_relative 'woods/extractors/component_discovery'
+# Configuration defaults the cycle caps to the analyzer's own constants.
+require_relative 'woods/graph_analyzer'
 
 module Woods
   class Error < StandardError; end
@@ -120,8 +124,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 +146,21 @@ 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,
+                :graph_cycle_limit, :graph_cycle_max_length,
+                :incremental_blast_radius_depth, :durable_payload_writes
 
     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 +208,28 @@ 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
+      @graph_cycle_limit = GraphAnalyzer::DEFAULT_CYCLE_LIMIT
+      @graph_cycle_max_length = GraphAnalyzer::DEFAULT_CYCLE_MAX_LENGTH
+      # nil = the unbounded transitive closure. See the setter for why the
+      # default is not a small number.
+      @incremental_blast_radius_depth = nil
+      # false = payload files are written without a per-file fsync and the
+      # whole payload is flushed once before `generation.json` is written.
+      # See the setter.
+      @durable_payload_writes = false
+      # 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 +268,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,9 +279,37 @@ 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
 
+    # Force an fsync on every payload file as it is written, on top of the
+    # single flush the publish already performs.
+    #
+    # Off by default, and off is not a weaker guarantee. Readers resolve only
+    # through `generation.json`; a payload file has no reader until that
+    # pointer names it, and {Woods::Extractor#sync_payload} makes the whole
+    # payload durable before the pointer is written. Turning this on buys
+    # exactly one thing: an individual payload file being durable before the
+    # pointer exists.
+    #
+    # It costs a lot for it. Two forced flushes per file, 8.9ms each on btrfs:
+    # 8000 units is 71s of writing against 1s.
+    #
+    # Turning it on cannot disable the publish flush. That flush *is* the
+    # durability contract, so it has no opt-out.
+    #
+    # @param value [Boolean]
+    # @raise [Woods::ConfigurationError] when value is not a boolean
+    def durable_payload_writes=(value)
+      validate_boolean!(:durable_payload_writes, value)
+      @durable_payload_writes = value
+    end
+
     # @param value [Boolean] Must be true or false
     # @raise [ConfigurationError] if value is not a boolean
     def pretty_json=(value)
@@ -270,17 +335,81 @@ 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
+
+    # How many distinct cycles {Woods::GraphAnalyzer#cycles} enumerates before
+    # it stops. `nil` removes the cap and restores exhaustive enumeration.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def graph_cycle_limit=(value)
+      @graph_cycle_limit = validate_optional_positive_integer!(:graph_cycle_limit, value)
+    end
+
+    # The longest cycle {Woods::GraphAnalyzer#cycles} records, in distinct
+    # nodes. `nil` removes the cap.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def graph_cycle_max_length=(value)
+      @graph_cycle_max_length = validate_optional_positive_integer!(:graph_cycle_max_length, value)
+    end
+
+    # How many reverse hops an incremental run walks from a changed file
+    # before it stops re-extracting dependents. `nil` (the default) keeps the
+    # unbounded transitive closure.
+    #
+    # A unit's extracted content is mostly a function of its own source and
+    # its own reflection, so on most graphs a small cap re-extracts the same
+    # bytes far faster. It is not safe everywhere, which is why the default
+    # is unbounded: an STI grandchild reads its grandparent's reflection
+    # (`reflect_on_all_associations`, `_validators` and the callback chain
+    # are all inherited), so `SportsCar < Car < Vehicle` has content that
+    # changes when `Vehicle` changes while sitting two hops away in the
+    # graph. A nested `has_many :through` resolves through the same kind of
+    # chain. Set this only on a tree you know has neither.
+    #
+    # @param value [Integer, nil] must be a positive Integer, or nil
+    # @raise [ConfigurationError] otherwise
+    def incremental_blast_radius_depth=(value)
+      @incremental_blast_radius_depth = validate_optional_positive_integer!(
+        :incremental_blast_radius_depth, value
+      )
+    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
 
     private
 
+    # @return [Integer, nil] +value+ when it is nil or a positive Integer
+    # @raise [ConfigurationError] otherwise
+    def validate_optional_positive_integer!(name, value)
+      return value if value.nil?
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ConfigurationError, "#{name} must be a positive Integer or nil, got #{value.inspect}"
+    end
+
     def validate_boolean!(name, value)
       return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
 
@@ -305,7 +434,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).