ai-spector 0.1.0

package/scaffold/.ai-spector/index/basic-design.md

@@ -0,0 +1,5 @@
+# Basic Design Document Index
+
+Last indexed: (not yet run — use `/index-docs basic-design`)
+
+No entries yet. Source root: `docs/basic-design/`.

package/scaffold/.ai-spector/index/srs.md

@@ -0,0 +1,5 @@
+# SRS Document Index
+
+Last indexed: (not yet run — use `/index-docs` or `/index-docs srs`)
+
+No entries yet. Source root: `docs/srs/`.

package/scaffold/.cursor/commands/_cli-failures.md

@@ -0,0 +1,110 @@
+# CLI failures (mandatory agent behavior)
+
+When any `ai-spector` command **fails** (non-zero exit, throws, or empty/invalid JSON when `--json` was required):
+
+1. **Stop** the current slash command — no templates, no subagents, no writing `docs/srs/**`.
+2. **Show the user** the failure using the response format below (verbatim CLI output).
+3. **Explain** what it means in plain language and give **concrete fix steps** the user can take (or approve the agent to apply).
+4. **Re-run the same CLI** after the fix — do not switch to a manual workaround.
+
+## Forbidden when CLI fails
+
+| Do not | Why |
+|--------|-----|
+| Hand-edit `traceability.graph.json` at scale | Bypasses merge/validate; drifts from `knowledge.json` |
+| Implement graph BFS/search in the agent | Duplicates `graph query` / `graph impact` |
+| Glob or read all of `docs/srs/**` because query failed | Hides missing graph or bad seed id |
+| Use `.ai-spector/index/*.md` as primary context when validate/query failed | Index is fallback only after **successful** CLI with empty graph |
+| Skip `graph merge` and “fill SRS from memory” | Breaks traceability |
+| Silently continue after `graph validate` errors | Generation will be wrong or inconsistent |
+| Tell the user “run this CLI yourself” without fixing | User workflow is slash commands; agent owns CLI |
+
+**Allowed after successful CLI:** If `graph query --json` succeeds but `nodes` has no domain entries, say so and suggest **`/analyze`** — still do not bulk-read `docs/srs/**`.
+
+---
+
+## Response format (copy this structure)
+
+```markdown
+## Blocked: <slash-command> — CLI failed
+
+**Command:** `ai-spector <subcommand> …`
+**Exit code:** <n>
+
+**CLI output:**
+\`\`\`
+<paste full stdout/stderr>
+\`\`\`
+
+**What this means:** <one or two sentences>
+
+**How to fix:**
+1. <step for user or agent>
+2. <step>
+3. Re-run **/<slash-command>** (or the step that failed, e.g. `/analyze`)
+
+**I will not:** <e.g. generate SRS without a passing validate, or edit the graph by hand>
+```
+
+---
+
+## Common failures → fixes
+
+### `ai-spector: command not found`
+
+- **Means:** Package not installed or not on PATH.
+- **Fix:** `npm install ai-spector` in the project; agent uses `npx ai-spector …` from project root.
+
+### `Could not find project root` / missing `docflow.config.json`
+
+- **Means:** `init` not run or wrong working directory.
+- **Fix:** Run `npx ai-spector init` from project root; agent `cd`s to workspace root before CLI.
+
+### `ai-spector analyze` fails
+
+- **Means:** Registry/templates or graph bootstrap broke.
+- **Fix:** Show full error; check `.ai-spector/registry/section-registry.json` exists; re-run `init` if config is corrupt; do not proceed to merge.
+
+### `graph merge` — `No domain entries in knowledge.json`
+
+- **Means:** `/analyze` extract did not populate staging.
+- **Fix:** Re-run Graphify extract in `/analyze`; ensure `docs/data-source/` has real files; fill `knowledge.json` with at least one `useCase` or `feature`.
+
+### `graph merge` — `Merge edge missing target node` / section id
+
+- **Means:** `listedInSection` points to a section id not in the graph.
+- **Fix:** Use a section id from `section-registry.json` (e.g. `sec.srs.3-use-cases.l3.3.32-list-use-case`) or omit `listedInSection` for defaults; re-run merge.
+
+### `graph validate` — `DOMAIN-ANCHORED` / `SECTION-TREE` / `SCHEMA`
+
+- **Means:** Graph inconsistent with rules.
+- **Fix:** Paste each `[ERROR]` line; prefer re-run **`/analyze`** (merge) over manual JSON surgery; for one bad id, agent may patch **only** that node/edge then re-validate.
+
+### `graph query <id>` — seed missing or empty subgraph
+
+- **Means:** Wrong id, or domain not merged.
+- **Fix:** Run **`/visualize-graph`** or `graph query` with a known id from `knowledge.json`; run **`/analyze`** if no `useCase`/`feature` nodes.
+
+### `graph query` — invalid JSON / parse error
+
+- **Means:** CLI crashed or wrong cwd.
+- **Fix:** Re-run from project root; if repeat, report as tool bug with full stderr.
+
+### Graphify MCP unavailable
+
+- **Means:** `/analyze` cannot extract.
+- **Fix:** User enables Graphify in Cursor; do not fake `knowledge.json`; stop and document blocker.
+
+---
+
+## Agent may fix without asking (small, local)
+
+- Create missing parent dirs under `.ai-spector/` if `init` was incomplete.
+- Correct a **single** typo in `knowledge.json` id or `listedInSection` then re-run `graph merge`.
+- Re-run the **same** failed command once after an obvious fix (e.g. `cd` to project root).
+
+## Agent must ask user before
+
+- Deleting `traceability.graph.json` or re-running `init --force`.
+- Large manual edits to graph or generated SRS.
+- Changing bundled templates or `workflow.dependencies.json`.

package/scaffold/.cursor/commands/_graph.md

@@ -0,0 +1,48 @@
+# Graph CLI (for agents)
+
+**Users do not run these.** Slash commands invoke CLI. Workflow: [_workflow.md](./_workflow.md). **On failure:** [_cli-failures.md](./_cli-failures.md).
+
+Run from project root: `npx ai-spector …` if needed.
+
+## Every CLI invocation
+
+1. Run the command; capture **exit code**, **stdout**, **stderr**.
+2. If non-zero or `--json` is unparseable → **stop**; report per `_cli-failures.md`.
+3. On success, use CLI output only — do not re-derive graph state in the agent.
+
+## Commands
+
+```bash
+ai-spector analyze
+ai-spector graph merge --from-knowledge
+ai-spector graph validate
+ai-spector graph visualize [--open]
+ai-spector graph query <nodeId> --json
+ai-spector graph impact <nodeId> --json
+```
+
+## `graph query`
+
+```bash
+ai-spector graph query <seedId> --direction both --depth 3 --json
+```
+
+Use `projectionPaths`, `nodes`, `edges` from JSON. **If command fails or JSON invalid:** stop — do not glob `docs/srs/**`.
+
+**If success but empty domain nodes:** report to user; suggest `/analyze` — still no folder-wide SRS reads.
+
+## `graph impact`
+
+```bash
+ai-spector graph impact <nodeId> --change content_change --json
+```
+
+If this fails, do not guess impact scope — show CLI output and fix.
+
+## `graph merge`
+
+Called from `/analyze`. On merge/validate failure, do not patch `traceability.graph.json` by hand at scale — fix `knowledge.json` or section ids and re-run merge.
+
+## Narrow fallback (success only)
+
+Only when **validate passed** and **query succeeded** but content is thin: read specific `docs/data-source/**` files. Never because CLI failed.

package/scaffold/.cursor/commands/_prerequisites.md

@@ -0,0 +1,48 @@
+# Workflow prerequisites (shared)
+
+User workflow: [**_workflow.md**](./_workflow.md). **CLI failures:** [**_cli-failures.md**](./_cli-failures.md). Agent CLI: [**_graph.md**](./_graph.md).
+
+Load `.ai-spector/.docflow/config/workflow.dependencies.json` for the active step.
+
+## When checks fail
+
+1. **Stop immediately** — do not read templates, spawn subagents, or write outputs.
+2. Reply with the **Blocked** format in [_cli-failures.md](./_cli-failures.md) (include full CLI output).
+3. Help the user fix the issue; re-run the failed CLI; then continue the slash command.
+
+## Graph context (only after CLI succeeds)
+
+1. **`ai-spector graph validate`** — exit 0 required before generate.
+2. Per target: **`ai-spector graph query <seedId> --json`** — parse JSON; use `projectionPaths` and `nodes`.
+3. Open **only** those paths (+ targeted `docs/data-source/**` if still insufficient).
+
+**If validate or query fails:** follow [_cli-failures.md](./_cli-failures.md) — do **not** fall back to index or full-tree reads.
+
+**If query succeeds but has no domain nodes:** tell the user; suggest **`/analyze`** — still no `docs/srs/**` glob.
+
+## Check types
+
+| type | Pass when |
+|------|-----------|
+| `pathExists` | Path exists on disk |
+| `hasFiles` | At least `min` files matching `glob` under `path` |
+| `stateNotNull` | `state.json` field is non-null |
+| `jsonAnyNonEmpty` | JSON file exists; listed keys non-empty |
+| `allPathsExist` | Every path in `paths` exists |
+| `indexPopulated` | Index has `## File:` entries, no placeholder markers |
+| `indexPopulatedIfSourceHasFiles` | Conditional index check |
+
+## Graph checks (generate steps)
+
+| id | Pass when |
+|----|-----------|
+| `graph-file` | `.ai-spector/graph/traceability.graph.json` exists |
+| `graph-merged` | `state.json` → `analysis.graphMergedAt` is set |
+
+If only section shells (no `useCase`/`feature`): **block** with fix steps → **`/analyze`**, not manual SRS from index.
+
+## Stale warnings (not failures)
+
+- Data source newer than `analysis.lastRunAt` → suggest `/analyze`.
+- Projections changed → suggest `/sync-graph` after validate passes.
+- Index stale → warn only; graph query remains primary when domain nodes exist.

package/scaffold/.cursor/commands/_workflow.md

@@ -0,0 +1,50 @@
+# AI Spector workflow (Cursor)
+
+**You use slash commands.** The agent runs `ai-spector` CLI in the terminal. Do not ask the user to run `analyze`, `graph merge`, or `graph query` manually.
+
+If CLI fails: agent **stops**, shows output, and helps you fix — see [**_cli-failures.md**](./_cli-failures.md). No silent fallbacks.
+
+## One-time setup (terminal)
+
+```bash
+npm install ai-spector
+npx ai-spector init
+```
+
+Add source material under `docs/data-source/`, open the project in Cursor, and enable the **ai-spector** skill.
+
+## Day-to-day (slash commands only)
+
+| Step | You run | Agent runs (CLI) |
+|------|---------|------------------|
+| 1 | **`/analyze`** | `ai-spector analyze` → Graphify extract → `graph merge --from-knowledge` → `graph validate` → optional `graph visualize --open` |
+| 2 | **`/validate-graph`** | `ai-spector graph validate` |
+| 3 | **`/generate-srs`** | `graph validate` → `graph query <seed> --json` per target → write docs → `graph validate` |
+| 4 | **`/index-docs srs`** (optional) | index update per command |
+| 5 | **`/generate-basic-design`** | same `graph query` pattern |
+| 6 | **`/generate-detail-design`** | same `graph query` pattern |
+| After edits | **`/graph-impact <nodeId>`** | `graph impact <id> --json` |
+| Inspect graph | **`/visualize-graph`** | `graph visualize --open` |
+
+**Any step fails?** Agent reports the error and fix steps, then you re-run the **same** slash command. The agent does not bypass CLI with manual graph edits or folder-wide doc reads.
+
+## Typical first run
+
+```text
+npx ai-spector init          ← only CLI step you run yourself
+docs/data-source/            ← add files
+/analyze
+/validate-graph
+/generate-srs
+```
+
+## If something fails
+
+| Symptom | What to do |
+|---------|------------|
+| Red error after `/analyze` | Read agent’s **Blocked** message; fix data-source or Graphify; run **`/analyze`** again |
+| Validate errors | **`/validate-graph`** — agent explains each `[ERROR]` and fixes or guides you |
+| Empty SRS / wrong context | **`/analyze`** then **`/generate-srs`** — not “read all docs manually” |
+| Unsure what regen | **`/graph-impact <id>`** |
+
+Details: [_cli-failures.md](./_cli-failures.md). CLI reference: [_graph.md](./_graph.md). Prerequisites: [_prerequisites.md](./_prerequisites.md).

package/scaffold/.cursor/commands/analyze.md

@@ -0,0 +1,92 @@
+# /analyze
+
+Ingest `docs/data-source/` and commit knowledge into the traceability graph.
+
+**User runs this command only.** The agent runs all CLI steps below — see [_workflow.md](./_workflow.md).
+
+## Usage
+
+- `/analyze` — default root `docs/data-source`
+- `/analyze <path1> ...` — override inputs
+
+## Prerequisites
+
+1. **`npx ai-spector init`** was run once (project scaffold exists).
+2. `docs/data-source/` has at least one real input file.
+
+**On success, suggest:** `/visualize-graph` (optional) → `/validate-graph` → `/generate-srs`.
+
+## Required Behavior
+
+### 0. Prepare graph structure (CLI — agent runs first)
+
+```bash
+ai-spector analyze
+```
+
+Creates section/document nodes from templates. Do not ask the user to run this separately.
+
+### A. Extract (Graphify MCP)
+
+1. Load `data-source.json`, `analyze.graphify.json`.
+2. Resolve paths → `scope.json` → `sources`.
+3. Build/update Graphify index for that scope.
+4. Query / fallback to extract:
+   - actors, useCases, features, functionalRequirements, nfrs, entities, interfaces, constraints, openQuestions
+5. Persist staging:
+   - `.ai-spector/.docflow/analysis/knowledge.json` (see package `schemas/schema.knowledge.json`)
+   - `.ai-spector/.docflow/analysis/gaps.json`
+   - `.ai-spector/.docflow/analysis/scope.json`
+
+### B. Commit to graph (CLI — agent runs; no hand-edited graph JSON)
+
+```bash
+ai-spector graph merge --from-knowledge
+ai-spector graph validate
+```
+
+Optional for the user:
+
+```bash
+ai-spector graph visualize --open
+```
+
+Or suggest **`/visualize-graph`**.
+
+**`knowledge.json` minimum fields:**
+
+| Entity | `id` | `title` / `name` | `listedInSection` (optional) | Links |
+|--------|------|------------------|------------------------------|-------|
+| use case | `UC-01` | required | defaults to §3.2 list section | — |
+| feature | `F-01` | required | defaults to §4.2 list section | `satisfies`: `["UC-01"]` |
+| actor | `actor.customer` | `name` or `title` | defaults to §2.2 user classes | — |
+| requirement | `REQ-01` | required | section id | `tracesTo` optional |
+| entity | `ENT-Order` | `name` | defaults to §5.2 logical model | — |
+
+### C. State
+
+Update `state.json`: `analysis.lastRunAt`, `analysis.dataSource`, scope hash. Merge sets `analysis.graphMergedAt`.
+
+## Success Criteria
+
+- `ai-spector graph validate` passes with domain nodes (`useCase`, `feature`, …) anchored to sections.
+- `knowledge.json` mirrors extract; graph is authoritative for `/generate-srs`.
+- Gaps recorded in `gaps.json`.
+
+## CLI steps — stop on first failure
+
+Run in order. If any step fails, **stop** and use [_cli-failures.md](./_cli-failures.md) (show full CLI output + fix steps). Do not skip to merge, validate, or `/generate-srs`.
+
+| Step | Command |
+|------|---------|
+| 0 | `ai-spector analyze` |
+| B | `ai-spector graph merge --from-knowledge` |
+| B | `ai-spector graph validate` |
+
+Graphify failure counts as blocked — do not invent `knowledge.json`.
+
+## If blocked
+
+Use the **Blocked** template in [_cli-failures.md](./_cli-failures.md). Include which step failed, exit code, verbatim CLI output, what it means, and how to fix. Offer to apply small fixes (e.g. one bad `listedInSection`) then re-run the same step.
+
+**Do not:** hand-edit the full graph, generate SRS, or read all of `docs/srs/` as a workaround.

package/scaffold/.cursor/commands/generate-basic-design.md

@@ -0,0 +1,26 @@
+# /generate-basic-design
+
+Basic design from graph-selected SRS context. **User runs this command;** agent runs CLI. On CLI failure: [_cli-failures.md](./_cli-failures.md). [_workflow.md](./_workflow.md), [_graph.md](./_graph.md).
+
+## Prerequisites
+
+Graph merged + `ai-spector graph validate`. Minimum SRS on disk.
+
+## Required Behavior
+
+1. `ai-spector graph validate`
+2. Resolve seed: target **`feature`** id `F-xx` (from file arg or DAG).
+3. Per seed:
+
+```bash
+ai-spector graph query F-xx --direction both --depth 3 --json
+```
+
+4. Load only `projectionPaths` + referenced sources from JSON.
+5. Generate; update graph edges (`tracesTo` / `references`); `ai-spector graph validate`.
+
+## If blocked
+
+Any failed `graph validate` or `graph query` → [_cli-failures.md](./_cli-failures.md). No index or SRS folder-wide fallback when CLI failed.
+
+Index only if **query succeeded** and subgraph is empty — then suggest `/analyze`.

package/scaffold/.cursor/commands/generate-detail-design.md

@@ -0,0 +1,19 @@
+# /generate-detail-design
+
+Detail design via graph context. **User runs this command;** agent runs CLI. On CLI failure: [_cli-failures.md](./_cli-failures.md). [_workflow.md](./_workflow.md), [_graph.md](./_graph.md).
+
+## Prerequisites
+
+Graph validates; SRS minimum exists.
+
+## Required Behavior
+
+1. `ai-spector graph validate`
+2. Seed: `feature` id or detail `document` node.
+3. `ai-spector graph query <seed> --direction both --depth 3 --json`
+4. Load SRS + basic-design paths from `projectionPaths` only.
+5. Generate; update graph; `ai-spector graph validate`.
+
+## If blocked
+
+Failed validate/query → [_cli-failures.md](./_cli-failures.md). Do not read all of `docs/` manually when CLI failed.

package/scaffold/.cursor/commands/generate-srs.md

@@ -0,0 +1,63 @@
+# /generate-srs
+
+Generate SRS projections. **User runs this command;** agent runs CLI (`graph validate`, `graph query`, …). See [_workflow.md](./_workflow.md).
+
+## Usage
+
+- `/generate-srs` | `/generate-srs <file>`
+
+## Prerequisites
+
+`workflow.dependencies.json` → `generate-srs`. Block if `analysis.graphMergedAt` missing or **`ai-spector graph validate`** fails.
+
+## Required Behavior
+
+### 1. Gate
+
+```bash
+ai-spector graph validate
+```
+
+### 2. Plan targets
+
+DAG + scan `docs/srs/` (`good` | `missing_content` | `missing_file`). Map each target to graph **seed** id.
+
+### 3. Context per target (CLI — mandatory)
+
+```bash
+ai-spector graph query <seedId> --direction both --depth 3 --json
+```
+
+Parse JSON:
+
+- Load **only** `projectionPaths`
+- Use `nodes` / `edges` for UC/F text and relationships
+- Supplement `docs/data-source/**` only when query + graph nodes are insufficient
+
+**Forbidden:** manual graph traversal; glob `docs/srs/**` when query failed or validate failed.
+
+### If `graph validate` or `graph query` fails
+
+Stop immediately. Report via [_cli-failures.md](./_cli-failures.md). Do not generate SRS from index or folder-wide reads.
+
+### 4. Generate + update graph
+
+Fill templates; write files; add `rendersTo` / domain nodes; then:
+
+```bash
+ai-spector graph validate
+```
+
+### 5. State + logs
+
+Update `state.json`, run log, Graphify sync if configured.
+
+## Guardrails
+
+- CLI `graph query` for every target seed — on failure, stop and help user fix (see _cli-failures.md).
+- Never overwrite `good` without force.
+- Final `graph validate` must pass; if not, show errors and do not claim success.
+
+## If blocked
+
+Use [_cli-failures.md](./_cli-failures.md). User re-runs **`/generate-srs`** after validate/query succeed.

package/scaffold/.cursor/commands/graph-impact.md

@@ -0,0 +1,45 @@
+# /graph-impact
+
+Scope regen after a change. **User runs this command;** agent runs `graph impact` ([_graph.md](./_graph.md), [_workflow.md](./_workflow.md)).
+
+## Usage
+
+- `/graph-impact <nodeId>`
+- `/graph-impact <nodeId> --change content_change|delete|id_change|…`
+
+## Prerequisites
+
+- `ai-spector graph validate` passes
+
+## Required Behavior
+
+1. Run:
+
+```bash
+ai-spector graph impact <nodeId> --change <type> --json
+```
+
+Optional report file:
+
+```bash
+ai-spector graph impact <nodeId> --json -o .ai-spector/views/impact-<timestamp>.json
+```
+
+2. Parse JSON buckets: `regenerate`, `review`, `downstream`.
+3. Present table to user with `projectionPath` per entry.
+4. For each **regenerate** id, suggest `/generate-srs` or patch using:
+
+```bash
+ai-spector graph query <thatId> --json
+```
+
+**Do not** implement impact BFS in the agent.
+
+## If blocked
+
+Use [_cli-failures.md](./_cli-failures.md). If `graph impact` or follow-up `graph query` fails, show output and fix — do not invent regenerate lists.
+
+## Guardrails
+
+- No whole-repo regen outside CLI buckets.
+- No regen plan if impact CLI failed.

package/scaffold/.cursor/commands/index-docs.md

@@ -0,0 +1,36 @@
+# /index-docs
+
+Build **searchable summaries** under `.ai-spector/index/`. This is a **secondary** aid — prefer **`graph_neighbors`** for generation context when the graph has domain nodes.
+
+## Usage
+
+- `/index-docs` | `/index-docs srs` | `/index-docs basic-design` | `/index-docs <path>` | `--force`
+
+## Role vs graph
+
+| Mechanism | Use for |
+|-----------|---------|
+| **`graph_neighbors`** | **Primary** — relevant sections, UC/F, projection paths |
+| **Index** | Fallback when graph empty; quick human browse; optional metadata cache |
+
+After indexing, optionally add **`references`** edges from index entries to `document` nodes (advanced `/sync-graph`).
+
+## Prerequisites
+
+Warn if no files to index; do not block. See `workflow.dependencies.json` warn steps.
+
+## Required Behavior
+
+1. Load `index.docs.json`; discover files under `docs/srs/` or `docs/basic-design/`.
+2. For each file, if graph has matching `document` node by `output` path — include `graphNodeId` in metadata line.
+3. Write summaries to `.ai-spector/index/srs.md` / `basic-design.md` (format unchanged).
+4. Update `state.json` index hashes.
+
+## Guardrails
+
+- Index does **not** replace graph for `/generate-*` when graph is populated.
+- Never index templates or `node_modules/ai-spector/templates/`.
+
+## Success
+
+- Index files updated; user informed that generate commands should still use graph first.

package/scaffold/.cursor/commands/sync-graph.md

@@ -0,0 +1,30 @@
+# /sync-graph
+
+Reconcile **disk projections** (`docs/srs/`, etc.) with **graph nodes** — add missing `document` nodes, `rendersTo` edges, detect orphans.
+
+## Usage
+
+- `/sync-graph`
+- `/sync-graph docs/srs`
+
+## When to run
+
+- After manual edits to markdown outside `/generate-*`
+- Before `/validate-graph` when files exist but graph lacks `document` nodes
+- After bulk import of SRS files
+
+## Required Behavior
+
+1. Load `traceability.graph.json` + `section-registry.json`.
+2. Glob projection roots (`docs/srs/**/*.md`, etc.).
+3. For each file:
+   - Match to `document` node by `output` path; if missing, create `document` + link sections from registry where possible.
+   - Add **`rendersTo`** from document (or primary section) → file path.
+4. For each graph `document` with `output` missing on disk → mark orphan in report (do not delete nodes without user confirm).
+5. Run **`ai-spector graph validate`**.
+6. Summarize: added nodes, added edges, orphans, stale projections.
+
+## Guardrails
+
+- Do not remove domain nodes without explicit user request.
+- Preserve stable ids (`UC-01`, `sec.*`) when linking new files.

package/scaffold/.cursor/commands/validate-graph.md

@@ -0,0 +1,28 @@
+# /validate-graph
+
+Gate before generation. **User runs this command;** agent runs the CLI.
+
+## Usage
+
+- `/validate-graph`
+
+## Required Behavior
+
+```bash
+ai-spector graph validate
+```
+
+- **Exit 0** → tell the user OK; if domain nodes exist, suggest `/generate-srs`; if only section shells, explain they need `/analyze` first.
+- **Non-zero** → **stop**. Use [_cli-failures.md](./_cli-failures.md): paste every `[ERROR]` line, explain each, give fix steps (usually re-run `/analyze` or fix one node then re-validate).
+
+**Do not:** guess validation in the agent, hand-fix the whole graph without showing the user, or proceed to `/generate-srs`.
+
+## If blocked
+
+Follow [_cli-failures.md](./_cli-failures.md). Typical fixes:
+
+- `DOMAIN-ANCHORED` → domain node missing `listedIn` / `describedIn` → re-run `/analyze` or fix one node and `graph merge` again.
+- `SECTION-TREE` → structure edge wrong → re-run `ai-spector analyze` (agent), not manual graph surgery at scale.
+- `REGISTRY-COMPLETE` → re-run `/analyze` step 0 (`ai-spector analyze`).
+
+After fix, user re-runs **`/validate-graph`**.

package/scaffold/.cursor/commands/visualize-graph.md

@@ -0,0 +1,24 @@
+# /visualize-graph
+
+Open an HTML report of the traceability graph and `knowledge.json`.
+
+## Usage
+
+- `/visualize-graph`
+
+## Required Behavior
+
+```bash
+ai-spector graph visualize --open
+```
+
+Agent runs from project root. Default: `.ai-spector/views/graph-knowledge.html`
+
+## If blocked
+
+Use [_cli-failures.md](./_cli-failures.md). Common fixes:
+
+- Missing graph → run **`/analyze`** first (step 0 `ai-spector analyze`).
+- `command not found` → `npm install ai-spector`; use `npx ai-spector graph visualize --open`.
+
+Do not tell the user to inspect raw JSON instead of fixing the CLI — offer to fix cwd/install, then re-run **`/visualize-graph`**.