ai-spector 0.4.2 → 0.4.4

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

@@ -1,128 +1,68 @@
-# Document generation workflow (shared)
+# Document generation workflow
 
-Used by **SRS**, **basic design**, and **detail design** generation skills.
+Used by SRS and basic design skills.
 
-| Topic | Document |
-|-------|----------|
-| Graph query, merge patch shape, waves algorithm | [generate-graph.md](./generate-graph.md) |
-| CLI failure recovery (fix / workaround / pause) | [cli-failures.md](./cli-failures.md) |
-| Layer-specific DAG, intent tables, waves | each skill’s `references/runbook.md` |
+**References (load when needed):**
+- Graph queries / merge / ingest → [generate-graph.md](./generate-graph.md)
+- Context compaction / sub-agents → [context-management.md](./context-management.md)
+- CLI failures → [cli-failures.md](./cli-failures.md)
 
-**Not used by** HTML prototype generation (`ai-spector-generate-prototype` runbook).
+## Language check (before first write)
 
-## Language — check before any write
+Read `.ai-spector/.docflow/config/language.json`. If `documentLanguage` is empty or missing, load [language-picker.md](./language-picker.md) and run the picker. All content in the chosen language; IDs, paths, code never translated.
 
-**Read [language-picker.md](./language-picker.md) before generating any document content.**
+## Context hygiene (always)
 
-1. Check `.ai-spector/.docflow/config/language.json` for `documentLanguage`.
-2. If missing, run the language-picker flow (ask → persist → continue). Do not write until confirmed.
-3. Apply the enforcement rules in language-picker.md to every file written: all content in the target language, IDs/paths/code never translated, no mixing.
+1. Only read files listed in `projectionPaths` — no `docs/**` glob.
+2. Raw graph JSON stays in the sub-agent, not main context.
+3. After writing a file, record path + status only; discard content.
+4. For runs of 5+ files: compact after every wave + every 5 per-domain files. Load [context-management.md](./context-management.md) for the sub-agent pattern.
 
-## Philosophy
+## Scope
 
-- **Accuracy over speed** — full graph context before every write; ingest before the next wave.
-- **Graph in, graph out** — query neighbors + dependencies before; `rendersTo` + `dependsOn` after ([generate-graph.md](./generate-graph.md) § E).
-- **Parallel when safe** — only targets in the **same DAG wave** with dependencies already merged + validated (and **indexed** when the command doc requires it).
+| Case | User input | Behavior |
+|---|---|---|
+| **1 — All** | "generate all SRS" | Every DAG node. Skip `good` files unless user asked to regenerate. |
+| **2 — Explicit** | file paths in chat | Map → DAG nodes → dependency closure. Same wave only. |
+| **3 — Words** | "API list and screens" | Scope table → user confirms → generate. No write before yes. |
 
-## Scope — three ways to choose targets
-
-Each generate command defines its DAG and intent hints. The pattern is always:
-
-| Case | User input | Agent behavior |
-|------|------------|----------------|
-| **1 — All** | “generate all SRS” / full layer | Plan every DAG node (+ per-domain expansions). Respect `good` on disk unless user asked to regenerate. |
-| **2 — Explicit paths** | paths in chat (`docs/…/file.md`) | Map paths → DAG nodes → seeds. Include **dependency closure**. Batch only within the same wave. |
-| **3 — Words** | “API list and screens” | Proposed scope table → **user confirms** → generate. **Do not write until approved.** |
-
-Paths are repo-relative. Mixed args: treat paths as case 2, free text as case 3.
-
-## Case 3 — confirm before write (mandatory)
-
-1. Parse the request against that command’s `dag.*.json`, `dag.*.graph-seeds.json`, and graph domain nodes.
-2. Build a **proposed scope** table (columns: DAG id, output path, seed, reason, prerequisites / deps).
-3. Include **dependency closure** — ancestors that are `missing_file` / `missing_content` run in earlier waves unless the user skips deps.
-4. Ask:
-
-```text
-I plan to generate the following (N items, waves X–Y). Prerequisites run first.
-Reply **yes** to proceed, **no** to cancel, or edit the list.
-```
-
-5. **Stop** without explicit **yes**. Do not write on assumption.
-6. If ambiguous (e.g. “features” = list vs all detail files), ask **one** clarifying question before the table.
-
-Command-specific phrase → DAG mappings live in each `generate-*.md` (not here).
-
-## Prerequisites (all DAG generate commands)
-
-1. Merged graph — normally after **analyze** (data-source ingest).
-2. Gate:
-
-```bash
-ai-spector graph validate
-```
-
-On errors, pause and follow recovery in [cli-failures.md](./cli-failures.md).
-
-3. `workflow.dependencies.json` entry for that command (SRS minimum, etc.).
+Case 3: build scope table (DAG id, output path, seed, reason, deps) → ask → stop until confirmed.
 
 ## Plan (once per invocation)
 
-1. **Select targets** (case 1 / 2 / 3; case 3 = confirm first).
-2. Topological sort selected nodes + required dependency ancestors.
-3. Map each node via `dag.*.graph-seeds.json` → query seeds + ingest document ids.
-4. Classify disk per output: `good` | `missing_content` | `missing_file` — do not overwrite `good` without user intent.
-5. Assign **waves** ([generate-graph.md](./generate-graph.md) § Waves). Present wave table (brief for cases 1–2; case 3 table already confirmed).
-
-## Per wave, then per target
+1. Select targets (case 1/2/3).
+2. Topological sort + dependency closure.
+3. Map DAG nodes → seeds via `dag.*.graph-seeds.json`.
+4. Classify disk: `good` | `missing_content` | `missing_file`.
+5. Assign waves; present wave table.
 
-For **each wave** in order:
-
-### Wave checklist
+## Wave checklist
 
 ```
-- [ ] All targets in this wave identified (parallel OK within wave only)
-- [ ] For each target: graph query deps + target (_generate-graph § C)
+- [ ] Targets for this wave identified (parallel OK within wave only)
+- [ ] Per target: delegate graph queries to sub-agent; receive ≤400-word summary
+- [ ] Load matching srs-context/ or bd-context/ section for this doc type
 - [ ] Read template from .ai-spector/templates/ — never invent structure
-- [ ] Write file(s)
-- [ ] Merge projection patch (rendersTo + dependsOn) for this wave
-- [ ] ai-spector graph validate — pass before next wave
-- [ ] ai-spector index when command doc requires (basic design: every wave; SRS: see generate-srs.md)
+- [ ] Write file from summary + template
+- [ ] Merge projection patch (rendersTo + dependsOn) for the wave
+- [ ] ai-spector graph validate
+- [ ] ai-spector index (basic design: every wave; SRS: see runbook)
+- [ ] /compact with plan summary before next wave
 ```
 
-### Per target (summary)
-
-Details: [generate-graph.md](./generate-graph.md) § C–E.
-
-1. **Query** — dependency seeds (depth 2) + target seed (depth 4); `graph impact` when regenerating.
-2. **Read** — `projectionPaths` and cited `docs/data-source/**` only; no glob of entire `docs/`.
-3. **Write** — from DAG template; graph-backed UC/F/API/screen names only.
-4. **Ingest** — merge patch; validate before leaving the wave.
-
-**Forbidden:** targets from different waves in one batch; next wave before merge + validate; skipping `rendersTo` on generated docs.
-
-### Log (optional)
-
-Append one line per target to `.ai-spector/.docflow/logs/generate-<layer>.log` (create dir if needed): timestamp, seed, path, validate OK.
-
-## Finish (end of command)
-
-1. `ai-spector graph validate`
-2. `ai-spector index` if not already run after the last wave (required for SRS — see `generate-srs.md`)
-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-doc-semantics` to skip UC/F body parsing; `--graph-only` for structure + merge only.
+Per target: Delegate → Receive summary → Write → Log path/status → Ingest.
 
 ## Guardrails
 
-- **Parallel only within a wave** — never across waves; never when A `dependsOn` B in the DAG.
-- **Every target** gets its own `graph query` + dependency queries before write.
-- **Every wave** ends with merge + validate (and **index** when the command doc says so) before the next wave.
-- **Case 3** requires explicit user **yes** before any write.
-- On `graph query` / `merge` / `validate` / `index` failure → pause and recover per [cli-failures.md](./cli-failures.md).
-- Prefer graph `nodes`/`edges` over stale `knowledge.json` for generation text.
+- Parallel only within a wave.
+- Sub-agent per target — never reuse a previous target's summary.
+- No raw graph JSON in main context.
+- No speculative reads — projectionPaths only.
+- Case 3 requires explicit yes before any write.
+- On CLI failure → load [cli-failures.md](./cli-failures.md).
 
-## If blocked
+## Finish
 
-[cli-failures.md](./cli-failures.md). Re-run the same task after fixes. Common upstream fix: **analyze** first, or generate SRS before basic design.
+1. `ai-spector graph validate`
+2. `ai-spector index` if not already run after last wave
+3. Suggest summary command when runbook lists one

package/scaffold/cursor/skills/ai-spector/references/project-conventions.md

@@ -16,7 +16,6 @@ Missing templates → `npx ai-spector init --force`.
 | Source input | `docs/data-source/` |
 | SRS | `docs/srs/` |
 | Basic design | `docs/basic-design/` |
-| Detail design | `docs/detail-design/` |
 | HTML prototype | `prototype/src/` |
 
 ## Document language

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

@@ -2,20 +2,16 @@
 name: ai-spector-generate
 description: >-
   Routes ambiguous document-generation requests to the correct AI Spector layer skill (SRS, basic
-  design, detail design, or HTML prototype). Use only when the user says generate docs or generate
-  requirements without naming a layer. Do not use when the request clearly targets SRS, screens, APIs,
-  detail design, or prototype HTML.
+  design, or HTML prototype). Use only when the user says generate docs or generate requirements
+  without naming a layer. Do not use when the request clearly targets SRS, screens, APIs, or prototype HTML.
 ---
 
 # AI Spector — Generate (router)
 
-Ask one question or infer from context, then **switch skill** and read that skill’s runbook:
+Ask one question or infer from context, then **switch skill** and read that skill's runbook:
 
 | Layer | Skill |
 |-------|-------|
 | Requirements / SRS | `ai-spector-generate-srs` |
 | Screens, APIs, DB | `ai-spector-generate-basic-design` |
-| Implementation detail | `ai-spector-generate-detail-design` |
 | HTML mockups | `ai-spector-generate-prototype` |
-
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md) · **Pipeline:** [../../WORKFLOW.md](../../WORKFLOW.md)

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

@@ -4,31 +4,33 @@ description: >-
   Generates or updates basic design documents from the traceability graph and SRS: screen list and
   screen details, API list and endpoint details, database design under docs/basic-design/. Use when
   the user asks for basic design, wireframes, screen map, API design, ERD, or list-screens.md. Do not
-  use for SRS-only work, detail design, HTML prototype, or graph analyze/index without doc generation.
+  use for SRS-only work, HTML prototype, or graph analyze/index without doc generation.
 paths:
   - "docs/basic-design/**"
   - ".ai-spector/templates/basic_design/**"
 ---
 
-# AI Spector — Generate basic design
-
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
-
-## Required reading
+# Generate Basic Design
 
+## Load at start
 1. [references/runbook.md](references/runbook.md)
 2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md)
-3. [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) § perEndpoint / perScreen
 
-## Checklist
+## Load when needed
 
-```
-- [ ] language confirmed (language-picker.md — check before first write)
-- [ ] graph validate; SRS on disk
-- [ ] index after every wave (mandatory)
-- [ ] one file per endpoint row / Screen Index row — not per F-xx
-```
+| Situation | Load |
+|---|---|
+| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
+| Writing DB design | [references/bd-context/db-design.md](references/bd-context/db-design.md) |
+| Writing API list | [references/bd-context/api-list.md](references/bd-context/api-list.md) |
+| Writing API detail (per endpoint) | [references/bd-context/api-detail.md](references/bd-context/api-detail.md) |
+| Writing screen list | [references/bd-context/screen-list.md](references/bd-context/screen-list.md) |
+| Writing screen detail (per screen) | [references/bd-context/screen-detail.md](references/bd-context/screen-detail.md) |
+| Graph queries / merge | [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) |
+| CLI fails | [../ai-spector/references/cli-failures.md](../ai-spector/references/cli-failures.md) |
+| Run of 5+ files | [../ai-spector/references/context-management.md](../ai-spector/references/context-management.md) |
 
-## Natural language
+## On CLI failure
+Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
 
-“basic design”, “screen list”, “API list”, “wireframe for login” → this skill.
+"basic design", "screen list", "API list", "wireframe for login" → this skill.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/api-detail.md

@@ -0,0 +1,27 @@
+# Graph → API Detail (per endpoint)
+
+Queries:
+```bash
+ai-spector graph query <F-xx> --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <UC-xx> --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query <entityId> --direction both --depth 2 --edges CONTEXT --json
+```
+
+| Template section | Graph source |
+|---|---|
+| **Summary / Operation ID** | UC `name`; camelCase from method + entity |
+| **Source Requirement** | F-xx id + name; UC-xx id + name |
+| **Auth** | Actor `authRequired`; UC precondition `authenticated` |
+| **Path params** | Entity field `pk: true`; UC flow step passing an id |
+| **Query params** | UC filter/search flow steps; F-xx filter requirements |
+| **Request body** | F-xx `inputData` → name, type, required, validation; UC `mainFlow` input steps |
+| **Response 2xx** | F-xx `outputData` + entity `fields` for returned object |
+| **Response 400** | F-xx `errorHandling` validation; entity field constraints |
+| **Response 401/403** | Actor auth; UC precondition violations |
+| **Response 404** | UC exception "resource not found" |
+| **Response 409** | UC exception "already exists" / "conflict" |
+| **§2 Data Model** | Entity `fields`; `relatesTo` edges for nested objects |
+| **§3 Error Codes** | All UC exception flows + F-xx error handling → HTTP codes |
+| **§4 Rate Limiting** | NFR nodes tagged `rateLimit` or `performance` |
+
+**Rule:** Every request field → F-xx `inputData` or UC flow input. Every response field → entity `fields` or F-xx `outputData`. No invented fields.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/api-list.md

@@ -0,0 +1,26 @@
+# Graph → API List
+
+Queries:
+```bash
+ai-spector graph query doc.bd.list-api --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query doc.srs.6-external-interfaces --direction both --depth 2 --edges DEPS --json
+```
+
+Derive each endpoint — **no invented endpoints**:
+
+| Endpoint rule | Graph evidence required |
+|---|---|
+| GET list | `dataEntity` + UC with list/search flow |
+| GET detail | `dataEntity` + UC with single-record read |
+| POST create | `dataEntity` + UC with create/submit flow |
+| PUT/PATCH update | `dataEntity` + UC with edit flow |
+| DELETE | `dataEntity` + UC with delete/archive flow |
+| Auth (login/logout) | Actor node + auth UC |
+
+| Column | Graph source |
+|---|---|
+| **Method** | Action type: GET/POST/PUT/DELETE |
+| **Path** | Entity name + UC slug; plural snake_case collections |
+| **Summary** | UC `name` or F-xx `name` |
+| **Auth required** | Actor `authRequired`; UC precondition `authenticated` |
+| **Source F-xx / UC-xx** | F-xx and UC-xx nodes that `satisfies` this endpoint |

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/db-design.md

@@ -0,0 +1,22 @@
+# Graph → DB Design
+
+Queries:
+```bash
+ai-spector graph query doc.bd.db-design --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <entityId> --direction both --depth 3 --edges CONTEXT --json  # per entity
+ai-spector graph query doc.srs.5-data-requirements --direction both --depth 2 --edges DEPS --json
+```
+
+| Template section | Graph source |
+|---|---|
+| **§1 DBMS** | NFR nodes tagged `infrastructure` or `database`; data-source mentions |
+| **§2 ERD entities** | All `dataEntity` nodes → table names (snake_case) |
+| **§2 ERD relationships** | `relatesTo` / `dependsOn` edges between entities → cardinality from edge `label` |
+| **§3 Table list** | All `dataEntity` nodes → `description` |
+| **§4 Fields** | Entity `fields` array → name, type, required, constraints, default |
+| **§4 Primary key** | Field with `pk: true` or id convention |
+| **§4 Foreign keys** | `relatesTo` / `dependsOn` edges → FK = `<target>_id` unless node specifies |
+| **§4 Indexes** | Entity `indexes` array; NFR performance constraints on this entity |
+| **§4 Constraints** | Field `validationRules` + NFR constraint nodes |
+
+**Rule:** Every table → `dataEntity` node. Every FK → edge. No tables without graph backing.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/screen-detail.md

@@ -0,0 +1,26 @@
+# Graph → Screen Detail (per screen)
+
+Queries:
+```bash
+ai-spector graph query doc.bd.screen-<slug> --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <UC-xx> --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <F-xx> --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query <api-node> --direction both --depth 2 --edges DEPS --json
+```
+
+| Template section | Graph source |
+|---|---|
+| **Purpose / User Role** | UC `name` + description; actor node name(s) |
+| **§1.1 Wireframe components** | UC `mainFlow` actor actions → form/button/list; UC `postconditions` → success state |
+| **§1.2 Layout** | Input steps → form; output steps → display/table; nav steps → breadcrumb/back |
+| **§1.3 Form fields** | API request body (F-xx `inputData`) → one input per field |
+| **§1.3 Table columns** | API response body (entity `fields`) → one column per field |
+| **§1.3 Buttons** | UC `mainFlow` action verbs → button labels |
+| **§1.4 Primary actions** | UC `mainFlow` actor steps |
+| **§1.4 Navigation** | UC `postconditions` target; `list-screens.md` §2 flow |
+| **§1.5 Field validation** | F-xx `inputData.validationRules`; entity field constraints |
+| **§1.5 Defaults** | F-xx `inputData.defaultValue`; entity field `default` |
+| **Error / empty states** | UC `exceptionFlows` → one state per exception; API 404 → empty; API 400 → inline |
+| **Role sections** | Multiple actors → mark each section with actor role |
+
+**Rule:** Every form field → API request or F-xx `inputData`. Every column → API response or entity field. Every button label → UC flow verb. No invented content.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/screen-list.md

@@ -0,0 +1,27 @@
+# Graph → Screen List
+
+Queries:
+```bash
+ai-spector graph query doc.bd.list-screen --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query doc.srs.3-use-cases --direction both --depth 2 --edges DEPS --json
+```
+
+Derive each screen — **no invented screens**:
+
+| Screen rule | Graph evidence |
+|---|---|
+| One screen per UC with actor-facing interaction steps | UC `mainFlow` with actor actions |
+| List/dashboard per browsable entity | `dataEntity` + UC with list/search flow |
+| Detail/form per creatable or editable entity | `dataEntity` + UC with create/edit flow |
+| Auth screens | Actor node + login/auth UC |
+| Role variants | Multiple actors on same UC → separate screens or role tabs |
+
+| Column | Graph source |
+|---|---|
+| **Screen ID** | S-xx sequentially |
+| **Screen Name** | UC name or entity name + action |
+| **Purpose** | UC one-line description |
+| **User Role** | Actor node(s) satisfying this UC |
+| **Related F-xx / UC-xx** | UC and F-xx nodes this screen satisfies |
+
+**§2 Navigation Flow:** UC `postconditions` → target screen after action completes.

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

@@ -8,6 +8,7 @@ Generate basic design markdown **from the traceability graph** and upstream SRS.
 |-----------------|----------|
 | Scope cases, waves, merge, finish, guardrails | [generate-workflow.md](../../ai-spector/references/generate-workflow.md) |
 | Graph query, ingest, perEndpoint/perScreen | [generate-graph.md](../../ai-spector/references/generate-graph.md) |
+| **Graph → template section mapping** | **[bd-context/](./bd-context/) — load the matching section file before writing each doc type** |
 
 **Upstream:** SRS on disk (minimum per `workflow.dependencies.json`). Do not invent APIs/screens not grounded in graph + SRS.
 
@@ -43,6 +44,20 @@ Templates: `.ai-spector/templates/basic_design/`
 
 **Reindex every wave (mandatory):** `graph merge` does not parse markdown bodies. Without index after wave 0, wave 1 cannot expand endpoint rows; without index after wave 1, wave 2 cannot expand Screen Index rows.
 
+## Graph context (required before writing each file)
+
+After running queries ([generate-graph.md](../../ai-spector/references/generate-graph.md) § C), load the matching file from `bd-context/` for the doc type being written:
+
+| Writing | Load |
+|---|---|
+| DB design | `bd-context/db-design.md` |
+| API list | `bd-context/api-list.md` |
+| API detail (per endpoint) | `bd-context/api-detail.md` |
+| Screen list | `bd-context/screen-list.md` |
+| Screen detail (per screen) | `bd-context/screen-detail.md` |
+
+Every endpoint, table, and screen must trace to graph nodes. No invented structure.
+
 ## Basic-design-specific write rules
 
 - **List chapters first** — names from `api-list.md` / `list-screens.md` tables; not one file per `F-xx`.
@@ -74,7 +89,7 @@ Execution checklist: [generate-workflow.md](../../ai-spector/references/generate
 ## Finish
 
 - Last wave already ran validate + index → final validate only; else run both again.
-- Suggest **`/summary basic-design`** (required before detail design per workflow).
+- Suggest **`/summary basic-design`** when workflow lists it.
 
 Log: `.ai-spector/.docflow/logs/generate-basic-design.log`.
 

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

@@ -5,38 +5,29 @@ description: >-
   Use when the user asks for HTML prototype, screen mockups, or prototype/src files. When no theme is
   stored, recommends 3 best-fit themes from project context, opens preview samples in the browser,
   and waits for the user to choose before setup. Uses stored preference on subsequent runs. Do not use
-  for markdown SRS/basic/detail design only, or graph operations without HTML output.
+  for markdown SRS/basic design only, or graph operations without HTML output.
 paths:
   - "prototype/**"
 ---
 
-# AI Spector — Generate prototype
+# Generate Prototype
 
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
+## Load at start
+1. [references/runbook.md](references/runbook.md)
 
-## Required reading
+## Load when needed
 
-- [references/runbook.md](references/runbook.md) — manifest, HTML rules, theme resolution
-- [references/auth-picker.md](references/auth-picker.md) — **when no basic auth stored**: ask username/password, create htpasswd
-- [references/theme-picker.md](references/theme-picker.md) — **when no theme stored**: recommend 3, preview, confirm
+| Situation | Load |
+|---|---|
+| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
+| No theme stored — **must confirm before setup** | [references/theme-picker.md](references/theme-picker.md) |
+| No basic auth stored | [references/auth-picker.md](references/auth-picker.md) |
+| Before writing each screen HTML | [references/prototype-graph-context.md](references/prototype-graph-context.md) |
+| Run of 5+ screens | [../ai-spector/references/context-management.md](../ai-spector/references/context-management.md) |
+| CLI fails | [../ai-spector/references/cli-failures.md](../ai-spector/references/cli-failures.md) |
 
-## Checklist
+## On CLI failure
+Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
 
-```
-- [ ] language confirmed (language-picker.md — check before writing any screen text content)
-- [ ] list-screens + screen detail docs exist
-- [ ] basic auth resolved (config basicAuth + prototype/htpasswd → **auth picker if none**)
-- [ ] theme resolved (request → theme.json → manifest → config → **theme picker if none**)
-- [ ] if picker: 3 recommendations + previews opened + user confirmed before setup
-- [ ] prototype setup (with --theme when needed; persists when user named a theme)
-- [ ] one .html per screen; prototypeStem from manifest
-- [ ] prototype manifest && prototype validate --strict
-```
-
-## Natural language
-
-“HTML prototype”, “mockup screens”, “prototype with stripe theme” → this skill.
-
-“Help me pick a theme”, “what theme fits my app?”, “show me theme options” → [theme-picker.md](references/theme-picker.md) (even before generating).
-
-Constraints: `prototype/CLAUDE.md` in the project repo.
+"HTML prototype", "mockup screens", "prototype with stripe theme" → this skill.
+"Help me pick a theme" → load theme-picker.md directly.

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

@@ -0,0 +1,115 @@
+# Graph context for prototype generation
+
+Run these queries **before writing each screen's HTML**. The graph holds the authoritative spec — screen detail docs often summarize it; the graph has the full picture.
+
+Skip this document only when the graph has zero nodes for the screen (brand-new project with no graph yet). In that case, note the gap and generate from screen detail doc alone.
+
+---
+
+## Step 1 — Screen node + neighborhood
+
+```bash
+ai-spector graph query doc.bd.screen-<slug> --direction both --depth 4 --edges CONTEXT --json
+```
+
+What to extract from the result:
+
+| Field / edge | Use in HTML |
+|---|---|
+| `satisfies` → F-xx nodes | Business rules, field constraints, success/error states |
+| `satisfies` → UC-xx nodes | Actor roles, preconditions, flow steps, postconditions |
+| `dependsOn` → `doc.bd.api-*` nodes | Form fields, request params, response columns |
+| `contains` → section nodes | Section headings and subsections already defined |
+| `tracesTo` → SRS nodes | NFR constraints (e.g. required, max length, format) |
+
+If `doc.bd.screen-<slug>` is not found in the graph, try `screen-<slug>` or the screenId from `list-screens.md`.
+
+---
+
+## Step 2 — Feature detail (per linked F-xx)
+
+For each F-xx found in Step 1 `satisfies` edges:
+
+```bash
+ai-spector graph query F-<n> --direction both --depth 3 --edges CONTEXT --json
+```
+
+Extract:
+- **Functional requirements** listed under the feature → must-have UI behaviours
+- **Field definitions** (`rendersTo` → docs if present)
+- **Business rules** (validation, conditional visibility, permissions)
+- **Actor** that performs / views this feature → drives role-based UI variants
+
+---
+
+## Step 3 — Use-case detail (per linked UC-xx)
+
+For each UC-xx found in Step 1 `satisfies` edges:
+
+```bash
+ai-spector graph query UC-<n> --direction both --depth 3 --edges CONTEXT --json
+```
+
+Extract:
+- **Primary actor** → who the screen is for; if multiple actors, plan role tabs or conditional sections
+- **Preconditions** → what state must be shown before the main action (e.g. "must be logged in" → redirect guard state)
+- **Main flow steps** → maps directly to the interactive sequence in the HTML (form → submit → result)
+- **Alternative / exception flows** → error states and empty states to include
+
+---
+
+## Step 4 — API endpoint detail (per linked API)
+
+For each `doc.bd.api-*` node found in Step 1 `dependsOn` edges:
+
+```bash
+ai-spector graph query doc.bd.api-<slug> --direction both --depth 2 --edges DEPS --json
+```
+
+Extract:
+- **Request body fields** → form inputs (name, type, required/optional, format hints)
+- **Response body fields** → table columns, card properties, display labels
+- **HTTP method + path** → drives the form `action` hint and confirmation copy
+- **Error codes** → error message copy and UI states (404 → empty state, 400 → inline validation, 401 → redirect)
+
+---
+
+## Step 5 — Actor / permission check
+
+If the screen serves multiple actors (e.g. Admin + End User):
+
+```bash
+ai-spector graph query <actorId> --direction both --depth 2 --edges CONTEXT --json
+```
+
+Use actor data to:
+- Render role-specific sections (admin actions gated behind a permission check visual)
+- Show the correct navigation items for each role
+- Label buttons and headings with the actor's natural language (not just "user")
+
+---
+
+## Synthesis — before writing the HTML
+
+Compile answers to these questions from the query results. Do **not** invent answers not grounded in graph data — leave a `<!-- TODO: not in spec -->` comment instead.
+
+| Question | Source |
+|---|---|
+| What fields does the form have? | API request body (Step 4) |
+| What columns / data does the list/detail show? | API response body (Step 4) |
+| What validation rules apply? | F-xx business rules (Step 2) |
+| What error states must exist? | UC exception flows (Step 3) + API error codes (Step 4) |
+| What empty state must exist? | UC preconditions + API 404 handling |
+| Which actors see what? | Actor roles (Step 3 + 5) |
+| What is the navigation target after the main action? | UC postconditions + `list-screens.md` §2 flow |
+| Any NFR constraints (length limits, formats)? | SRS `tracesTo` nodes (Step 1) |
+
+---
+
+## Accuracy rules
+
+1. **Every form field must trace to** an API request field, an F-xx field definition, or a UC data requirement. Remove any field that has no graph backing.
+2. **Every table column must trace to** an API response field or a data entity property. No invented columns.
+3. **Every button / action must trace to** a UC main flow step or F-xx functional requirement. Label it with the spec's language, not generic copy ("Save" is fine only if the spec says save; use the spec's verb if it differs).
+4. **Error and empty states are mandatory** when the UC has exception flows or the API returns error codes. A screen with only the happy-path is incomplete.
+5. **Role-based sections are mandatory** when more than one actor satisfies the screen. Use a visual separator or tab — do not silently drop one actor's view.