buildanything 2.0.0 → 2.1.1

package/agents/tech-feasibility.md

@@ -1,8 +1,10 @@
 ---
 name: tech-feasibility
-description: Evaluates technical architecture, hard problems, build-vs-buy decisions, MVP scope, and stack recommendations for a product idea. Use when assessing whether something can actually be built.
+description: Evaluates technical architecture, hard problems, build-vs-buy decisions, scope, and stack recommendations for a product idea. Use when assessing whether something can actually be built.
 tools: WebSearch, WebFetch, TodoWrite, Skill
 color: blue
+model: sonnet
+effort: medium
 ---
 
 You are a senior staff engineer doing a technical feasibility review. Think like a Stripe or Google infra engineer — pragmatic, opinionated, evidence-based.
@@ -44,8 +46,8 @@ You will receive an idea framed as an SCQA. Evaluate:
 - For each major component: existing service/API/library, or build from scratch?
 - Name specific tools. Search to verify they exist and are production-ready.
 
-### 4. MVP Scope
-- The absolute minimum build to test the hypothesis. Describe in under 50 words.
+### 4. Scope
+- The minimum build to test the hypothesis. Describe in under 50 words.
 - What can be faked, mocked, Wizard-of-Oz'd, or done manually at first?
 
 ### 5. Stack Recommendation

package/agents/testing-api-tester.md

@@ -4,6 +4,8 @@ description: Expert API testing specialist focused on comprehensive API validati
 color: purple
 emoji: 🔌
 vibe: Breaks your API before your users do.
+model: sonnet
+effort: medium
 ---
 
 # API Tester Agent Personality

package/agents/testing-evidence-collector.md

@@ -2,6 +2,8 @@
 name: testing-evidence-collector
 description: Screenshot-obsessed, fantasy-allergic QA specialist - Default to finding 3-5 issues, requires visual proof for everything
 color: orange
+model: sonnet
+effort: medium
 ---
 
 # Evidence Collector
@@ -109,3 +111,25 @@ Production Readiness: FAILED / NEEDS WORK / READY (default to FAILED)
 Status: FAILED (default unless overwhelming evidence otherwise)
 Re-test Required: YES
 ```
+
+## Dogfood Evidence Outputs (Step 5.3b)
+
+When dispatched for autonomous dogfooding (Phase 5 Step 5.3b), write three artifact groups under `docs/plans/evidence/dogfood/`:
+
+1. Screenshots — one PNG/JPG per finding, named after the `finding_id` (e.g. `DF-001.png`).
+2. `findings.md` — human-readable report with severity, description, repro steps, screenshot references.
+3. `findings.json` — machine-readable mirror of `findings.md` for graph indexing (Step 5.3b.idx). Schema:
+
+```json
+[
+  {
+    "finding_id": "DF-001",
+    "severity": "critical" | "major" | "minor",
+    "description": "User cannot complete checkout — Submit button unresponsive on Safari iOS",
+    "screenshot_path": "evidence/dogfood/checkout-submit-broken.png",
+    "affected_screen_id": "screen__checkout"
+  }
+]
+```
+
+Each finding gets a stable `finding_id` (`DF-001`, `DF-002`, …). `screenshot_path` is relative to project root and must point to an existing file in `evidence/dogfood/`. `affected_screen_id` matches a screen ID from the Slice 1 graph (`screen__<kebab>`); set null if the finding is not screen-specific. Both `findings.md` and `findings.json` are required — the Slice 5 indexer reads `findings.json` to wire `screenshot_evidences_finding` edges.

package/agents/testing-performance-benchmarker.md

@@ -2,6 +2,8 @@
 name: testing-performance-benchmarker
 description: Expert performance testing and optimization specialist focused on measuring, analyzing, and improving system performance across all applications and infrastructure
 color: orange
+model: sonnet
+effort: medium
 ---
 
 # Performance Benchmarker

package/agents/testing-reality-checker.md

@@ -2,7 +2,8 @@
 name: testing-reality-checker
 description: Stops fantasy approvals, evidence-based certification - Default to "NEEDS WORK", requires overwhelming proof for production readiness
 color: red
-model: opus
+model: sonnet
+effort: medium
 ---
 
 # Reality Checker

package/agents/visual-research.md

@@ -2,6 +2,8 @@
 name: visual-research
 description: Playwright-driven visual sweep of rival UIs or awards sites. Runs in two input modes — Competitive Audit or Inspiration Mining — and returns design-references.md grouped by DNA axis.
 color: blue
+model: sonnet
+effort: medium
 ---
 
 # Visual Research
@@ -21,10 +23,10 @@ Both modes run the same Playwright capture loop with different URL seeds.
 
 ## Inputs
 
-- Path to `visual-dna.md` — the locked 6-axis DNA card
+- Path to `DESIGN.md` — the locked 7-axis DNA lives in `## Overview > ### Brand DNA`
 - Mode flag: `competitive-audit` or `inspiration-mining`
 - Optional list of specific site URLs from the user or earlier research
-- Optional path to `findings-digest.md` (for competitor hints from Phase 1)
+- Optional path to `docs/plans/phase1-scratch/findings-digest.md` (for competitor hints from Phase 1)
 
 ## Core Responsibilities
 
@@ -45,13 +47,13 @@ Both modes run the same Playwright capture loop with different URL seeds.
 ## Workflow
 
 ### Shared setup
-1. Read `visual-dna.md`. Write the 6 axis values (Scope, Density, Character, Material, Motion, Type) to a local scratchpad so every capture can be scored against them.
+1. Read `DESIGN.md` `## Overview > ### Brand DNA`. Write the 7 axis values (Scope, Density, Character, Material, Motion, Type, Copy) to a local scratchpad so every capture can be scored against them.
 2. Pick the mode branch below based on the input flag.
 
 ### Competitive Audit mode
 3a. Build the candidate URL list:
    - Start with user-provided URLs if any
-   - Read `findings-digest.md` if present and pull named rivals
+   - Read `docs/plans/phase1-scratch/findings-digest.md` if present and pull named rivals
    - Otherwise, use WebFetch / WebSearch to find 10-15 products in the same category as the design-doc
 4a. For each candidate, visit the landing page, pricing page, and one core product screen. Score each against the 6 DNA axes on a 0-3 scale. Keep candidates with total ≥ 12.
 5a. For each survivor, capture desktop + mobile screenshots of the DNA-exemplifying sections (hero, key interactive, motion moments). Tag each capture with the DNA axis it exemplifies.
@@ -113,4 +115,4 @@ survivor_count: 6
 - Playwright MCP (primary) — `browser_navigate`, `browser_take_screenshot`, `browser_resize` for breakpoint parity
 - WebFetch / WebSearch for URL discovery
 - Write for the final `design-references.md`
-- Read for `visual-dna.md` and `findings-digest.md`
+- Read for `DESIGN.md` and `docs/plans/phase1-scratch/findings-digest.md`

package/bin/adapters/scribe-tool.ts

@@ -26,13 +26,15 @@ const rejectedAlternativeSchema = z.object({
 
 const scribeInputShape = {
   phase: z.string().min(1),
-  category: z.string().min(1),
   summary: z.string().min(1),
   decided_by: z.string().min(1),
   impact_level: z.enum(["low", "medium", "high", "critical"]),
   chosen_approach: z.string().min(1),
   rejected_alternatives: z.array(rejectedAlternativeSchema).max(3).optional(),
-  ref: z.string().optional(),
+  ref: z
+    .string()
+    .min(1)
+    .regex(/^[a-zA-Z0-9_\-./]+\.(md|json|jsonl|yaml|yml)(#[a-zA-Z0-9_\-/.]+)?$/),
 };
 
 export function buildScribeTool(tool: ToolConstructor, cwd: string) {

package/bin/adapters/write-lease-tool.ts

@@ -37,7 +37,7 @@ export function buildAcquireWriteLeaseTool(tool: ToolConstructor) {
     acquireInputShape,
     async (args) => {
       try {
-        const result = acquireWriteLease(args.task_id, args.file_paths);
+        const result = await acquireWriteLease(args.task_id, args.file_paths);
         return {
           content: [
             {

package/bin/buildanything-runtime.ts

@@ -2,6 +2,17 @@
 /*
  * buildanything runtime — entrypoint loaded by Claude Code plugin
  * when SDK mode is enabled.
+ *
+ * Responsibilities:
+ *   - schema_version forward-compat check on docs/plans/.build-state.json
+ *   - --resume stale-edge recovery (Task 4.3.4)
+ *   - SDK/host compat probe (sdkActive = state file + CLAUDE_CODE_VERSION ok)
+ *   - logging
+ *
+ * Orchestrator MCP tools (state_save, write_lease, cycle_counter, scribe) are
+ * served over stdio by bin/mcp-servers/orchestrator-mcp.ts — registered via
+ * .claude-plugin/plugin.json's mcpServers block and auto-started by Claude
+ * Code. This runtime no longer registers them in-process.
  */
 
 import process from "node:process";
@@ -203,113 +214,15 @@ async function main(): Promise<void> {
   const sdkActive = stateFileActive && hostCompat;
   console.log(`[buildanything-runtime] sdkActive=${sdkActive} (stateFile=${stateFileActive}, hostCompat=${hostCompat})`);
 
-  // [Task 1.2.4] scribe MCP registration
-  // [Task 2.3.4] write-lease MCP registration
-  // [Task 3.2.4] state-save MCP registration
-  // [Task 4.2.4] cycle-counter MCP registration
-  const mcpServers: Record<string, unknown> = {};
-  if (!sdkActive) {
-    console.log("[buildanything-runtime] sdk inactive — scribe + write-lease + state-save + cycle-counter MCP registration skipped (markdown mode)");
-  } else {
-    try {
-      const sdk = await import("@anthropic-ai/claude-agent-sdk");
-      const { buildScribeTool } = await import("./adapters/scribe-tool.js");
-      const scribeTool = buildScribeTool(sdk.tool, process.cwd());
-      mcpServers.scribe = sdk.createSdkMcpServer({
-        name: "scribe",
-        tools: [scribeTool],
-      });
-      console.log("[buildanything-runtime] scribe MCP server registered (tool: scribe_decision)");
-    } catch (err) {
-      console.warn(
-        `[buildanything-runtime] warning: scribe MCP registration failed (${(err as Error).message}); continuing in markdown mode`,
-      );
-    }
-
-    // Hydrate in-memory lease store from disk so it matches persisted state
-    // across runtime restarts. init() no-ops on missing file and swallows
-    // parse errors internally; we still guard so a surprise throw doesn't
-    // block MCP registration.
-    try {
-      const writeLeaseModule = await import("../src/orchestrator/mcp/write-lease.js");
-      writeLeaseModule.init(buildStatePath);
-    } catch (err) {
-      console.warn(
-        `[buildanything-runtime] warning: write-lease init failed (${(err as Error).message}); continuing with empty in-memory leases`,
-      );
-    }
-
-    try {
-      const sdk = await import("@anthropic-ai/claude-agent-sdk");
-      const {
-        buildAcquireWriteLeaseTool,
-        buildReleaseWriteLeaseTool,
-        buildListWriteLeasesTool,
-      } = await import("./adapters/write-lease-tool.js");
-      const acquireTool = buildAcquireWriteLeaseTool(sdk.tool);
-      const releaseTool = buildReleaseWriteLeaseTool(sdk.tool);
-      const listTool = buildListWriteLeasesTool(sdk.tool);
-      mcpServers.write_lease = sdk.createSdkMcpServer({
-        name: "write_lease",
-        tools: [acquireTool, releaseTool, listTool],
-      });
-      console.log(
-        "[buildanything-runtime] write-lease MCP server registered (tools: acquire_write_lease, release_write_lease, list_write_leases)",
-      );
-    } catch (err) {
-      console.warn(
-        `[buildanything-runtime] warning: write-lease MCP registration failed (${(err as Error).message}); continuing without lease enforcement`,
-      );
-    }
-
-    try {
-      const sdk = await import("@anthropic-ai/claude-agent-sdk");
-      const {
-        buildStateSaveTool,
-        buildStateReadTool,
-        buildVerifyIntegrityTool,
-      } = await import("./adapters/state-save-tool.js");
-      const saveTool = buildStateSaveTool(sdk.tool);
-      const readTool = buildStateReadTool(sdk.tool);
-      const verifyTool = buildVerifyIntegrityTool(sdk.tool);
-      mcpServers.state_save = sdk.createSdkMcpServer({
-        name: "state_save",
-        tools: [saveTool, readTool, verifyTool],
-      });
-      console.log(
-        "[buildanything-runtime] state-save MCP server registered (tools: state_save, state_read, verify_integrity)",
-      );
-    } catch (err) {
-      console.warn(
-        `[buildanything-runtime] warning: state-save MCP registration failed (${(err as Error).message}); continuing in markdown mode`,
-      );
-    }
-
-    try {
-      const sdk = await import("@anthropic-ai/claude-agent-sdk");
-      const {
-        buildCycleCounterCheckTool,
-        buildClearInFlightEdgeTool,
-        buildHandleStaleEdgeTool,
-      } = await import("./adapters/cycle-counter-tool.js");
-      const checkTool = buildCycleCounterCheckTool(sdk.tool);
-      const clearTool = buildClearInFlightEdgeTool(sdk.tool);
-      const staleTool = buildHandleStaleEdgeTool(sdk.tool);
-      mcpServers.cycle_counter = sdk.createSdkMcpServer({
-        name: "cycle_counter",
-        tools: [checkTool, clearTool, staleTool],
-      });
-      console.log(
-        "[buildanything-runtime] cycle-counter MCP server registered (tools: cycle_counter_check, clear_in_flight_edge, handle_stale_edge)",
-      );
-    } catch (err) {
-      console.warn(
-        `[buildanything-runtime] warning: cycle-counter MCP registration failed (${(err as Error).message}); continuing without cycle enforcement`,
-      );
-    }
-  }
-
-  void mcpServers;
+  // Orchestrator MCP tools (scribe_decision [Task 1.2.4], acquire/release/list
+  // write-lease [Task 2.3.4], state_save/state_read/verify_integrity [Task
+  // 3.2.4], cycle_counter_check/clear_in_flight_edge/handle_stale_edge [Task
+  // 4.2.4]) are served over stdio by bin/mcp-servers/orchestrator-mcp.ts,
+  // registered through .claude-plugin/plugin.json's mcpServers block. The
+  // Agent SDK path no longer owns these tools — stdio is the single source.
+  // The adapters in bin/adapters/*.ts remain for any future in-process SDK
+  // path that wants to share the zod shapes.
+  void sdkActive;
 }
 
 function isCliEntry(): boolean {

package/bin/graph-index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin shim: delegates to the graph indexer TypeScript entry via tsx.
+const { spawn } = require('child_process');
+const path = require('path');
+
+const tsEntry = path.join(__dirname, 'graph-index.ts');
+const child = spawn('npx', ['--no-install', 'tsx', tsEntry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+child.on('error', (err) => {
+  process.stderr.write(`[graph-index shim] failed to spawn tsx: ${err.message}\n`);
+  process.exit(1);
+});

package/bin/graph-index.ts

@@ -0,0 +1,340 @@
+#!/usr/bin/env tsx
+
+import { readFileSync, statSync, readdirSync, existsSync, unlinkSync } from "node:fs";
+import { basename, resolve, join, relative, extname } from "node:path";
+import { createHash } from "node:crypto";
+import process from "node:process";
+import { extractProductSpec, extractDesignMd, extractDesignMdTokens, extractComponentManifest, extractPageSpec, extractArchitecture, extractSprintTasks, extractDecisionsJsonl, extractScreenshot, saveGraph } from "../src/graph/index.js";
+import type { GraphFragment } from "../src/graph/types.js";
+
+type ImageClass = "reference" | "brand_drift" | "dogfood";
+
+const VALID_IMAGE_CLASSES: ReadonlySet<string> = new Set(["reference", "brand_drift", "dogfood"]);
+const IMAGE_EXTENSIONS: ReadonlySet<string> = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
+
+function parseArgs(argv: string[]): { positional: string[]; imageClass: string | undefined } {
+  const positional: string[] = [];
+  let imageClass: string | undefined;
+  for (const arg of argv) {
+    if (arg.startsWith("--image-class=")) {
+      imageClass = arg.slice("--image-class=".length);
+    } else if (arg === "--image-class") {
+      // peek-ahead style not supported; require =VALUE form
+      process.stderr.write("[graph-index] error: --image-class requires =VALUE form (e.g. --image-class=reference)\n");
+      process.exit(64);
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, imageClass };
+}
+
+function inferImageClassFromPath(absPath: string): ImageClass | null {
+  // Normalize trailing slash + lower-case scan against known suffixes.
+  const normalized = absPath.replace(/\/+$/, "");
+  if (normalized.endsWith("/design-references") || normalized.includes("/design-references/")) {
+    return "reference";
+  }
+  if (normalized.endsWith("/evidence/brand-drift") || normalized.includes("/evidence/brand-drift/")) {
+    return "brand_drift";
+  }
+  if (normalized.endsWith("/evidence/dogfood") || normalized.includes("/evidence/dogfood/")) {
+    return "dogfood";
+  }
+  return null;
+}
+
+function targetFileForClass(c: ImageClass): string {
+  switch (c) {
+    case "reference": return "slice-5-references.json";
+    case "brand_drift": return "slice-5-brand-drift.json";
+    case "dogfood": return "slice-5-dogfood.json";
+  }
+}
+
+function collectImageFiles(dir: string): string[] {
+  const files: string[] = [];
+  // Recurse one level — competitors/, inspiration/, screenshots/ subdirs are common.
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      try {
+        for (const sub of readdirSync(full, { withFileTypes: true })) {
+          if (sub.isFile() && IMAGE_EXTENSIONS.has(extname(sub.name).toLowerCase())) {
+            files.push(join(full, sub.name));
+          }
+        }
+      } catch { /* unreadable subdir */ }
+    } else if (entry.isFile() && IMAGE_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+      files.push(full);
+    }
+  }
+  return files.sort();
+}
+
+function indexImageDirectory(absPath: string, imageClass: ImageClass): void {
+  // TODO Slice 5 production: when imageClass === 'dogfood', read evidence/dogfood/findings.json side-channel to populate linked_finding_id per screenshot.
+  const imageFiles = collectImageFiles(absPath);
+
+  if (imageFiles.length === 0) {
+    // Per Slice 5 schema §11 scenario 1: empty directory writes empty fragment, does NOT fail.
+    process.stdout.write(`[graph-index] info — no images in ${absPath}, writing empty fragment\n`);
+  }
+
+  const allNodes: GraphFragment["nodes"] = [];
+  const allEdges: GraphFragment["edges"] = [];
+  const hashChunks: Buffer[] = [];
+  const warnings: string[] = [];
+  let successCount = 0;
+
+  for (const filePath of imageFiles) {
+    let bytes: Buffer;
+    try {
+      bytes = readFileSync(filePath);
+    } catch (err) {
+      const msg = `failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+      process.stderr.write(`[graph-index] warning: ${msg}\n`);
+      warnings.push(msg);
+      continue;
+    }
+    hashChunks.push(bytes);
+
+    try {
+      const result = extractScreenshot({
+        imagePath: relative(process.cwd(), filePath),
+        imageClass,
+        imageBytes: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+      });
+
+      if (!result.ok) {
+        const msg = `${filePath}: ${result.errors.map((e) => e.message).join("; ")}`;
+        warnings.push(msg);
+        continue;
+      }
+      allNodes.push(...result.nodes);
+      allEdges.push(...result.edges);
+      successCount++;
+    } catch (err) {
+      const msg = `${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+      warnings.push(msg);
+      continue;
+    }
+  }
+
+  if (imageFiles.length > 0 && successCount === 0) {
+    for (const w of warnings) {
+      process.stderr.write(`[graph-index] warning: ${w}\n`);
+    }
+    process.exit(1);
+  }
+
+  const combined = Buffer.concat(hashChunks);
+  const combinedHash = combined.length > 0
+    ? createHash("sha256").update(combined).digest("hex")
+    : "0".repeat(64);
+
+  const relDir = relative(process.cwd(), absPath) + "/";
+
+  const fragment: GraphFragment = {
+    source_file: relDir,
+    source_sha: combinedHash,
+    produced_at: new Date().toISOString(),
+    version: 1,
+    schema: "buildanything-slice-5",
+    nodes: allNodes,
+    edges: allEdges,
+  };
+
+  const targetFile = targetFileForClass(imageClass);
+  saveGraph(process.cwd(), fragment, targetFile);
+  process.stdout.write(
+    `[graph-index] ok — ${fragment.nodes.length} nodes, ${fragment.edges.length} edges → .buildanything/graph/${targetFile}\n`,
+  );
+
+  if (imageFiles.length > 0) {
+    for (const w of warnings) {
+      process.stdout.write(`[graph-index] warning: ${w}\n`);
+    }
+    process.stdout.write(`[graph-index] indexed ${successCount}/${imageFiles.length} images; ${warnings.length} warnings\n`);
+  }
+}
+
+const { positional, imageClass: explicitImageClass } = parseArgs(process.argv.slice(2));
+const target = positional[0];
+
+if (!target) {
+  process.stderr.write(
+    "Usage: graph-index <path> [--image-class=reference|brand_drift|dogfood]\n" +
+    "  Recognized basenames: product-spec.md, DESIGN.md, component-manifest.md, architecture.md, sprint-tasks.md, decisions.jsonl\n" +
+    "  Directory mode: page-specs/ → indexes all *.md files inside\n" +
+    "  Image directory mode: design-references/ | evidence/brand-drift/ | evidence/dogfood/ → indexes all images\n" +
+    "  DESIGN.md produces both slice-2-dna.json (Pass 1) and slice-3-tokens.json (Pass 2, if tokens found)\n",
+  );
+  process.exit(64);
+}
+
+if (explicitImageClass !== undefined && !VALID_IMAGE_CLASSES.has(explicitImageClass)) {
+  process.stderr.write(`[graph-index] error: --image-class must be one of: reference, brand_drift, dogfood (got: ${explicitImageClass})\n`);
+  process.exit(64);
+}
+
+try {
+  const absPath = resolve(target);
+
+  // ── Directory mode ──────────────────────────────────────────────────
+  let isDir = false;
+  try { isDir = statSync(absPath).isDirectory(); } catch { /* not a dir */ }
+
+  if (isDir) {
+    // page-specs/ — Slice 3 markdown directory mode
+    if (basename(absPath) === "page-specs") {
+      const mdFiles = readdirSync(absPath)
+        .filter((f) => f.endsWith(".md"))
+        .sort();
+
+      if (mdFiles.length === 0) {
+        process.stderr.write(`[graph-index] error: no .md files found in directory: ${absPath}\n`);
+        process.exit(1);
+      }
+
+      const allNodes: GraphFragment["nodes"] = [];
+      const allEdges: GraphFragment["edges"] = [];
+      const contents: string[] = [];
+
+      for (const file of mdFiles) {
+        const filePath = join(absPath, file);
+        const content = readFileSync(filePath, "utf-8");
+        contents.push(content);
+        const result = extractPageSpec({ mdPath: filePath, mdContent: content });
+        if (!result.ok) {
+          for (const err of result.errors) {
+            process.stderr.write(`[graph-index] ${file} L${err.line}: ${err.message}\n`);
+          }
+          process.stderr.write(`[graph-index] fatal: page-spec parse failed for ${file}\n`);
+          process.exit(1);
+        }
+        allNodes.push(...result.fragment!.nodes);
+        allEdges.push(...result.fragment!.edges);
+      }
+
+      const combinedHash = createHash("sha256").update(contents.join("")).digest("hex");
+      const relDir = relative(process.cwd(), absPath) + "/";
+
+      const fragment: GraphFragment = {
+        source_file: relDir,
+        source_sha: combinedHash,
+        produced_at: new Date().toISOString(),
+        version: 1,
+        schema: "buildanything-slice-3",
+        nodes: allNodes,
+        edges: allEdges,
+      };
+
+      saveGraph(process.cwd(), fragment, "slice-3-pages.json");
+      process.stdout.write(
+        `[graph-index] ok — ${fragment.nodes.length} nodes, ${fragment.edges.length} edges → .buildanything/graph/slice-3-pages.json\n`,
+      );
+      process.exit(0);
+    }
+
+    // Slice 5 image-directory mode — explicit override OR path inference
+    const inferred = inferImageClassFromPath(absPath);
+    const resolvedClass = (explicitImageClass ?? inferred) as ImageClass | null;
+
+    if (resolvedClass !== null) {
+      indexImageDirectory(absPath, resolvedClass);
+      process.exit(0);
+    }
+
+    process.stderr.write(
+      `[graph-index] error: directory ${absPath} is not a recognized indexer target.\n` +
+      `  Markdown directory: page-specs/\n` +
+      `  Image directories (auto-detected): design-references/, evidence/brand-drift/, evidence/dogfood/\n` +
+      `  Or pass --image-class=reference|brand_drift|dogfood to force.\n`,
+    );
+    process.exit(64);
+  }
+
+  // ── File mode ───────────────────────────────────────────────────────
+  if (!(() => { try { readFileSync(absPath); return true; } catch { return false; } })()) {
+    process.stderr.write(
+      "Usage: graph-index <path>\n" +
+      "  Recognized basenames: product-spec.md, DESIGN.md, component-manifest.md, architecture.md, sprint-tasks.md, decisions.jsonl\n" +
+      "  Directory mode: pass a page-specs/ directory to index all *.md files inside\n",
+    );
+    process.exit(64);
+  }
+
+  const mdContent = readFileSync(absPath, "utf-8");
+  const base = basename(absPath);
+
+  let result;
+  let targetFile: string;
+  if (base === "product-spec.md") {
+    result = extractProductSpec({ mdPath: absPath, mdContent });
+    targetFile = "slice-1.json";
+  } else if (base === "DESIGN.md") {
+    result = extractDesignMd({ mdPath: absPath, mdContent });
+    targetFile = "slice-2-dna.json";
+  } else if (base === "component-manifest.md") {
+    result = extractComponentManifest({ mdPath: absPath, mdContent });
+    targetFile = "slice-2-manifest.json";
+  } else if (base === "architecture.md") {
+    result = extractArchitecture({ mdPath: absPath, mdContent });
+    targetFile = "slice-4-architecture.json";
+  } else if (base === "sprint-tasks.md") {
+    result = extractSprintTasks({ mdPath: absPath, mdContent });
+    targetFile = "slice-4-tasks.json";
+  } else if (base === "decisions.jsonl") {
+    result = extractDecisionsJsonl({ mdPath: absPath, mdContent });
+    targetFile = "slice-4-decisions.json";
+  } else {
+    process.stderr.write(
+      `Usage: graph-index <path>\n  Recognized basenames: product-spec.md, DESIGN.md, component-manifest.md, architecture.md, sprint-tasks.md, decisions.jsonl\n  Directory mode: pass a page-specs/ directory to index all *.md files inside\n  Got: ${base}\n`,
+    );
+    process.exit(64);
+  }
+
+  if (result.ok) {
+    const fragment = result.fragment!;
+    saveGraph(process.cwd(), fragment, targetFile);
+    process.stdout.write(
+      `[graph-index] ok — ${fragment.nodes.length} nodes, ${fragment.edges.length} edges → .buildanything/graph/${targetFile}\n`,
+    );
+  } else {
+    for (const err of result.errors) {
+      process.stderr.write(`[graph-index] L${err.line}: ${err.message}\n`);
+    }
+    process.exit(1);
+  }
+
+  // ── DESIGN.md Pass 2: tokens ────────────────────────────────────────
+  if (base === "DESIGN.md") {
+    const pass2 = extractDesignMdTokens({ mdPath: absPath, mdContent });
+    if (pass2.ok && pass2.fragment!.nodes.length > 0) {
+      saveGraph(process.cwd(), pass2.fragment!, "slice-3-tokens.json");
+      process.stdout.write(
+        `[graph-index] ok — ${pass2.fragment!.nodes.length} nodes, ${pass2.fragment!.edges.length} edges → .buildanything/graph/slice-3-tokens.json\n`,
+      );
+    } else if (!pass2.ok) {
+      for (const err of pass2.errors) {
+        process.stderr.write(`[graph-index] warning (Pass 2): L${err.line}: ${err.message}\n`);
+      }
+    }
+
+    if ((pass2.ok && pass2.fragment!.nodes.length === 0) || !pass2.ok) {
+      const stalePath = join(process.cwd(), ".buildanything", "graph", "slice-3-tokens.json");
+      try {
+        if (existsSync(stalePath)) {
+          unlinkSync(stalePath);
+          process.stdout.write("[graph-index] Pass 2 empty — removed stale slice-3-tokens.json\n");
+        }
+      } catch { /* best-effort */ }
+    }
+  }
+} catch (e: unknown) {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`[graph-index] fatal: ${msg}\n`);
+  process.exit(2);
+}