ai-spector 0.3.6 → 0.3.7

package/dist/visualize/html.js.map

@@ -1 +1 @@
-{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/visualize/html.ts"],"names":[],"mappings":"AAaA,SAAS,mBAAmB,CAAC,IAAa;IACxC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAyB;IAC9D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAE9C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iDA4KwC,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAsWjD,CAAC;AACT,CAAC"}
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/visualize/html.ts"],"names":[],"mappings":"AAaA,SAAS,mBAAmB,CAAC,IAAa;IACxC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAyB;IAC9D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAE9C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iDAqPwC,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA+ejD,CAAC;AACT,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spector",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Cursor-first documentation workflow: traceability graph, SRS/basic/detail design templates, and ai-spector CLI",
   "type": "module",
   "license": "MIT",
@@ -56,9 +56,14 @@
     "ai-spector": "node dist/cli.js"
   },
   "dependencies": {
+    "@types/mdast": "^4.0.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/scaffold/.ai-spector/.docflow/config/prototype.config.json

@@ -5,6 +5,5 @@
   "screenDetailDir": "docs/basic-design/screens/",
   "prototypeDir": "prototype",
   "srcDir": "prototype/src",
-  "slugFrom": "screenName",
-  "defaultTheme": "vercel"
+  "slugFrom": "screenName"
 }

package/scaffold/cursor/WORKFLOW.md

@@ -17,7 +17,7 @@ Add files under `docs/data-source/`, open the project in Cursor, **reload MCP**
 
 | You want to… | Say (examples) | Skill | Agent runs (summary) |
 |--------------|----------------|-------|----------------------|
-| Ingest sources | “analyze my data source”, “build the knowledge graph” | `ai-spector-graph` | `analyze` → Graphify → merge knowledge → validate |
+| Ingest sources | “analyze my data source”, “build the knowledge graph” | `ai-spector-graph` | `analyze` → read markdown → merge knowledge → validate |
 | Check graph | “validate the graph”, “graph errors” | `ai-spector-graph` | `graph validate` |
 | Refresh after edits | “re-index”, “sync the graph” | `ai-spector-graph` | `ai-spector index` |
 | Write SRS | “generate SRS”, “write use cases” | `ai-spector-generate-srs` | DAG waves → docs/srs → merge → index |
@@ -54,7 +54,7 @@ analyze → validate graph → generate SRS → index
 
 | Symptom | What to say / do |
 |---------|------------------|
-| Analyze failed | Agent offers fix vs workaround; say **1** to retry or “analyze again” after fixing data-source / Graphify |
+| Analyze failed | Agent offers fix vs workaround; say **1** to retry or “analyze again” after fixing data-source |
 | Validate errors | “validate the graph” — agent explains each error |
 | Empty SRS | “analyze” then “generate SRS” — not bulk-read all docs |
 | Unsure what regen | “what’s the impact of my changes” |

package/scaffold/cursor/commands/_workflow.md

@@ -11,7 +11,7 @@ npm install ai-spector
 npx ai-spector init
 ```
 
-Add source material under `docs/data-source/`, open the project in Cursor, **reload MCP** (Graphify is in `.cursor/mcp.json` from `init`), and **enable all ai-spector skills** under `.cursor/skills/` (see `.cursor/skills/README.md`).
+Add source material under `docs/data-source/`, open the project in Cursor, and **enable all ai-spector skills** under `.cursor/skills/` (see `.cursor/skills/README.md`).
 
 Skills auto-route for natural language; **slash commands stay the source of truth** for step-by-step work (see [commands/README.md](./README.md)). Slash commands win over skills when both apply.
 
@@ -19,11 +19,11 @@ Skills auto-route for natural language; **slash commands stay the source of trut
 
 | Step | You run | Agent runs (CLI) |
 |------|---------|------------------|
-| 1 | **`/analyze`** | `ai-spector analyze` → `ai-spector graphify update` (sidecar) → semantic extract → `graph merge --from-knowledge` → `graph validate` → optional `graph visualize --open` |
+| 1 | **`/analyze`** | `ai-spector analyze` → read markdown from `docs/data-source/` → `graph merge --from-knowledge` → `graph validate` → optional `graph visualize --open` |
 | 2 | **`/validate-graph`** | `ai-spector graph validate` |
 | 3 | **`/generate-srs`** [paths or request] — all, listed files, or described scope (**confirm** if described) → waves → merge (see `generate-srs.md`) |
 | 4 | **`/summary srs`** (optional) | Doc summaries under `.ai-spector/index/` (fallback browse; graph is primary) |
-| — | **`/index`** | After manual edits or **`/generate-srs`**: `ai-spector index` (structure + knowledge merge + **SRS body extract** + Graphify on changed paths + doc indexes) |
+| — | **`/index`** | After manual edits or **`/generate-srs`**: `ai-spector index` (structure + knowledge merge + **SRS body extract** + doc indexes) |
 | 5 | **`/generate-basic-design`** [paths or request] — same targeting + waves as SRS (`generate-basic-design.md`) |
 | 6 | **`/generate-detail-design`** | same `graph query` pattern |
 | 7 | **`/generate-prototype`** [--theme name] | `ai-spector prototype setup --theme …` → agent writes `prototype/src/*.html` → `prototype manifest` → `prototype validate --strict` |

package/scaffold/cursor/mcp.json

@@ -1,17 +1,3 @@
 {
-  "mcpServers": {
-    "graphify": {
-      "command": "uv",
-      "args": [
-        "tool",
-        "run",
-        "--from",
-        "graphifyy",
-        "python",
-        "-m",
-        "graphify.serve",
-        "${workspaceFolder}/.ai-spector/.docflow/graph/graphify-out/graph.json"
-      ]
-    }
-  }
+  "mcpServers": {}
 }

package/scaffold/cursor/skills/ai-spector/references/cli-failures.md

@@ -95,8 +95,6 @@ Use only when the user chooses **2** or explicitly accepts the trade-off. Prefer
 | `graph query` OK but thin `nodes` | Read only `projectionPaths` + cited `docs/data-source/**` | Named paths only; no `docs/srs/**` glob | `graph merge` + `validate` after draft |
 | `graph validate` — one bad id/edge | Patch **single** node/edge; re-validate | No mass graph surgery | `validate` must pass before next wave |
 | `graph merge` — one bad `listedInSection` | Fix id in `knowledge.json`; re-merge | No hand-merge of full graph | Same |
-| Graphify MCP down mid-**analyze** | Continue with existing `knowledge.json` + user sources | User accepts stale extract; document in reply | Re-run **analyze** when MCP is back |
-| `graphify update` on markdown-only path | Skip (expected); use **index** for doc semantics | Do not treat as hard failure | **index** on schedule per command doc |
 | `index` fails on one path | Skip that path if command allows; fix path and re-index | Do not skip required wave index without user OK | Re-run **index** for skipped paths |
 | Optional visualize fails | Skip open; continue pipeline | User chose workaround | None |
 | Terminal/env (not git, missing `uv`) | Agent runs install/init steps user approves | No destructive deletes without ask | Re-run failed CLI |
@@ -126,7 +124,7 @@ After any workaround that wrote docs or graph patches: **`graph validate`** (and
 ### `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`.
+- **Fix:** Re-run `/analyze`; ensure `docs/data-source/` has real markdown files with UC/F/actor content; fill `knowledge.json` with at least one `useCase` or `feature`.
 - **Workaround (user OK):** Manually add minimal entries to `knowledge.json` then re-merge.
 
 ### `graph merge` — `Merge edge missing target node` / section id
@@ -154,27 +152,6 @@ After any workaround that wrote docs or graph patches: **`graph validate`** (and
 - **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; reload MCP.
-- **Workaround (user OK):** Proceed with existing `knowledge.json` and data-source reads; schedule re-analyze.
-
-### `graphify update` — `unknown option: --graph`
-
-- **Means:** Agent used `graphify update <path> --graph <file>`. The `update` subcommand does **not** accept `--graph` (only `query`, `explain`, `path`, `cluster-only` do).
-- **Fix:** Run **`ai-spector graphify update`** (sets absolute `GRAPHIFY_OUT` and project-root cwd). Do not pass `--graph` on `update`.
-
-### `graphify update` — `No code files found` (exit 1) on `docs/srs` / `docs/basic-design`
-
-- **Means:** Those paths are empty or markdown-only; Graphify `update` AST-indexes **code** extensions (`.py`, `.ts`, `.js`, …), not SRS markdown alone.
-- **Fix:** **`ai-spector index`** / **`ai-spector graphify update`** skip empty and markdown-only sources automatically (success, not failure). Use **`docs/data-source`** for code Graphify indexing; SRS/basic-design semantics come from index doc-extract, not `graphify update`.
-
-### `graphify update` — output under `docs/data-source/.ai-spector/...`
-
-- **Means:** `GRAPHIFY_OUT` was a **relative** path and Graphify resolved it from the **source directory** (`docs/data-source`), not the repo root.
-- **Fix:** Run **`ai-spector graphify update`** from the project root. Delete mistaken `docs/data-source/graphify-out/` or `docs/data-source/.ai-spector/.docflow/graph/graphify-out/` if present.
-
 ### `graph impact --git` — not a git repository / no changes
 
 - **Means:** `--git` needs a git working tree with staged or unstaged diffs.
@@ -188,13 +165,7 @@ After any workaround that wrote docs or graph patches: **`graph validate`** (and
 ### Stale graph or indexes after manual edits or generate SRS
 
 - **Means:** User changed `docs/data-source/`, SRS outputs, or templates without re-running ingest; graph still shows template-only domain nodes.
-- **Fix:** Run **`ai-spector index`**. Use **`--force-graphify`** if Graphify output must rebuild entirely.
-- **Still stale domain detail?** Re-run **analyze** for Graphify MCP → fresh `knowledge.json`.
-
-### Graphify wrote `docs/data-source/graphify-out/` or `docs/data-source/.ai-spector/.../graphify-out/`
-
-- **Means:** `graphify update` ran without absolute `GRAPHIFY_OUT` from project root (or used a relative env path).
-- **Fix:** Run **`ai-spector graphify update`** (absolute `GRAPHIFY_OUT`, cwd = project root, removes stale folders). Do not copy files manually unless CLI failed and user approved workaround.
+- **Fix:** Run **`ai-spector index`**. For fully stale domain detail, re-run **`/analyze`** → fresh `knowledge.json`.
 
 ---
 
@@ -203,7 +174,7 @@ After any workaround that wrote docs or graph patches: **`graph validate`** (and
 - 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).
-- Wrong CLI flags the agent introduced (e.g. `graphify update --graph`) — fix and retry immediately.
+- Wrong CLI flags the agent introduced — fix and retry immediately.
 
 ## Agent must ask user before
 

package/scaffold/cursor/skills/ai-spector/references/generate-graph.md

@@ -3,21 +3,28 @@
 Used by **SRS**, **basic design**, and **detail design** generation skills.
 
 | Orchestration (scope, confirm, wave checklist, finish) | [generate-workflow.md](./generate-workflow.md) |
-| Per-command DAG + intent tables | `generate-srs.md`, `generate-basic-design.md`, `generate-detail-design.md` |
+| Per-command DAG + intent tables | each skill's `references/runbook.md` |
 
 **Principle:** Accuracy over speed. The graph is the planner, context loader, and registry of what was written.
 
-**Parallelism:** Allowed **only inside a DAG wave** — targets that do not depend on each other (and whose dependencies are already ingested + indexed when required). Never parallelize across waves.
+**Parallelism:** Allowed **only inside a DAG wave**. Never across waves.
 
-## Agent rules (non-negotiable)
+## Edge presets (use these in queries — don't copy-paste long lists)
 
-1. **Plan from DAG + graph** — build **waves** from `dag.*.json` (see § Waves); map each node to a graph seed via `dag.*.graph-seeds.json`.
-2. **Context before write** — for **every** target (batch or single), run CLI queries below; read `projectionPaths` and domain `nodes`/`edges`. No invented UC/F text.
-3. **Dependencies before write** — for each target’s `dependsOn`, `graph query` dependency seeds and **read existing markdown** when `rendersTo` exists.
-4. **Ingest before next wave** — after each file (or after a whole wave), merge `rendersTo` + `dependsOn` (see § Ingest), then `graph validate`. The next wave must see upstream `rendersTo` edges.
-5. **No shortcuts** — no glob `docs/srs/**`, no skipping validate/query, no index-first generation, no batching targets that have a DAG dependency on each other.
+| Preset name | Edges | Use for |
+|-------------|-------|---------|
+| `CONTEXT` | `listedIn,definedIn,describedIn,satisfies,dependsOn,rendersTo,partOf,contains` | Target neighborhood — what exists and where it lives |
+| `DEPS` | `rendersTo,dependsOn,listedIn,satisfies,partOf,contains` | Dependency context — what upstream docs look like |
+| `IMPACT` | `satisfies,tracesTo,dependsOn,references,relatesTo` | What a change would affect |
 
-## CLI workflow per target
+## Agent rules
+
+1. **Plan from DAG** — build waves from `dag.*.json`; map each DAG node → graph seed via `dag.*.graph-seeds.json`.
+2. **Context before write** — for **every** target run the CONTEXT query; read `projectionPaths`. No invented UC/F text.
+3. **Merge once per wave, not per file** — write all files in a wave, then do one batch merge + one validate. Do not merge after every file.
+4. **No shortcuts** — no glob `docs/srs/**`, no skipping validate, no batching targets that have a DAG dependency on each other.
+
+## CLI workflow
 
 ### A. Gate (once per command)
 
@@ -25,75 +32,52 @@ Used by **SRS**, **basic design**, and **detail design** generation skills.
 ai-spector graph validate
 ```
 
-### B. Plan
-
-- Load `dag.srs.json` (or matching DAG).
-- Load `dag.srs.graph-seeds.json` for `document` seeds.
-- Build **waves** (below).
-- Skip `good` files unless user asked to regenerate; use `graph impact` when replacing content.
-
-#### Waves (when batch is allowed)
+### B. Plan — waves
 
 Assign each DAG node to wave `0`, `1`, `2`, …:
 
-- **Wave 0:** nodes with empty `dependsOn`.
-- **Wave k:** nodes whose `dependsOn` are all in waves `< k` (not in the same wave).
-
-**Same wave = safe to generate in parallel** (no target in the wave depends on another target in that wave).
-
-**Example** (`dag.srs.json`): after `srs.feature-details`, both `srs.data-requirements` and `srs.external-interfaces` are in the **same wave** (each depends on feature-details only, not on each other) → may generate both in one batch.
-
-**Forbidden batch:** `srs.use-cases` + `srs.features-list` (features-list depends on use-cases).
-
-**User asks for specific files** (case 2): map paths → DAG nodes; include dependency closure; batch only within same wave.
+- **Wave 0:** nodes with empty `dependsOn`
+- **Wave k:** nodes whose `dependsOn` are all in waves `< k`
 
-**User describes scope in words** (case 3): [generate-workflow.md](./generate-workflow.md) § Case 3 — confirm before write; intent phrase tables stay in each `generate-*.md`.
+**Same wave = parallel OK.** Example: after `srs.feature-details`, both `srs.data-requirements` and `srs.external-interfaces` are in the same wave → generate both in one batch.
 
 Present plan as:
 
-| Wave | DAG ids (parallel OK within row) | Seeds | Blocked until |
-|------|----------------------------------|-------|---------------|
+| Wave | DAG ids (parallel OK) | Seeds | Blocked until |
+|------|----------------------|-------|---------------|
 | 0 | … | … | — |
 | 1 | … | … | wave 0 merged + validate |
 
-### C. Before writing file `T`
+### C. Before writing each target
 
-**1. Dependency context** (each DAG `dependsOn` id → graph seed):
+**Dependency context** (once per wave, for each DAG `dependsOn`):
 
 ```bash
-ai-spector graph query <depSeedId> --direction both --depth 2 --edges rendersTo,dependsOn,listedIn,satisfies,definedIn,partOf,contains --json
+ai-spector graph query <depSeedId> --direction both --depth 2 --edges DEPS --json
 ```
 
-Open existing `projectionPaths` from the JSON (already-generated SRS chapters).
-
-**2. Target neighborhood** (domain + structure):
+**Target neighborhood:**
 
 ```bash
-ai-spector graph query <targetSeedId> --direction both --depth 4 --edges listedIn,definedIn,describedIn,satisfies,dependsOn,references,rendersTo,partOf,contains --json
+ai-spector graph query <targetSeedId> --direction both --depth 4 --edges CONTEXT --json
 ```
 
-**3. Impact scope** (when regenerating or unsure):
+**When regenerating** (unsure what changed):
 
 ```bash
 ai-spector graph impact <targetSeedId> --change content_change --json
 ```
 
-Respect `regenerate` / `review` buckets; do not rewrite unrelated chapters.
-
-**4. Data-source supplement** — only for gaps after graph query succeeds; cite paths in the doc.
-
 ### D. Write
 
-- **Read the template** from `.ai-spector/templates/` (path = DAG `template` value, e.g. `srs/3-use-cases.md`, `basic_design/list-api-template.md`). If missing, stop and ask the user to run `npx ai-spector init`.
-- Fill that template for the target only — keep all required headings/sections; replace placeholders with graph-backed content.
+- Read template from `.ai-spector/templates/` (DAG `template` field). If missing → stop and ask user to run `npx ai-spector init`.
+- Fill for this target only; keep all required headings; replace placeholders with graph-backed content.
 - Cross-check every UC/F reference against `nodes` from query JSON.
 - Add section anchors `<!-- section:sec.... -->` where templates expect them.
 
-### E. Ingest (mandatory — per file or per wave)
-
-After **each file**, or once at **end of a parallel wave** (single patch listing all files in that wave):
+### E. Ingest (once per wave — not per file)
 
-Write `.ai-spector/.docflow/extract/projection-patch.json`:
+After **all files in a wave** are written, write a single patch covering the whole wave:
 
 ```json
 {
@@ -101,51 +85,46 @@ Write `.ai-spector/.docflow/extract/projection-patch.json`:
   "nodes": [],
   "edges": [
     { "type": "rendersTo", "from": "doc.srs.3-use-cases", "to": "docs/srs/3-use-cases.md" },
-    { "type": "dependsOn", "from": "doc.srs.3-use-cases", "to": "doc.srs.1-introduction" },
-    { "type": "dependsOn", "from": "doc.srs.3-use-cases", "to": "doc.srs.2-overall-description" }
+    { "type": "dependsOn", "from": "doc.srs.3-use-cases", "to": "doc.srs.1-introduction" }
   ]
 }
 ```
 
-Then:
-
 ```bash
 ai-spector graph merge .ai-spector/.docflow/extract/projection-patch.json
 ai-spector graph validate
 ```
 
-- `rendersTo`: `from` = graph `document` (or section) id, `to` = repo-relative markdown path.
-- `dependsOn`: mirror DAG edges between **document** ids (downstream queries use these for context).
-- Per-domain files (`UC-01`, `F-01`): also link `definedIn` from domain node to detail sections if applicable.
+Then — for SRS and basic-design waves — run index before starting the next wave:
 
-**Wave rule:** finish all writes in wave `k`, merge **all** `rendersTo` / `dependsOn` for that wave, `graph validate`, then **`ai-spector index`** (basic design and SRS generation — see command files), then start wave `k+1`.
+```bash
+ai-spector index
+```
 
-Alternative repair: **`/sync-graph`** — not a substitute for merge between waves.
+**Exception:** if a file within the wave is a dependency for another file in the **same** wave (unusual — check the DAG), merge that file's `rendersTo` before writing the dependent. For standard DAGs this never happens within a wave.
 
 ### F. Per-domain detail files
 
-For `mode: perFeature` / `perDomain` DAG nodes (SRS):
+For `mode: perFeature` / `perDomain` (SRS):
 
 - Seed = domain id (`UC-01`, `F-01`), not only chapter document.
-- Query with `--depth 4`; include inbound `satisfies` / `dependsOn`.
-- `rendersTo` from resolved output path (e.g. `docs/srs/03-use-cases/uc-01-....md`).
+- Query with `--depth 4` + CONTEXT edges; include inbound `satisfies`.
+- Batch all per-domain files in their wave; merge all `rendersTo` once at wave end.
 
-For `mode: perEndpoint` / `perScreen` (basic design — `dag.basic-design.graph-seeds.json`):
+For `mode: perEndpoint` / `perScreen` (basic design):
 
-- **Do not** expand one file per `F-xx` feature.
-- **perEndpoint:** read `docs/basic-design/api-list.md` §3 Endpoint Summary; one markdown file per table row under `docs/basic-design/api/<slug>.md` (`slug` from method + path, e.g. `post-resource-id`).
-- **perScreen:** read `docs/basic-design/list-screens.md` §4 Screen Index; one file per screen under `docs/basic-design/screens/<slug>.md`.
-- List chapter lives at `docs/basic-design/list-screens.md` (not under `screens/`).
-- Query SRS + related `F-xx` for context on each endpoint/screen; ingest `doc.bd.api-*` / `doc.bd.screen-*` with `contains` from list chapter.
+- **perEndpoint:** read `docs/basic-design/api-list.md` §3; one file per row under `docs/basic-design/api/<slug>.md`.
+- **perScreen:** read `docs/basic-design/list-screens.md` §4; one file per screen under `docs/basic-design/screens/<slug>.md`.
+- Ingest `doc.bd.api-*` / `doc.bd.screen-*` with `contains` from list chapter in the wave-end merge.
 
-## Accuracy checklist (before marking target done)
+## Accuracy checklist
 
 - [ ] `graph query` run for target and every DAG dependency with existing files
 - [ ] All UC/F ids in markdown exist as graph nodes
-- [ ] `rendersTo` + `dependsOn` merged for this file
-- [ ] `graph validate` passes
+- [ ] Wave-end `rendersTo` + `dependsOn` merged in one patch
+- [ ] `graph validate` passes before next wave
 - [ ] No placeholder lorem / empty tables unless marked TBD in `gaps.json`
 
 ## On CLI failure
 
-[cli-failures.md](./cli-failures.md) — pause; offer fix / workaround / pause; do not generate from memory without user-approved workaround.
+[cli-failures.md](./cli-failures.md) — pause; offer fix / workaround / pause; do not generate from memory.

package/scaffold/cursor/skills/ai-spector/references/generate-workflow.md

@@ -104,7 +104,7 @@ Append one line per target to `.ai-spector/.docflow/logs/generate-<layer>.log` (
 3. Suggest the command doc’s summary command (`/summary srs`, `/summary basic-design`, …) when listed there
 4. Optional: `/visualize-graph` for review
 
-Index flags: `--skip-graphify` when only markdown under `docs/` changed; `--force-graphify` when `docs/data-source/` must rebuild.
+Index flags: `--skip-doc-semantics` to skip UC/F body parsing; `--graph-only` for structure + merge only.
 
 ## Guardrails
 

package/scaffold/cursor/skills/ai-spector/references/graph.md

@@ -14,7 +14,6 @@ Run from project root: `npx ai-spector …` if needed.
 
 ```bash
 ai-spector analyze
-ai-spector graphify update
 ai-spector graph merge --from-knowledge
 ai-spector graph validate
 ai-spector graph visualize [--open]

package/scaffold/cursor/skills/ai-spector-generate-prototype/SKILL.md

@@ -2,9 +2,9 @@
 name: ai-spector-generate-prototype
 description: >-
   Generates static HTML/CSS/JS screen prototypes from basic-design screen specs and bundled UI themes.
-  Use when the user asks for HTML prototype, screen mockups, prototype/src files, or to pick a theme
-  (vercel, stripe, etc.). Do not use for markdown SRS/basic/detail design only, or graph operations
-  without HTML output.
+  Use when the user asks for HTML prototype, screen mockups, or prototype/src files. Asks user to
+  choose a theme if none is stored; uses stored preference on subsequent runs. Do not use for
+  markdown SRS/basic/detail design only, or graph operations without HTML output.
 paths:
   - "prototype/**"
 ---
@@ -15,13 +15,14 @@ paths:
 
 ## Required reading
 
-[references/runbook.md](references/runbook.md) — theme setup, manifest, HTML rules.
+[references/runbook.md](references/runbook.md) — theme resolution (no upfront picker), manifest, HTML rules.
 
 ## Checklist
 
 ```
 - [ ] list-screens + screen detail docs exist
-- [ ] prototype setup --theme <name>
+- [ ] theme resolved (request → theme.json → manifest → prototype.config.json → **ask user if none stored**)
+- [ ] prototype setup (with --theme when needed; persists when user named a theme)
 - [ ] one .html per screen; prototypeStem from manifest
 - [ ] prototype manifest && prototype validate --strict
 ```

package/scaffold/cursor/skills/ai-spector-generate-prototype/references/runbook.md

@@ -7,7 +7,7 @@ Generate **static HTML** prototypes from basic-design screen specs. All setup an
 ## Philosophy
 
 - **Screen design is source of truth** — `docs/basic-design/list-screens.md` + `docs/basic-design/screens/<slug>.md`
-- **Theme is chosen up front** — design tokens live in `prototype/DESIGN.md` (copied from bundled `assets/themes/<name>/`)
+- **Theme must be confirmed before generating** — if no theme is stored, ask the user to choose one before running setup. Once the user has chosen (stored in `prototype/theme.json` or `prototype.config.json`), never ask again.
 - **One HTML per screen** — `prototype/src/<prototypeStem>.html` must match `prototype/manifest.json`
 - **Static only** — HTML/CSS/JS under `prototype/`; no frameworks, no CDN unless the theme DESIGN allows it
 
@@ -26,21 +26,39 @@ Generate **static HTML** prototypes from basic-design screen specs. All setup an
 
 ## Required behavior (agent runs CLI)
 
-### 1. Choose theme and setup workspace
+### 1. Resolve theme and setup workspace
 
-List themes if the user did not specify one:
+**Resolution order** (first match wins):
 
-```bash
-ai-spector prototype themes
+1. Theme named in this request (`--theme`, “use stripe theme”, etc.)
+2. `prototype/theme.json` → `themeName`
+3. `prototype/manifest.json` → `themeName` (non-empty)
+4. `.ai-spector/.docflow/config/prototype.config.json` → `defaultTheme`
+
+**If no stored theme is found**, ask the user to choose before proceeding:
+
+```
+No theme is saved yet. Which UI theme would you like for your prototype?
+Run `ai-spector prototype themes` to see all options, or name one (e.g. vercel, stripe, notion, linear.app).
 ```
 
+Wait for the user's answer — do **not** silently default to `vercel`. Once the user names a theme, proceed with setup; the choice is persisted and will not be asked again.
+
 Setup (creates `prototype/`, copies `DESIGN.md`, seeds manifest when `list-screens.md` exists):
 
 ```bash
-ai-spector prototype setup --theme <name>
+ai-spector prototype setup --theme <resolved-name>
 ```
 
-Default theme: `vercel` (override with `--theme` or user preference).
+Omit `--theme` only when setup can infer the same name from stored files (the CLI reads `theme.json` / config automatically).
+
+**Persist** when the user explicitly names a theme in this session: `prototype setup --theme <name>` updates `prototype/theme.json` and saves `defaultTheme` in `prototype.config.json` for later runs.
+
+List themes when the user asks (“what themes?”, “list prototype themes”):
+
+```bash
+ai-spector prototype themes
+```
 
 ### 2. Plan screens
 
@@ -76,13 +94,15 @@ git commit -m "chore(prototype): add HTML screens (<theme>)"
 
 | User says | Action |
 |-----------|--------|
-| “use stripe theme”, `--theme stripe` | `prototype setup --theme stripe --force-design` if switching theme mid-branch |
+| “use stripe theme”, `--theme stripe` | `prototype setup --theme stripe` (persists preference); add `--force-design` if switching theme mid-branch |
 | “what themes?” | `ai-spector prototype themes` |
-| no preference | `vercel` or project default from `prototype.config.json` |
+| no theme in message, no stored theme | **Ask the user** to name a theme before proceeding |
+| no theme in message, stored theme found | Use stored theme — do not ask |
 
 ## Accuracy checklist
 
-- [ ] `prototype setup` run with agreed theme
+- [ ] Theme resolved without blocking theme picker (unless user asked to list themes)
+- [ ] `prototype setup` run with resolved theme
 - [ ] Every generated file name matches `prototypeStem` in manifest
 - [ ] Wireframe/layout from screen detail doc reflected in HTML
 - [ ] Tokens from `prototype/DESIGN.md` only (no random CDN)

package/scaffold/cursor/skills/ai-spector-generate-srs/references/runbook.md

@@ -60,7 +60,7 @@ After last wave ([generate-workflow.md](../../ai-spector/references/generate-wor
 ai-spector index
 ```
 
-`index` parses UC/F/actor ids and adds `doc.srs.uc-*` / `doc.srs.f-*` document + section nodes. Use `--force-graphify` only when data-source hashes must rebuild.
+`index` parses UC/F/actor ids from markdown bodies and adds `doc.srs.uc-*` / `doc.srs.f-*` document + section nodes.
 
 Suggest `/summary srs` after index. Log: `.ai-spector/.docflow/logs/generate-srs.log`.
 

package/scaffold/cursor/skills/ai-spector-graph/references/analyze.md

@@ -18,7 +18,7 @@ The agent runs all CLI steps below — see [WORKFLOW.md](../../WORKFLOW.md).
 
 ## Required Behavior
 
-### 0. Prepare graph structure (CLI — agent runs first)
+### 0. Prepare graph structure
 
 ```bash
 ai-spector analyze
@@ -26,38 +26,27 @@ ai-spector analyze
 
 Creates section/document nodes from templates. Do not ask the user to run this separately.
 
-### A. Extract (semantic-first; Graphify sidecar)
+### A. Extract from markdown sources
 
-1. Load `data-source.json`, `analyze.graphify.json`.
-2. **Graphify paths (from `ai-spector init`):**
-   - Output dir: `.ai-spector/.docflow/graph/graphify-out` (`GRAPHIFY_OUT`)
-   - Graph file: `.ai-spector/.docflow/graph/graphify-out/graph.json` (MCP + queries use `--graph` only on `graphify query`, not on `update`)
-3. **Code ingest sidecar (CLI — agent runs):**
+1. Load `data-source.json` to resolve the data-source root (default: `docs/data-source/`).
+2. **Read all markdown files** under that root directly — each file is well-structured markdown with headings, tables, and labeled fields.
+3. Extract the following entities, mapping them to their canonical ids and fields:
 
-```bash
-ai-spector graphify update
-```
-
-This runs `graphify update docs/data-source` with `GRAPHIFY_OUT` set. **Forbidden:** `graphify update … --graph …` (`unknown option: --graph`).
-
-Fallback if needed:
-
-```bash
-GRAPHIFY_OUT=.ai-spector/.docflow/graph/graphify-out graphify update docs/data-source
-```
-
-The command removes stale `docs/data-source/graphify-out/` if Graphify created it by mistake.
+| Entity | `id` | Required fields | Links |
+|--------|------|-----------------|-------|
+| use case | `UC-01` | `title` | — |
+| feature | `F-01` | `title` | `satisfies`: `["UC-01"]` |
+| actor | `actor.customer` | `name` or `title` | — |
+| functional requirement | `FR-01` | `title` | `tracesTo` optional |
+| NFR | `NFR-01` | `title` | — |
+| data entity | `ENT-Order` | `name` | — |
 
-4. **Semantic extract (Graphify MCP)** — query profiles in `analyze.graphify.json`; use graph at `graphJsonPath` for `graphify query "…" --graph .ai-spector/.docflow/graph/graphify-out/graph.json`.
-5. Resolve paths → `scope.json` → `sources`.
-6. Query / fallback to extract:
-   - actors, useCases, features, functionalRequirements, nfrs, entities, interfaces, constraints, openQuestions
-7. Persist staging (canonical for AI Spector):
-   - `.ai-spector/.docflow/analysis/knowledge.json` (see package `schemas/schema.knowledge.json`)
+4. Persist staging (canonical for AI Spector):
+   - `.ai-spector/.docflow/analysis/knowledge.json` (schema: `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)
+### B. Commit to graph
 
 ```bash
 ai-spector graph merge --from-knowledge
@@ -70,18 +59,6 @@ Optional for the user:
 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`.
@@ -94,19 +71,16 @@ Update `state.json`: `analysis.lastRunAt`, `analysis.dataSource`, scope hash. Me
 
 ## CLI steps — stop on first failure
 
-Run in order. If any step fails, **pause** and use [cli-failures.md](../../ai-spector/references/cli-failures.md) (show full CLI output; offer fix / workaround / pause). Do not skip to merge, validate, or generate SRS without user choice.
-
 | Step | Command |
 |------|---------|
 | 0 | `ai-spector analyze` |
 | B | `ai-spector graph merge --from-knowledge` |
 | B | `ai-spector graph validate` |
 
-Graphify indexing is **sidecar** for code-aware context. Markdown-only or empty sources may skip Graphify and continue.
-Only block if semantic extract / `knowledge.json` generation fails.
+If any step fails, **pause** and use [cli-failures.md](../../ai-spector/references/cli-failures.md). Do not skip to generate SRS without user choice.
 
 ## If blocked
 
-Use the **Blocked** template in [cli-failures.md](../../ai-spector/references/cli-failures.md). Include which step failed, exit code, verbatim CLI output, fix steps, optional workaround, and **1 / 2 / 3** choices. Offer to apply small fixes (e.g. one bad `listedInSection`) then re-run the same step.
+Use the **Blocked** template in [cli-failures.md](../../ai-spector/references/cli-failures.md). Include which step failed, exit code, verbatim CLI output, fix steps, and **1 / 2 / 3** choices.
 
 **Do not:** hand-edit the full graph, generate SRS, or read all of `docs/srs/` as a workaround.