refactor(skill): split SKILL.md sections >500 lines into recipe files

understand-anything-plugin/skills/understand/recipes/fingerprints-baseline.md

@@ -0,0 +1,26 @@
+# Recipe: Phase 7 Structural Fingerprints Baseline
+
+> Builds the fingerprint baseline that future auto-update runs compare against. Referenced from `SKILL.md` Phase 7 step 2 (Generate structural fingerprints baseline).
+
+Generate structural fingerprints baseline. This creates the basis for future automatic incremental updates and **must succeed before `meta.json` is written** — otherwise auto-update sees a fresh commit hash with no fingerprints to compare against, classifies every file as STRUCTURAL, and escalates to `FULL_UPDATE` on every subsequent commit (issue #152).
+
+Write the input file:
+```bash
+cat > $PROJECT_ROOT/.understand-anything/intermediate/fingerprint-input.json <<EOF
+{
+  "projectRoot": "$PROJECT_ROOT",
+  "sourceFilePaths": [<all source file paths from Phase 1, as JSON array>],
+  "gitCommitHash": "<current commit hash>"
+}
+EOF
+```
+
+Then invoke the bundled script (located next to this SKILL.md):
+```bash
+node <SKILL_DIR>/build-fingerprints.mjs \
+  $PROJECT_ROOT/.understand-anything/intermediate/fingerprint-input.json
+```
+
+The script uses `TreeSitterPlugin + PluginRegistry` exactly like `extract-structure.mjs`, so the baseline matches the comparison logic used during auto-updates.
+
+**If the script exits non-zero or stdout does not include `Fingerprints baseline:`, abort Phase 7 and report the error. Do NOT proceed to write `meta.json`.**

understand-anything-plugin/skills/understand/recipes/incremental-update.md

@@ -0,0 +1,27 @@
+# Recipe: Phase 2 Incremental Update Path
+
+> The "Incremental update path" branch of Phase 2 — how to re-batch only changed files, prune the prior graph, and re-merge. Referenced from `SKILL.md` Phase 2 → "Incremental update path".
+
+Write the changed-files list (one path per line) to a temp file:
+```bash
+git diff <lastCommitHash>..HEAD --name-only > $PROJECT_ROOT/.understand-anything/tmp/changed-files.txt
+```
+
+Run compute-batches with `--changed-files`:
+```bash
+node <SKILL_DIR>/compute-batches.mjs $PROJECT_ROOT \
+  --changed-files=$PROJECT_ROOT/.understand-anything/tmp/changed-files.txt
+```
+
+This produces a `batches.json` that contains only batches with changed files, but neighborMap entries still reference unchanged files (with their full-graph batchIndex) so cross-batch edges remain emittable.
+
+Then dispatch file-analyzer subagents per the same template as the full path.
+
+After batches complete:
+1. Remove old nodes whose `filePath` matches any changed file from the existing graph
+2. Remove old edges whose `source` or `target` references a removed node
+3. Write the pruned existing nodes/edges as `batch-existing.json` in the intermediate directory
+4. Run the same merge script — it will combine `batch-existing.json` with the fresh `batch-*.json` files:
+   ```bash
+   python <SKILL_DIR>/merge-batch-graphs.py $PROJECT_ROOT
+   ```

understand-anything-plugin/skills/understand/recipes/inline-validator.md

@@ -0,0 +1,80 @@
+# Recipe: Inline Deterministic Graph Validator
+
+> The Node.js script written to `$PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs` for the default (non-`--review`) Phase 6 path. Referenced from `SKILL.md` Phase 6 → "Default path (no `--review`): inline deterministic validation".
+
+Write the following Node.js script to `$PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs`:
+
+```javascript
+#!/usr/bin/env node
+const fs = require('fs');
+const graphPath = process.argv[2];
+const outputPath = process.argv[3];
+try {
+  const graph = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
+  const issues = [], warnings = [];
+  if (!Array.isArray(graph.nodes)) { issues.push('graph.nodes is missing or not an array'); graph.nodes = []; }
+  if (!Array.isArray(graph.edges)) { issues.push('graph.edges is missing or not an array'); graph.edges = []; }
+  const nodeIds = new Set();
+  const seen = new Map();
+  graph.nodes.forEach((n, i) => {
+    if (!n.id) { issues.push(`Node[${i}] missing id`); return; }
+    if (!n.type) issues.push(`Node[${i}] '${n.id}' missing type`);
+    if (!n.name) issues.push(`Node[${i}] '${n.id}' missing name`);
+    if (!n.summary) issues.push(`Node[${i}] '${n.id}' missing summary`);
+    if (!n.tags || !n.tags.length) issues.push(`Node[${i}] '${n.id}' missing tags`);
+    if (seen.has(n.id)) issues.push(`Duplicate node ID '${n.id}' at indices ${seen.get(n.id)} and ${i}`);
+    else seen.set(n.id, i);
+    nodeIds.add(n.id);
+  });
+  graph.edges.forEach((e, i) => {
+    if (!nodeIds.has(e.source)) issues.push(`Edge[${i}] source '${e.source}' not found`);
+    if (!nodeIds.has(e.target)) issues.push(`Edge[${i}] target '${e.target}' not found`);
+  });
+  const fileLevelTypes = new Set(['file', 'config', 'document', 'service', 'pipeline', 'table', 'schema', 'resource', 'endpoint']);
+  const fileNodes = graph.nodes.filter(n => fileLevelTypes.has(n.type)).map(n => n.id);
+  const assigned = new Map();
+  if (!Array.isArray(graph.layers)) { if (graph.layers) warnings.push('graph.layers is not an array'); graph.layers = []; }
+  if (!Array.isArray(graph.tour)) { if (graph.tour) warnings.push('graph.tour is not an array'); graph.tour = []; }
+  graph.layers.forEach(layer => {
+    (layer.nodeIds || []).forEach(id => {
+      if (!nodeIds.has(id)) issues.push(`Layer '${layer.id}' refs missing node '${id}'`);
+      if (assigned.has(id)) issues.push(`Node '${id}' appears in multiple layers`);
+      assigned.set(id, layer.id);
+    });
+  });
+  fileNodes.forEach(id => {
+    if (!assigned.has(id)) issues.push(`File node '${id}' not in any layer`);
+  });
+  graph.tour.forEach((step, i) => {
+    (step.nodeIds || []).forEach(id => {
+      if (!nodeIds.has(id)) issues.push(`Tour step[${i}] refs missing node '${id}'`);
+    });
+  });
+  const withEdges = new Set([
+    ...graph.edges.map(e => e.source),
+    ...graph.edges.map(e => e.target)
+  ]);
+  graph.nodes.forEach(n => {
+    if (!withEdges.has(n.id)) warnings.push(`Node '${n.id}' has no edges (orphan)`);
+  });
+  const stats = {
+    totalNodes: graph.nodes.length,
+    totalEdges: graph.edges.length,
+    totalLayers: graph.layers.length,
+    tourSteps: graph.tour.length,
+    nodeTypes: graph.nodes.reduce((a, n) => { a[n.type] = (a[n.type]||0)+1; return a; }, {}),
+    edgeTypes: graph.edges.reduce((a, e) => { a[e.type] = (a[e.type]||0)+1; return a; }, {})
+  };
+  fs.writeFileSync(outputPath, JSON.stringify({ issues, warnings, stats }, null, 2));
+  process.exit(0);
+} catch (err) { process.stderr.write(err.message + '\n'); process.exit(1); }
+```
+
+Execute it:
+```bash
+node $PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs \
+  "$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json" \
+  "$PROJECT_ROOT/.understand-anything/intermediate/review.json"
+```
+
+If the script exits non-zero, read stderr, fix the script, and retry once.

understand-anything-plugin/skills/understand/recipes/intermediate-cleanup.md

@@ -0,0 +1,17 @@
+# Recipe: Phase 7 Intermediate Cleanup
+
+> Cleans up `.understand-anything/intermediate/` while preserving `scan-result.json`. Referenced from `SKILL.md` Phase 7 step 4.
+
+Clean up intermediate files, **preserving `scan-result.json`** so future incremental runs can skip Phase 1 SCAN (see issue #293):
+
+```bash
+# Preserve scan-result.json — Phase 1's deterministic file inventory.
+# Future incremental runs (Phase 2 compute-batches.mjs --changed-files=…)
+# need this inventory; without it, Phase 1 must re-dispatch and pay ~157k
+# tokens / ~158s per incremental run.
+INTER="$PROJECT_ROOT/.understand-anything/intermediate"
+if [ -d "$INTER" ]; then
+  find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-result.json' -exec rm -rf {} +
+fi
+rm -rf $PROJECT_ROOT/.understand-anything/tmp
+```

understand-anything-plugin/skills/understand/recipes/llm-review-path.md

@@ -0,0 +1,26 @@
+# Recipe: Phase 6 `--review` Path (LLM Graph Reviewer)
+
+> The alternative Phase 6 validation branch when `--review` is in `$ARGUMENTS`. Dispatches the LLM `graph-reviewer` subagent instead of the inline deterministic validator. Referenced from `SKILL.md` Phase 6 → "`--review` path: full LLM reviewer".
+
+If `--review` IS in `$ARGUMENTS`, dispatch the LLM graph-reviewer subagent as follows:
+
+Dispatch a subagent using the `graph-reviewer` agent definition (at `agents/graph-reviewer.md`). Append the following additional context:
+
+> **Additional context from main session:**
+>
+> Phase 1 scan results (file inventory):
+> ```json
+> [list of {path, sizeLines} from scan-result.json]
+> ```
+>
+> Phase warnings/errors accumulated during analysis:
+> - [list any batch failures, skipped files, or warnings from Phases 2-5]
+>
+> Cross-validate: every file in the scan inventory should have a corresponding node in the graph (node types may vary: `file:`, `config:`, `document:`, `service:`, `pipeline:`, `table:`, `schema:`, `resource:`, `endpoint:`). Flag any missing files. Also flag any graph nodes whose `filePath` doesn't appear in the scan inventory.
+
+Pass these parameters in the dispatch prompt:
+
+> Validate the knowledge graph at `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`.
+> Project root: `$PROJECT_ROOT`
+> Read the file and validate it for completeness and correctness.
+> Write output to: `$PROJECT_ROOT/.understand-anything/intermediate/review.json`

understand-anything-plugin/skills/understand/recipes/plugin-root-resolution.md

@@ -0,0 +1,51 @@
+# Recipe: Plugin Root Resolution and Build Check
+
+> Resolves the `understand-anything` plugin root across install locations, then ensures `@understand-anything/core` is built. Referenced from `SKILL.md` Phase 0 step 1.5 (Ensure the plugin is built).
+
+**Important:** do **not** assume the plugin root is simply two directories above the skill path string. In many installations `~/.agents/skills/understand` is a symlink into the real plugin checkout. Prefer runtime-provided plugin roots first (for Claude), then fall back to universal symlinks, skill symlink resolution, and common clone-based install paths.
+
+Resolve the plugin root like this:
+
+```bash
+SKILL_REAL=$(realpath ~/.agents/skills/understand 2>/dev/null || readlink -f ~/.agents/skills/understand 2>/dev/null || echo "")
+SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
+COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand 2>/dev/null || readlink -f ~/.copilot/skills/understand 2>/dev/null || echo "")
+COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
+
+PLUGIN_ROOT=""
+for candidate in \
+  "${CLAUDE_PLUGIN_ROOT}" \
+  "$HOME/.understand-anything-plugin" \
+  "$SELF_RELATIVE" \
+  "$COPILOT_SELF_RELATIVE" \
+  "$HOME/.codex/understand-anything/understand-anything-plugin" \
+  "$HOME/.opencode/understand-anything/understand-anything-plugin" \
+  "$HOME/.pi/understand-anything/understand-anything-plugin" \
+  "$HOME/understand-anything/understand-anything-plugin"; do
+  if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && [ -f "$candidate/pnpm-workspace.yaml" ]; then
+    PLUGIN_ROOT="$candidate"
+    break
+  fi
+done
+
+if [ -z "$PLUGIN_ROOT" ]; then
+  echo "Error: Cannot find the understand-anything plugin root."
+  echo "Checked:"
+  echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
+  echo "  - $HOME/.understand-anything-plugin"
+  echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand>}"
+  echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand>}"
+  echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
+  echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
+  echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
+  echo "  - $HOME/understand-anything/understand-anything-plugin"
+  echo "Make sure the plugin is installed correctly."
+  exit 1
+fi
+
+if [ ! -f "$PLUGIN_ROOT/packages/core/dist/index.js" ]; then
+  cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build
+fi
+```
+
+If `pnpm` is missing, report to the user: "Install Node.js ≥ 22 and pnpm ≥ 10, then re-run `/understand`."

understand-anything-plugin/skills/understand/recipes/understandignore-generator.md

@@ -0,0 +1,30 @@
+# Recipe: Generate `.understandignore` Starter File
+
+> One-shot Node.js script that synthesizes a starter `.understandignore` from `.gitignore` and detected directories. Referenced from `SKILL.md` Phase 0.5 step 2 (If `.understandignore` does not exist, generate a starter file).
+
+Run the following Node.js one-liner in `$PROJECT_ROOT` (reads `.gitignore` and deduplicates against built-in defaults):
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+const root = process.cwd();
+const defaults = ['node_modules/','node_modules','.git/','vendor/','venv/','.venv/','__pycache__/','dist/','dist','build/','build','out/','coverage/','coverage','.next/','.cache/','.turbo/','target/','obj/','*.lock','package-lock.json','yarn.lock','pnpm-lock.yaml','*.png','*.jpg','*.jpeg','*.gif','*.svg','*.ico','*.woff','*.woff2','*.ttf','*.eot','*.mp3','*.mp4','*.pdf','*.zip','*.tar','*.gz','*.min.js','*.min.css','*.map','*.generated.*','.idea/','.vscode/','LICENSE','.gitignore','.editorconfig','.prettierrc','.eslintrc*','*.log'];
+const norm = p => p.replace(/\/+$/, '');
+const defaultSet = new Set(defaults.map(norm));
+const header = '# .understandignore — patterns for files/dirs to exclude from analysis\n# Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs)\n# Lines below are suggestions — uncomment to activate.\n# Use ! prefix to force-include something excluded by defaults.\n#\n# Built-in defaults (always excluded unless negated):\n#   node_modules/, .git/, dist/, build/, obj/, *.lock, *.min.js, etc.\n#\n';
+let body = '';
+const gitignorePath = path.join(root, '.gitignore');
+if (fs.existsSync(gitignorePath)) {
+  const gi = fs.readFileSync(gitignorePath, 'utf-8').split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#')).filter(p => !defaultSet.has(norm(p)));
+  if (gi.length) { body += '# --- From .gitignore (uncomment to exclude) ---\n\n' + gi.map(p => '# ' + p).join('\n') + '\n\n'; }
+}
+const dirs = ['__tests__','test','tests','fixtures','testdata','docs','examples','scripts','migrations','.storybook'];
+const found = dirs.filter(d => fs.existsSync(path.join(root, d)));
+if (found.length) { body += '# --- Detected directories (uncomment to exclude) ---\n\n' + found.map(d => '# ' + d + '/').join('\n') + '\n\n'; }
+body += '# --- Test file patterns (uncomment to exclude) ---\n\n# *.test.*\n# *.spec.*\n# *.snap\n';
+const outDir = path.join(root, '.understand-anything');
+if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+fs.writeFileSync(path.join(outDir, '.understandignore'), header + body);
+"
+```

understand-anything-plugin/skills/understand/recipes/worktree-redirect.md

@@ -0,0 +1,25 @@
+# Recipe: Worktree Redirect
+
+> Detects whether `PROJECT_ROOT` is a git worktree and redirects output to the main repo root. Referenced from `SKILL.md` Phase 0 step 1 (Resolve `PROJECT_ROOT`).
+
+If `PROJECT_ROOT` is inside a git worktree (not the main checkout), redirect output to the main repository root. Worktrees managed by Claude Code are ephemeral — `.understand-anything/` written there is destroyed when the session ends, taking the knowledge graph with it (issue #133). Detect a worktree by comparing `git rev-parse --git-dir` against `git rev-parse --git-common-dir`; in a normal checkout or submodule they resolve to the same path, in a worktree they differ and the parent of `--git-common-dir` is the main repo root.
+
+```bash
+COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
+GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)
+if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
+  COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
+  GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" 2>/dev/null && pwd -P)
+  if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
+    MAIN_ROOT=$(dirname "$COMMON_ABS")
+    if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
+      echo "[understand] Detected git worktree at $PROJECT_ROOT"
+      echo "[understand] Redirecting output to main repo root: $MAIN_ROOT"
+      echo "[understand] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
+      PROJECT_ROOT="$MAIN_ROOT"
+    fi
+  fi
+fi
+```
+
+Set `UNDERSTAND_NO_WORKTREE_REDIRECT=1` if you intentionally want a per-worktree graph (rare — most users want the redirect).

understand-anything-plugin/skills/understand/reference/knowledge-graph-schema.md

@@ -0,0 +1,45 @@
+# Reference: KnowledgeGraph Schema
+
+> Authoritative node-type, edge-type, and edge-weight tables for the assembled `knowledge-graph.json`. Referenced from `SKILL.md` "Reference: KnowledgeGraph Schema".
+
+## Node Types (13 total)
+
+| Type | Description | ID Convention |
+|---|---|---|
+| `file` | Source code file | `file:<relative-path>` |
+| `function` | Function or method | `function:<relative-path>:<name>` |
+| `class` | Class, interface, or type | `class:<relative-path>:<name>` |
+| `module` | Logical module or package | `module:<name>` |
+| `concept` | Abstract concept or pattern | `concept:<name>` |
+| `config` | Configuration file (YAML, JSON, TOML, env) | `config:<relative-path>` |
+| `document` | Documentation file (Markdown, RST, TXT) | `document:<relative-path>` |
+| `service` | Deployable service definition (Dockerfile, K8s) | `service:<relative-path>` |
+| `table` | Database table or migration | `table:<relative-path>:<table-name>` |
+| `endpoint` | API endpoint or route definition | `endpoint:<relative-path>:<endpoint-name>` |
+| `pipeline` | CI/CD pipeline configuration | `pipeline:<relative-path>` |
+| `schema` | Schema definition (GraphQL, Protobuf, Prisma) | `schema:<relative-path>` |
+| `resource` | Infrastructure resource (Terraform, CloudFormation) | `resource:<relative-path>` |
+
+## Edge Types (26 total)
+
+| Category | Types |
+|---|---|
+| Structural | `imports`, `exports`, `contains`, `inherits`, `implements` |
+| Behavioral | `calls`, `subscribes`, `publishes`, `middleware` |
+| Data flow | `reads_from`, `writes_to`, `transforms`, `validates` |
+| Dependencies | `depends_on`, `tested_by`, `configures` |
+| Semantic | `related`, `similar_to` |
+| Infrastructure | `deploys`, `serves`, `provisions`, `triggers` |
+| Schema/Data | `migrates`, `documents`, `routes`, `defines_schema` |
+
+## Edge Weight Conventions
+
+| Edge Type | Weight |
+|---|---|
+| `contains` | 1.0 |
+| `inherits`, `implements` | 0.9 |
+| `calls`, `exports`, `defines_schema` | 0.8 |
+| `imports`, `deploys`, `migrates` | 0.7 |
+| `depends_on`, `configures`, `triggers` | 0.6 |
+| `tested_by`, `documents`, `provisions`, `serves`, `routes` | 0.5 |
+| All others | 0.5 (default) |