start-vibing 4.3.1 → 4.3.3

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "start-vibing",
-	"version": "4.3.1",
-	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. super-design 0.6.1: compass-artifact alignment — WCAG 2.2 SCs, CrUX field data, tool triangulation, Baymard sub-rules, Doherty/Tesler/Postel rationale, atomic state write, unshallow ladder.",
+	"version": "4.3.3",
+	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. super-design 0.6.3: DSC-choice active selection — score-typeui.mjs ranks 12 typeui-* skills by 7-axis fingerprint (density/contrast/geometry/color/typography/motion/audience) from findings+DIS, top-3 written to typeui-proposal.json with copy-paste CLI; harvest-typeui.sh pulls typeui.sh catalog + vercel-labs/anthropic fallbacks; sd-fix --typeui <name> rebrands V1-V8 fixes to snap spacing/color/radius to chosen direction's tokens.",
 	"type": "module",
 	"bin": {
 		"start-vibing": "./dist/cli.js"

package/template/.claude/skills/super-design/SKILL.md

@@ -8,7 +8,7 @@ description: >
   UX audit (WCAG 2.2 AA, Nielsen heuristics, Baymard, CWV), and synthesized
   overview. Re-audits only what changed since last run. On explicit user request,
   applies surgical fixes with full rollback.
-version: 0.6.1
+version: 0.6.3
 ---
 
 # super-design
@@ -33,17 +33,25 @@ Four-phase pipeline with 6 specialist agents:
      low density, weak CTA hierarchy, vibecode smell).
    - **Step 3h mobile-native audit** (21-item Duolingo/Linear/Arc/Cash-App
      checklist) — replaces "responsive-web-on-a-phone" thinking.
-   - C16 ≤ 4 → design-skill advisory finding citing typeui-* selection matrix.
+   - C16 ≤ 4 → **DSC-choice** proposal: sd-synthesis runs
+     `scripts/score-typeui.mjs --from-audit <dir>` to derive a 7-axis site
+     fingerprint (density/contrast/geometry/color/typography/motion/audience)
+     and rank all installed typeui-* skills by fit 0-1. Top-3 are written to
+     `typeui-proposal.json` + shown in overview.md with a copy-paste CLI.
    Produces findings.json + design-intelligence.json with SHOT+QUOTE+SEL+VAL.
 3. **Synthesis** (sd-synthesis) — unifies research + audit + design-intelligence
-   into overview.md (per-page DIS table + executive summary).
+   into overview.md (per-page DIS table + executive summary + typeui proposal
+   when craft ≤ 4).
 4. **Fix** (sd-fix + two-stage verify) — optional. Applies safe fixes with
    technical gates (types/lint/tests) AND semantic verification ("does this
    fix actually resolve the finding, or just mask it?"). Template families:
    A1-A15 a11y · V1-V8 design · U1-U10 ux · P1-P10 perf · **M1-M15 mobile**
    (cards-in-flex-col → compact list, table-on-mobile → card-per-row,
    centered-modal → bottom-sheet, etc.) · **DSC-1 design-skill advisory**
-   (proposes typeui-* direction, never auto-applies — HIGH risk). After each
+   (proposes typeui-* direction). With `--typeui <name>` flag, sd-fix loads
+   the chosen typeui skill (tokens: primary, radius, spacing scale,
+   typography) and rebrands V1-V8 fixes so every spacing/color/radius target
+   snaps to that direction's scale — turning advisory into applied. After each
    successful fix, re-drives Playwright to capture an after-screenshot (full
    page + element crop) and emits `docs/super-design/sessions/<id>/fix-report.md`:
    a self-contained visual diff with before/after images, file diffs,
@@ -105,10 +113,105 @@ Do NOT paste overview into chat.
 - `--refresh-research` — rerun sd-research
 - `--only <cat>` — a11y | design | ux | perf | research
 - `--scope <url>` — specific route
+- `--app <name>` — scope the entire run to one monorepo app (matches a
+  `name` entry from `scripts/detect-apps.sh`). Required when `--scope <url>`
+  is ambiguous between multiple apps.
 - `--fix` — run sd-fix after audit
+- `--typeui <name>` — combine with `--fix` to apply fixes aligned to a
+  chosen typeui direction (e.g. `--fix --typeui application`). Loads tokens
+  from `~/.claude/skills/typeui-<name>/SKILL.md` and rebrands V1-V8 targets
+  to that scale. Picked from the top-3 proposed in overview.md typeui
+  block. Without this flag, DSC-1 stays advisory. Run
+  `bash scripts/score-typeui.mjs --list` to see all installed directions.
+- `--harvest-typeui` — run `scripts/harvest-typeui.sh` first to pull
+  missing typeui-* and related design skills (typeui.sh registry with
+  built-in catalog fallback). Idempotent; add `--refresh` to re-download.
 - `--dry-run` — artifacts without committing state
 - `--ci` — non-interactive, create PR, exit non-zero on blockers
-- `--update-baselines` — Re-hash pages and tokens without re-auditing (use after accepted cosmetic drift)
+- `--update-baselines` — Re-hash pages and tokens without re-auditing (use after accepted cosmetic drift). Also accepted by `scripts/visual-regression.sh` to overwrite `.super-design/baselines/*.png` with the current capture.
+- `--visual-regression` — Run `scripts/visual-regression.sh` after hashing. Reads the `visual_regression` block from `.audit-state.json` (engine: pixelmatch | odiff | sha256-fallback; threshold 0.1; max_diff_pixel_ratio 0.01). See artifact §16.
+- `MASK_SELECTORS=<sel,sel,...>` (env) — Extra CSS selectors masked in every screenshot captured by `scripts/hash-pages.sh`. Artifact §3.4 defaults (`[data-timestamp], .relative-time, [data-react-hydration], video, canvas`) are always applied.
+
+## Monorepo support
+
+Audit state is per-app (artifact §11 line 902) so independent deploys
+carry independent freshness, `git_sha_at_audit`, and tool results. Layout
+is auto-detected; nothing else to configure.
+
+### Detection
+
+`scripts/detect-apps.sh` reads the first workspace manifest it finds:
+
+| Manifest | Source of globs |
+|----------|-----------------|
+| `pnpm-workspace.yaml` | `packages:` list |
+| `package.json` | `workspaces: [...]` or `workspaces.packages: [...]` (npm, yarn, Bun) |
+| `turbo.json` | Presence → uses pnpm/npm/yarn workspaces; falls back to `apps/*` + `packages/*` if none |
+| `nx.json` | `workspaceLayout.appsDir` / `libsDir` (default `apps/*`, `libs/*`) |
+| `bunfig.toml` | Presence → falls back to `apps/*` + `packages/*` if package.json has no workspaces |
+
+Each matched directory that also has a `package.json` becomes an app
+with `name` taken from `package.json#name` (scope stripped), `path` the
+directory, and `state_path` = `<path>/docs/super-design/.audit-state.json`.
+If nothing matches, `detect-apps.sh` emits a `single` layout with
+`path: "."` and the repo-root state path — preserving existing single-app
+behavior.
+
+### Per-app pipeline
+
+- **Preflight**: per app, read `<app>/docs/super-design/.audit-state.json`
+  via `validate-state.sh <app_path>`.
+- **Change detection**: `scripts/detect-changes.sh --all-apps` loops over
+  every app and narrows `git diff` to `-- <app_path>/` so each app's
+  scope decision sees only its own files. Single-app shape is preserved
+  with `detect-changes.sh <last_sha>`.
+- **Write state**: `scripts/write-state.sh <app_path>` derives the target
+  path; for single-app repos pass `.` or omit.
+
+### URL → app disambiguation
+
+`--scope <url>` still targets one URL. When the URL maps cleanly to a
+single app (e.g. `apps/admin` serves `https://admin.example.com`), the
+pipeline picks that app automatically. When mapping is ambiguous
+(multiple apps serve overlapping hostnames, or URL patterns cross apps),
+the user MUST pass `--app <name>` — otherwise the skill aborts with a
+`{"error":"ambiguous-app","candidates":[...]}` verdict instead of
+guessing.
+
+## Scripts
+
+Reusable shell helpers under `scripts/`. All POSIX/bash, tested on
+Windows git-bash + Linux.
+
+- `discover-routes.sh` — emits `route_map` as a JSON array. Dynamic
+  segments (`[slug]`, `[[...all]]`, `$id`, `:uid`) are suffixed with
+  `@fixture-<id>` (artifact §2.7). Fixtures resolved from sibling
+  `*.fixture.json`, `fixtures/<name>.json`, or `$SUPER_DESIGN_FIXTURES`
+  env JSON; falls back to `@fixture-default` with a warning. Consumers
+  (hash-pages, sd-audit) MUST strip the suffix before navigating.
+- `build-import-graph.sh` — builds `.super-design/import-graph.json`
+  (`{nodes, edges, hash, backend}`) and persists `import_graph_sha` to
+  state. Prefers `npx madge --json <roots>`; falls back to a regex
+  scanner (JS/TS only, no alias resolution) if madge is missing.
+  - Query: `bash .../build-import-graph.sh importers <file> --hops 3`
+    → BFS over reversed edges; `detect-changes.sh` uses this to close
+    the component→pages gap when only components changed (Step 2 scope
+    decision: "Only components changed → re-audit pages importing them
+    (N=3 hops via madge)").
+- `hash-pages.sh` — captures 3 viewports per URL (mobile_375, tablet_768,
+  desktop_1280), emits `{html_hash, dom_structure_hash, viewport_hashes:
+  {<vp>: {sha256, phash, png_path}}}` per page to
+  `docs/super-design/.cache/hashes/hashes.json` and persists each PNG to
+  `<cache>/screenshots/<url-enc>/<vp>.png`. Applies artifact §3.4 mask
+  defaults plus `MASK_SELECTORS`; `phash` uses `sharp` when available
+  (tagged `phash:`) or a deterministic PNG fingerprint otherwise
+  (tagged `fpr:`, only useful for exact-match comparison).
+- `visual-regression.sh [--update-baselines] [<state>]` — reads the
+  `visual_regression` block from `.audit-state.json` and diffs current
+  screenshots against `.super-design/baselines/`. Engine chain:
+  `pixelmatch` → `odiff` → `sha256-fallback`. Emits
+  `{page, viewport, diff_ratio, threshold, pass, diff_image_path}` to
+  `<diff_dir>/results.json`. Exits non-zero if any page fails.
 
 ## References (Read on demand)
 

package/template/.claude/skills/super-design/audit-state.schema.json

@@ -0,0 +1,226 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://hakutaku.ai/schemas/super-design/audit-state.schema.json",
+  "title": "super-design audit state",
+  "description": "Canonical schema for docs/super-design/.audit-state.json — the state file that super-design reads on every run to decide what to re-audit. Derived from docs/compass_artifact_wf-f52f98c2-73c9-4483-b49c-6b080ef7dc92_text_markdown.md sections 5, 10, and 16.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "skill_version",
+    "last_audit_at",
+    "git_sha_at_audit"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver string for this state file's schema. Major bumps force a full re-audit (see §12 line 934, §10).",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:[-+].+)?$"
+    },
+    "skill_version": {
+      "type": "string",
+      "description": "Semver of the super-design skill that wrote this state.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:[-+].+)?$"
+    },
+    "last_audit_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp of the last completed audit (used for freshness cascade: 90d soft, 180d hard).",
+      "format": "date-time"
+    },
+    "git_sha_at_audit": {
+      "type": "string",
+      "description": "Git SHA (7–64 hex chars) that HEAD pointed to at audit time. Used as the range-start for next audit's git log (§2.1).",
+      "pattern": "^[0-9a-f]{7,64}$"
+    },
+    "git_branch": {
+      "type": "string",
+      "description": "Branch name at audit time (informational)."
+    },
+    "is_shallow_clone": {
+      "type": "boolean",
+      "description": "True if the repo was a shallow clone at audit time. Signals that __MISSING__ fallback (§6) may need git fetch --unshallow."
+    },
+
+    "theory_doc_sha": {
+      "type": "string",
+      "description": "sha256: of references/design-theory.md. Mismatch forces full re-audit (§9.1).",
+      "pattern": "^sha256:[0-9a-f]{4,64}$"
+    },
+    "market_analysis_sha": {
+      "type": "string",
+      "description": "sha256: of the current market-analysis.md output.",
+      "pattern": "^sha256:[0-9a-f]{4,64}$"
+    },
+
+    "tools": {
+      "type": "object",
+      "description": "Versions of the audit toolchain at audit time. Major bumps can invalidate prior findings.",
+      "additionalProperties": true,
+      "properties": {
+        "axe-core":       { "type": "string" },
+        "lighthouse":     { "type": "string" },
+        "playwright":     { "type": "string" },
+        "playwright-mcp": { "type": "string" },
+        "pa11y":          { "type": "string" }
+      }
+    },
+
+    "framework": {
+      "type": "object",
+      "description": "Detected framework info. Router/version migration triggers full re-audit (§7).",
+      "additionalProperties": true,
+      "properties": {
+        "name":    { "type": "string" },
+        "router":  { "type": "string" },
+        "version": { "type": "string" }
+      },
+      "required": ["name"]
+    },
+
+    "route_map": {
+      "type": "array",
+      "description": "Canonical route list at audit time. Diff against prior route_map produces new/deleted routes (§7).",
+      "items": { "type": "string" }
+    },
+
+    "pages_audited": {
+      "type": "array",
+      "description": "Per-page hashes + findings (§3, §5). Incremental audits compare these to decide which pages to re-visit.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["url"],
+        "properties": {
+          "url":                  { "type": "string" },
+          "route_file":           { "type": "string" },
+          "html_hash":            { "type": "string", "pattern": "^sha256:[0-9a-f]{4,64}$" },
+          "dom_structure_hash":   { "type": "string", "pattern": "^sha256:[0-9a-f]{4,64}$" },
+          "screenshot_hash":      { "type": "string", "pattern": "^(sha256|phash):[0-9a-f]{4,64}$" },
+          "viewport_hashes": {
+            "type": "object",
+            "description": "Per-viewport hashes (mobile_375/tablet_768/desktop_1280). Each entry may be a bare phash string (back-compat with artifact §10 line 492) or the extended {sha256,phash,png_path} object emitted by hash-pages.sh. Any viewport drift -> re-audit that page.",
+            "additionalProperties": {
+              "oneOf": [
+                { "type": "string" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "sha256":   { "type": "string" },
+                    "phash":    { "type": "string" },
+                    "png_path": { "type": "string" }
+                  }
+                }
+              ]
+            }
+          },
+          "mask_selectors": {
+            "type": "array",
+            "description": "CSS selectors masked in this page's screenshots (artifact §3.4). Merged from hash-pages.sh defaults + MASK_SELECTORS env.",
+            "items": { "type": "string" }
+          },
+          "phash_engine": {
+            "type": "string",
+            "description": "Which engine produced the phash values. `phash:` = sharp-based aHash. `fpr:` = zero-dep PNG fingerprint fallback (exact-match only)."
+          },
+          "last_audited": { "type": "string", "format": "date-time" },
+          "findings_ids": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+
+    "components": {
+      "type": "object",
+      "description": "Map of component path -> xxh3 hash (§8). Source of truth for component-level change detection.",
+      "additionalProperties": { "type": "string" }
+    },
+
+    "token_hash": {
+      "type": "string",
+      "description": "sha256: hash of the canonicalized design-token map. Mismatch invalidates every page (§9).",
+      "pattern": "^sha256:[0-9a-f]{4,64}$"
+    },
+
+    "import_graph_sha": {
+      "type": "string",
+      "description": "sha256: of the serialized import graph (madge). Used to compute blast radius of component changes.",
+      "pattern": "^sha256:[0-9a-f]{4,64}$"
+    },
+
+    "findings_counts": {
+      "type": "object",
+      "description": "Aggregate tally after last audit (§5).",
+      "additionalProperties": false,
+      "properties": {
+        "blockers": { "type": "integer", "minimum": 0 },
+        "high":     { "type": "integer", "minimum": 0 },
+        "medium":   { "type": "integer", "minimum": 0 },
+        "nitpicks": { "type": "integer", "minimum": 0 }
+      }
+    },
+
+    "research_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp of the last sd-research run. Used to decide whether to rerun research (>90d -> refresh).",
+      "format": "date-time"
+    },
+
+    "ignored_paths": {
+      "type": "array",
+      "description": "Globs excluded from design-relevance classification (§2.3).",
+      "items": { "type": "string" }
+    },
+
+    "visual_regression": {
+      "type": "object",
+      "description": "Optional visual-regression config (§16). Absent when user hasn't opted in. Consumed by scripts/visual-regression.sh.",
+      "additionalProperties": true,
+      "properties": {
+        "enabled":              { "type": "boolean", "default": false },
+        "engine": {
+          "type": "string",
+          "description": "Engine chain: scripts/visual-regression.sh tries in order and falls back. `sha256-fallback` = exact-match only, always available.",
+          "enum": ["pixelmatch", "odiff", "resemble", "looks-same", "playwright", "sha256-fallback"],
+          "default": "pixelmatch"
+        },
+        "threshold":            { "type": "number", "minimum": 0, "default": 0.1 },
+        "max_diff_pixel_ratio": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.01 },
+        "antialiasing":         { "type": "boolean", "default": true },
+        "viewports": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label", "width", "height"],
+            "properties": {
+              "label":  { "type": "string" },
+              "width":  { "type": "integer", "minimum": 1 },
+              "height": { "type": "integer", "minimum": 1 }
+            }
+          }
+        },
+        "mask_selectors": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "baseline_dir": {
+          "type": "string",
+          "description": "Where accepted baseline PNGs live. Committed to git (small repos) or stored via LFS/artifacts (large).",
+          "default": ".super-design/baselines"
+        },
+        "current_dir": {
+          "type": "string",
+          "description": "Where hash-pages.sh writes the current run's PNGs. Usually gitignored.",
+          "default": "docs/super-design/.cache/hashes/screenshots"
+        },
+        "diff_dir": {
+          "type": "string",
+          "description": "Where diff images + results.json are emitted by visual-regression.sh.",
+          "default": "docs/super-design/.cache/hashes/diffs"
+        },
+        "docker_image": { "type": "string" }
+      }
+    }
+  }
+}

package/template/.claude/skills/super-design/scripts/build-import-graph.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# build-import-graph.sh — build a JS/TS import graph for the repo so
+# super-design can propagate component-level changes to pages within N
+# hops (artifact §8, line 666: default N=3).
+#
+# Usage:
+#   build-import-graph.sh [--state <path>]            # full build
+#   build-import-graph.sh importers <file> [--hops N] # BFS query
+#
+# Output (full build): .super-design/import-graph.json with shape
+#   {
+#     "nodes":   ["src/app/page.tsx", ...],
+#     "edges":   [{"from":"src/app/page.tsx","to":"src/components/Nav.tsx"}, ...],
+#     "hash":    "sha256:<hex>",
+#     "backend": "madge" | "regex-fallback",
+#     "built_at":"<ISO-8601>"
+#   }
+#
+# State: writes `import_graph_sha` back into .audit-state.json via
+# scripts/write-state.sh. The sha lives in audit-state.schema.json so
+# detect-changes.sh can short-circuit re-propagation if the graph is
+# unchanged.
+#
+# Backend choice:
+#   1. If `npx madge --version` works, use `npx madge --json <roots>`
+#      (artifact §8: madge reads .madgerc / package.json#madge).
+#   2. Else fall back to a zero-dep regex scanner (JS/TS/JSX/TSX only —
+#      no CSS/Vue/Svelte detectives, no alias resolution). Logs a
+#      warning so the caller knows propagation is best-effort.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STATE_PATH="docs/super-design/.audit-state.json"
+OUT_DIR=".super-design"
+OUT_FILE="$OUT_DIR/import-graph.json"
+
+log() { printf '[build-import-graph] %s\n' "$*" >&2; }
+
+# Source roots — read from state, else default.
+resolve_roots() {
+  local roots=""
+  if [[ -f "$STATE_PATH" ]]; then
+    roots="$(jq -r '.source_roots // empty | .[]?' "$STATE_PATH" 2>/dev/null || true)"
+  fi
+  if [[ -z "$roots" ]]; then
+    for d in src app pages; do [[ -d "$d" ]] && echo "$d"; done
+  else
+    printf '%s\n' "$roots"
+  fi
+}
+
+# --- Full build -----------------------------------------------------------
+
+build_madge() {
+  # madge prints { "file": [deps], ... }. We flatten to edges.
+  local roots_json
+  roots_json="$(resolve_roots | jq -Rn '[inputs]')"
+  local roots
+  roots="$(printf '%s' "$roots_json" | jq -r '.[]' | tr '\n' ' ')"
+  [[ -z "$roots" ]] && { log "no source roots found"; echo '{}'; return; }
+  # shellcheck disable=SC2086
+  npx --yes madge --json $roots 2>/dev/null
+}
+
+build_regex_fallback() {
+  log "madge unavailable; using regex fallback (JS/TS only, no alias resolution)"
+  local roots
+  roots="$(resolve_roots | tr '\n' ' ')"
+  [[ -z "$roots" ]] && { echo '{}'; return; }
+
+  # Emit NDJSON: {"from":"<path>","to":"<dep>"} for each import line in
+  # each JS/TS file, then fold into {file: [deps]} via jq.
+  # shellcheck disable=SC2086
+  find $roots -type f \( \
+      -name '*.ts' -o -name '*.tsx' \
+      -o -name '*.js' -o -name '*.jsx' \
+      -o -name '*.mjs' -o -name '*.cjs' \) 2>/dev/null \
+  | while IFS= read -r f; do
+      # Grep import/require specifiers. Handles:
+      #   import ... from 'x'
+      #   import 'x'
+      #   require('x')
+      #   import('x')          (dynamic)
+      #   export ... from 'x'
+      grep -hoE "(from|require|import)[[:space:]]*\(?[[:space:]]*['\"][^'\"]+['\"]" "$f" 2>/dev/null \
+        | sed -E "s|.*['\"]([^'\"]+)['\"].*|\1|" \
+        | while IFS= read -r spec; do
+            [[ -z "$spec" ]] && continue
+            # Skip bare package specifiers for graph purposes (we only
+            # want local file edges to compute importers).
+            case "$spec" in
+              .*|/*) : ;;
+              *) continue ;;
+            esac
+            # Normalize: resolve relative to $f's directory, best-effort.
+            local dir resolved
+            dir="$(dirname "$f")"
+            resolved="$dir/$spec"
+            # Strip ./ and trailing /
+            resolved="$(printf '%s' "$resolved" \
+              | sed -E 's|/\./|/|g; s|/$||')"
+            jq -cn --arg from "$f" --arg to "$resolved" '{from:$from,to:$to}'
+          done
+    done \
+  | jq -sc 'group_by(.from) | map({key:.[0].from, value:(map(.to)|unique)}) | from_entries'
+}
+
+build_graph_json() {
+  local raw
+  if npx --yes madge --version >/dev/null 2>&1; then
+    raw="$(build_madge || echo '{}')"
+    BACKEND="madge"
+  else
+    raw="$(build_regex_fallback || echo '{}')"
+    BACKEND="regex-fallback"
+  fi
+  [[ -z "$raw" ]] && raw='{}'
+  printf '%s' "$raw"
+}
+
+emit_final() {
+  local raw="$1"
+  mkdir -p "$OUT_DIR"
+  # Build nodes + edges from the {file: [deps]} shape. Keep original
+  # paths verbatim (do not attempt alias resolution here).
+  local body
+  body="$(printf '%s' "$raw" | jq --arg backend "$BACKEND" --arg now "$(date -u +%FT%TZ)" '
+    . as $g
+    | ([keys[], (.[] | .[])] | unique) as $nodes
+    | [to_entries[] | .key as $from | .value[] | {from:$from, to:.}] as $edges
+    | {nodes:$nodes, edges:$edges, backend:$backend, built_at:$now}
+  ')"
+  # Hash over nodes+edges (stable serialization via jq --sort-keys -c).
+  local hash
+  hash="$(printf '%s' "$body" | jq -S -c '{nodes, edges}' | sha256sum | awk '{print "sha256:"$1}')"
+  printf '%s' "$body" | jq --arg h "$hash" '. + {hash:$h}' > "$OUT_FILE"
+
+  # Update state.import_graph_sha if state file exists.
+  if [[ -f "$STATE_PATH" ]]; then
+    jq --arg h "$hash" '. + {import_graph_sha:$h}' "$STATE_PATH" \
+      | bash "$SCRIPT_DIR/write-state.sh" "$STATE_PATH" >/dev/null \
+      || log "failed to persist import_graph_sha to state"
+  fi
+
+  jq -n --arg path "$OUT_FILE" --arg hash "$hash" --arg backend "$BACKEND" \
+        --argjson nodes "$(jq '.nodes|length' "$OUT_FILE")" \
+        --argjson edges "$(jq '.edges|length' "$OUT_FILE")" \
+    '{status:"ok", path:$path, hash:$hash, backend:$backend, nodes:$nodes, edges:$edges}'
+}
+
+# --- Query: importers_of --------------------------------------------------
+
+# importers_of <file> [--hops N]
+#   BFS over the edge list using jq. Emits one path per line.
+importers_of() {
+  local file="$1"; shift || true
+  local hops=3
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --hops) hops="${2:-3}"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  [[ -f "$OUT_FILE" ]] || { log "no import graph; run build first"; return 1; }
+  jq -r --arg start "$file" --argjson hops "$hops" '
+    . as $g
+    # Reverse adjacency: to → [from...]
+    | ([.edges[] | {key:.to, value:.from}] | group_by(.key)
+        | map({key:.[0].key, value:(map(.value)|unique)}) | from_entries) as $rev
+    | def bfs(frontier; seen; depth):
+        if depth >= $hops or (frontier|length)==0 then seen
+        else
+          (frontier | map($rev[.] // []) | add // [] | unique) as $next
+          | ($next - (seen|keys | map(.))) as $fresh
+          | bfs($fresh; (seen + ($fresh | map({(.):true}) | add // {})); depth + 1)
+        end;
+      bfs([$start]; {}; 0) | keys[]
+  ' "$OUT_FILE"
+}
+
+# --- Dispatch -------------------------------------------------------------
+
+main() {
+  case "${1:-build}" in
+    build|"")
+      shift || true
+      while [[ $# -gt 0 ]]; do
+        case "$1" in
+          --state) STATE_PATH="${2:?}"; shift 2 ;;
+          *) shift ;;
+        esac
+      done
+      raw="$(build_graph_json)"
+      emit_final "$raw"
+      ;;
+    importers)
+      shift
+      [[ -z "${1:-}" ]] && { log "usage: importers <file> [--hops N]"; exit 2; }
+      importers_of "$@"
+      ;;
+    *)
+      log "unknown subcommand: $1"
+      exit 2
+      ;;
+  esac
+}
+
+main "$@"