woods 1.6.1 → 2.0.0.beta2

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).

data/plugin/skills/woods-mcp-config/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: woods-mcp-config
+description: Configure Woods MCP connections with the exact client JSON shapes and token rules — the Index Server over stdio or Docker, and the authorized Console server over stdio or authenticated HTTP. Use when wiring a Woods server into any MCP client configuration (.mcp.json, Claude Code, desktop clients), pointing an agent at a Rails app's index, or enabling live-data Console access.
+---
+
+# Woods MCP configuration
+
+## Preflight
+
+```bash
+bundle info woods
+bin/rails woods:validate
+bin/rails woods:stats
+```
+
+This skill describes the Woods 2.x line; the authoritative minimum version lives in the marketplace entry. Operate only against capabilities the recorded installed version provides. Detect the MCP client, app root, host vs Docker Rails process, the filesystem context that contains the application bundle and index, and whether live-data access is actually required.
+
+Default to Index-only. It reads generated code context and exposes 14 tools. Console MCP boots Rails and reads live data; ask before enabling it.
+
+## Shape 1: Index-only
+
+```json
+{
+  "mcpServers": {
+    "woods": {
+      "command": "bundle",
+      "args": ["exec", "woods-mcp-start", "./tmp/woods"],
+      "cwd": "/absolute/path/to/app"
+    }
+  }
+}
+```
+
+Use this shape for any stdio-capable MCP client, adapted to the client's configuration location. `woods-mcp-start` validates and launches; it does not install or auto-restart.
+
+When Woods is installed only in Docker, prefer running the server through the application container:
+
+```json
+{
+  "mcpServers": {
+    "woods": {
+      "command": "docker",
+      "args": ["compose", "exec", "-T", "app", "bundle", "exec", "woods-mcp", "/app/tmp/woods"],
+      "cwd": "/absolute/host/path/to/app"
+    }
+  }
+}
+```
+
+Use a host-side bundle only after verifying Ruby, the application bundle, and the index are available on the host. Always pass the path visible to the process that runs `woods-mcp`.
+
+A read-only index mount is sufficient for structural tools. The `reload` tool for in-memory semantic retrieval also takes Woods' shared on-disk writer lock, so the MCP process needs write access to the index directory. Without it, reload returns a typed degraded error and keeps serving the previous aligned generation. Either grant that access or restart the MCP process after publishing a new embedded index.
+
+## Shape 2: Index plus authorized Console
+
+After explicit authorization, enable the live-data master switch in the Rails initializer. The process exits while it remains false:
+
+```ruby
+Woods.configure do |config|
+  config.console_mcp_enabled = true
+  config.console_mcp_token = ENV["WOODS_CONSOLE_MCP_TOKEN"]
+end
+```
+
+The token authenticates HTTP requests and is not sent by a stdio client. Production Rails boot still requires `WOODS_CONSOLE_MCP_TOKEN` to contain at least 32 characters whenever Console is enabled, including for a stdio-only setup. Keep it in the application's secret store. Outside production, omitting it warns and leaves the Console HTTP endpoint guarded with 401.
+
+Then add a direct Console process:
+
+```json
+"woods-console": {
+  "command": "bundle",
+  "args": ["exec", "woods-console-mcp"],
+  "cwd": "/absolute/path/to/app"
+}
+```
+
+For Docker/SSH, configure `~/.woods/console.yml` or `WOODS_CONSOLE_CONFIG`; the launcher owns process replacement. Direct Docker stdio uses `docker exec -i`, or `docker compose exec -T` to disable Compose's pseudo-TTY while retaining stdin.
+
+Console registers nine default tools. `config.console_embedded_read_tools = true` explicitly adds `console_sql` and `console_query` for eleven total. Tier 2, Tier 3, and `console_eval` are inventory-only in supported packaged modes.
+
+## Shape 3: Authenticated Console HTTP
+
+Use only after authorization and server-side setup:
+
+```json
+"woods-console": {
+  "type": "streamable-http",
+  "url": "https://app.example.test/mcp/console",
+  "headers": { "Authorization": "Bearer <token>" }
+}
+```
+
+Require `console_mcp_enabled`, a strong token, allowed origins, TLS, and the Console security controls. Never commit the token or expose an unauthenticated listener.
+
+## Verify
+
+Reconnect through the client so it performs its supported MCP negotiation. Clients on current MCP protocol revisions use per-request metadata/discovery; older clients initialize first — the server supports both. Call `woods_status`, `search`, and `lookup`. For Console, inspect the registered list and call `console_status` only in the authorized environment.
+
+Do not use an isolated raw JSON-RPC request as proof of MCP health. Do not claim conditional Index or inventory-only Console schemas are callable.
+
+Canonical guide: [MCP_SERVERS.md](https://github.com/lost-in-the/woods/blob/main/docs/MCP_SERVERS.md).

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

@@ -0,0 +1,99 @@
+---
+name: woods-setup
+description: Install, upgrade, and first-run-configure the Woods Rails code-intelligence gem — Gemfile entry, generator, extraction, index verification, MCP registration, and the 1.x-to-2.x upgrade path. Use whenever a user wants Woods added to or upgraded in a Rails app, or asks for a runtime-accurate codebase index for AI tools, even without naming Woods' components.
+---
+
+# Woods setup
+
+Install a structural Index Server first. Embeddings and Console MCP are separate opt-ins.
+
+## Preflight
+
+Read repository instructions and preserve unrelated changes. Record:
+
+```bash
+git status --short --branch
+ruby --version
+bundle exec rails --version
+bundle info woods 2>/dev/null || true
+bundle exec rails runner 'puts Rails.application.class.name'
+```
+
+This skill describes the Woods 2.x line; the authoritative minimum version lives in the marketplace entry. Operate only against capabilities the recorded installed version provides, and for an older gem use the documentation on that version's tag. Determine host vs Docker execution, database adapter, migration policy, existing Woods config/tables, and which filesystem context contains the application bundle and `tmp/woods/`.
+
+## Install and inspect
+
+Add `gem "woods", "~> 2.0"` to the development group, then:
+
+```bash
+bundle install
+bundle exec ruby -rwoods/version -e 'puts Woods::VERSION'
+bin/rails generate woods:install
+git diff -- config/initializers/woods.rb db/migrate
+```
+
+The generator creates an initializer and a legacy application migration for `woods_units`, `woods_edges`, and `woods_embeddings`. Woods 2's shipped structural index and storage backends do not use those application tables. For a new default installation, propose removing the generated migration and obtain approval first. Keep or run it only when repository history proves an older/custom integration uses those tables, after normal migration authorization and conflict checks.
+
+Do not broadly update gems or overwrite existing configuration.
+
+## Upgrading from 1.x
+
+When the preflight records an installed 1.x version, this is an upgrade, not an install. Woods 2.0 changes observable index identifiers, the publication layout, vector-store reconciliation, and the supported MCP surface, so plan a clean re-index and follow the canonical runbook: [UPGRADING_TO_2.md](https://github.com/lost-in-the/woods/blob/main/docs/UPGRADING_TO_2.md).
+
+Before changing the Gemfile: back up any shared or durable index and agree on a rollback window — never upgrade one in place. After `bundle update woods`, run a full `bin/rails woods:extract` (not incremental; the old index is not a valid baseline across the major), then `woods:validate`. With embeddings configured, re-embed from scratch into a store matching the configured model; expect identifier-level churn in anything that consumed 1.x identifiers (exports, saved queries, downstream tooling). Verify MCP clients against the new surface rather than assuming 1.x tool behavior.
+
+## Extract and verify
+
+Structural setup needs no embedding provider:
+
+```bash
+bin/rails woods:extract
+bin/rails woods:validate
+bin/rails woods:stats
+```
+
+If extraction fails, reproduce Rails boot and eager loading first. Do not inspect internal payload files when Woods tasks provide the check.
+
+Configure the Index Server with the application bundle, absolute app `cwd`, and an index path visible to that process. For a host-installed bundle:
+
+```json
+{
+  "mcpServers": {
+    "woods": {
+      "command": "bundle",
+      "args": ["exec", "woods-mcp-start", "./tmp/woods"],
+      "cwd": "/absolute/path/to/app"
+    }
+  }
+}
+```
+
+When Woods is installed only in Docker, launch it through the application service instead:
+
+```json
+{
+  "mcpServers": {
+    "woods": {
+      "command": "docker",
+      "args": ["compose", "exec", "-T", "app", "bundle", "exec", "woods-mcp", "/app/tmp/woods"],
+      "cwd": "/absolute/host/path/to/app"
+    }
+  }
+}
+```
+
+Reconnect and call `woods_status`, then `search`, `lookup`, and `dependents` for a known class. The normal Index Server has 14 tools. `codebase_retrieve` requires configured embeddings.
+
+Offer to add `bundle exec rake woods:watch` to the existing development process manager. When authorized, it catches up missed changes and automatically maintains the structural index; the Index Server refreshes on its next call, so ordinary edits need no manual extraction or MCP restart. State that boot-captured changes require supervisor restart, Docker may need `WOODS_WATCH_POLL=1`, and semantic vectors still need `woods:embed_incremental`.
+
+The plugin also ships two hooks (Woods 2.3 or later), shipped disabled. A `PostToolUse` hook runs `woods:incremental` in the background when an edit touches models, routes, migrations, schema, or a `package.yml`, reading `cwd` from the hook payload so linked worktrees refresh their own index; it batches paths from overlapping edits instead of dropping them under lock contention. A `SessionStart` hook warns when the published generation predates the last commit, a check scoped to commit timestamps, so it does not cover uncommitted edits or an older checkout. Both do nothing until `tmp/woods/generation.json` exists and until the user sets `WOODS_HOOKS_ENABLED=1`; set `WOODS_HOOK_RAKE="docker compose exec -T app bundle exec rake"` when the bundle lives in a container, `WOODS_OUTPUT` when the index directory is non-default, and `WOODS_HOOKS_DISABLED=1` to turn both back off.
+
+## Ask before expanding scope
+
+Require explicit approval before adding Ollama/OpenAI, pgvector/Qdrant, secrets, Console MCP/live-data access, HTTP transport, or purge overrides. The `:local` preset avoids cloud keys but requires the `sqlite3` gem, an installed/running Ollama service, and a pulled model (`ollama pull nomic-embed-text` by default); `:shared_filesystem` avoids sqlite3 but still uses Ollama. Recommend `gem "tokenizers", "~> 0.5"` for exact counting on dense Ruby source, while stating that it is optional.
+
+## Handoff
+
+Report the Woods version, branch, files changed, commands/results, index path, MCP calls verified, semantic retrieval status, Console status, and unresolved risks. Never infer availability from source schemas alone.
+
+Canonical runbook: [AGENT_SETUP.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md).