ai-spector 0.5.2 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spector",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Cursor-first documentation workflow: traceability graph, SRS/basic/detail design templates, and ai-spector CLI",
   "type": "module",
   "license": "MIT",

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

@@ -25,9 +25,11 @@ When `npx ai-spector` exits non-zero, required `--json` is invalid, or a require
 
 | Item | Path |
 |------|------|
+| Config (languages, paths) | `.ai-spector/docflow.config.json` |
 | Graph | `.ai-spector/graph/traceability.graph.json` |
 | Query | `npx ai-spector graph query <id> --json` |
 | Templates | `.ai-spector/templates/` |
+| Doc output | `docs/srs/{lang.code}/` · `docs/basic-design/{lang.code}/` |
 
 ## Route to a task skill
 
@@ -38,10 +40,12 @@ When `npx ai-spector` exits non-zero, required `--json` is invalid, or a require
 | Basic design | `ai-spector-generate-basic-design` |
 | Prototype | `ai-spector-generate-prototype` |
 | Comments | `ai-spector-resolve-comments` |
+| Translation status / stale languages | `ai-spector-lang-status` |
 | “Generate docs” (vague) | `ai-spector-generate` |
 
 When a task skill applies, read its `references/` runbook fully before acting.
 
 ## More
 
-[references/project-conventions.md](references/project-conventions.md)
+- [references/cli-reference.md](references/cli-reference.md) — full command reference (all options + examples)
+- [references/project-conventions.md](references/project-conventions.md)

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

@@ -0,0 +1,392 @@
+# AI Spector CLI Reference
+
+Complete command reference for AI agents. Run all commands from the project root with `npx ai-spector`.
+
+**On any failure:** pause, report exit code + stderr, do not guess. Load [cli-failures.md](./cli-failures.md).
+
+---
+
+## Quick lookup
+
+| Goal | Command |
+|---|---|
+| Initialize a new project | `npx ai-spector init` |
+| Add a language | `npx ai-spector lang add <code>` |
+| Refresh graph + indexes | `npx ai-spector index` |
+| Prepare graph structure only | `npx ai-spector index --graph-only` |
+| Rebuild doc indexes only | `npx ai-spector index --docs-only` |
+| Query a node's subgraph | `npx ai-spector graph query <id> --json` |
+| Impact analysis from a node | `npx ai-spector graph impact <id> --json` |
+| Impact from git diff | `npx ai-spector graph impact --git --json` |
+| Merge knowledge into graph | `npx ai-spector graph merge --from-knowledge` |
+| Validate graph | `npx ai-spector graph validate` |
+| Graph health report | `npx ai-spector graph report --json` |
+| Visualize graph in browser | `npx ai-spector graph visualize --open` |
+| List review comments | `npx ai-spector comments list --json` |
+| Comment triage inbox | `npx ai-spector comments inbox --json` |
+| Resolve a comment thread | `npx ai-spector comments resolve <threadId>` |
+| Refresh Cursor skills | `npx ai-spector sync-cursor` |
+
+---
+
+## `init`
+
+Scaffold a new project: creates `.ai-spector/`, `docs/srs/{lang}/`, `docs/basic-design/{lang}/`, Cursor skills.
+
+```bash
+npx ai-spector init [options]
+
+Options:
+  -l, --languages <codes>   Comma-separated language codes (default: "en")
+                            e.g. --languages en,jp,vi
+  -f, --force               Overwrite existing scaffold files
+  -C, --cwd <path>          Target directory (default: current dir)
+```
+
+**Examples:**
+```bash
+npx ai-spector init                        # English only
+npx ai-spector init --languages en,jp,vi   # three languages
+npx ai-spector init --force                # re-scaffold in place
+```
+
+**What it writes:**
+- `.ai-spector/docflow.config.json` — project config including `languages[]`
+- `docs/srs/{lang}/` and `docs/basic-design/{lang}/` for each language
+- `.cursor/skills/` — Cursor agent skills
+- `.ai-spector/templates/` — SRS + basic design templates
+
+---
+
+## `lang add`
+
+Add a language to an already-initialized project at any time.
+
+```bash
+npx ai-spector lang add <code> [options]
+
+Arguments:
+  code              BCP-47 language code: en, jp, ja, vi, zh, ko, fr, de, es, pt
+
+Options:
+  --label <label>   Override display name (inferred from built-in map if omitted)
+  -C, --cwd <path>  Project root (default: current dir)
+```
+
+**Examples:**
+```bash
+npx ai-spector lang add jp
+npx ai-spector lang add vi --label Vietnamese
+```
+
+**What it does:**
+1. Creates `docs/srs/{code}/` and `docs/basic-design/{code}/`
+2. Appends `{ code, label }` to `languages[]` in `docflow.config.json`
+3. Registers `translationOf` edges in the graph for all existing primary document nodes
+4. Prints: "Run `npx ai-spector index` to refresh the full graph."
+
+After running, always follow with `npx ai-spector index`.
+
+---
+
+## `index`
+
+Full refresh: section registry → graph bootstrap → knowledge merge → doc-semantic merge → provenance → bundles → validate → doc indexes.
+
+```bash
+npx ai-spector index [options]
+
+Options:
+  --graph-only          Registry + bootstrap + merge + validate only (no doc indexes)
+  --docs-only           Rebuild .ai-spector/index/*.md only (no graph changes)
+  --skip-docs           Skip doc indexes (graph steps still run)
+  --skip-merge          Skip merging knowledge.json
+  --skip-doc-semantics  Skip parsing docs body for UC/F/actor ids
+  --skip-validate       Skip graph validate
+```
+
+**Typical agent usage:**
+```bash
+npx ai-spector index                  # after any doc write
+npx ai-spector index --graph-only     # when only graph state matters
+npx ai-spector index --skip-merge     # when knowledge.json is stale/missing
+```
+
+**Output:** prints a step-by-step summary table. Each step shows `✓ ok`, `○ skipped`, or `✗ failed`.
+
+**Multi-language behaviour:** automatically creates `doc:{lang.code}:{docId}` nodes and `translationOf` edges for each secondary language configured in `docflow.config.json`.
+
+---
+
+## `graph query`
+
+Return the subgraph and projection paths for a node. Always run before writing a document section.
+
+```bash
+npx ai-spector graph query <nodeId> [options]
+
+Arguments:
+  nodeId            Node id from the traceability graph
+
+Options:
+  -d, --direction <dir>   out | in | both (default: "both")
+  --depth <n>             Traversal depth (default: 2)
+  -e, --edges <types>     Comma-separated edge types
+  --json                  JSON output (required for agent use)
+```
+
+**Examples:**
+```bash
+npx ai-spector graph query UC-01 --json
+npx ai-spector graph query doc.srs.use-cases --direction out --depth 3 --json
+npx ai-spector graph query srs-overview --edges contains,partOf --json
+```
+
+**JSON output shape:**
+```jsonc
+{
+  "origin": { "id": "...", "type": "..." },
+  "nodes": [...],
+  "edges": [...],
+  "projectionPaths": ["docs/srs/en/03-use-cases.md", ...]
+}
+```
+
+Use `projectionPaths` to know which files to read. Do not glob `docs/**`.
+
+---
+
+## `graph impact`
+
+Compute which nodes/documents need regeneration or review after a change. Also surfaces stale translation nodes.
+
+```bash
+npx ai-spector graph impact [id] [options]
+
+Arguments:
+  id                Node id (optional when using --file, --heading, or --git)
+
+Options:
+  --file <path>       Resolve origin from repo-relative doc path
+  --heading <text>    Resolve section by heading (combine with --file)
+  --git               Seeds from current git diff (staged + unstaged)
+  --change <type>     Change type label (default: "content_change")
+  -o, --output <path> Write impact JSON to file
+  --json              Print JSON
+```
+
+**Examples:**
+```bash
+npx ai-spector graph impact UC-01 --json
+npx ai-spector graph impact --file docs/srs/en/03-use-cases.md --json
+npx ai-spector graph impact --file docs/srs/en/03-use-cases.md --heading "3.2 List Use Case" --json
+npx ai-spector graph impact --git --json
+```
+
+**JSON output shape:**
+```jsonc
+{
+  "origin": { "id": "...", "type": "...", "change": "content_change" },
+  "affected": {
+    "regenerate": [{ "id": "...", "type": "document", "projectionPath": "..." }],
+    "review":     [{ "id": "...", "type": "section",  "projectionPath": "..." }]
+  },
+  "staleTranslations": [        // present when secondary-language nodes are affected
+    { "id": "doc:jp:srs-use-cases", "type": "document", "reason": "translationOf srs-use-cases" }
+  ]
+}
+```
+
+`staleTranslations` lists secondary-language document nodes whose primary counterpart changed — they need re-translation, not re-generation from graph.
+
+---
+
+## `graph merge`
+
+Merge a domain patch or `knowledge.json` into the traceability graph (upsert nodes + edges).
+
+```bash
+npx ai-spector graph merge [file] [options]
+
+Options:
+  --from-knowledge      Read .ai-spector/.docflow/analysis/knowledge.json
+  --semantic            Merge semantic-links patch (agent meaning edges)
+  -g, --graph <path>    Graph path override
+  -o, --write-patch <p> Write normalized patch before merge
+  --no-validate         Skip validate after merge
+  --dry-run             Stats only, no save
+```
+
+**Examples:**
+```bash
+npx ai-spector graph merge --from-knowledge           # after /analyze
+npx ai-spector graph merge patch.json                 # manual patch file
+npx ai-spector graph merge --from-knowledge --dry-run # preview
+```
+
+Do not hand-edit `traceability.graph.json` for domain nodes — always merge via this command.
+
+---
+
+## `graph validate`
+
+Validate graph against JSON schema and traceability rules.
+
+```bash
+npx ai-spector graph validate [options]
+
+Options:
+  -g, --graph <path>    Graph path override
+  -s, --schema <path>   Schema path override
+  --registry <path>     Registry path
+  --rules <path>        Rules manifest path
+```
+
+Run after every merge or doc write. Exit code 0 = valid (warnings may still print).
+
+---
+
+## `graph report`
+
+Layer health report: structure, spec instances, hubs, provenance, semantic links.
+
+```bash
+npx ai-spector graph report [options]
+
+Options:
+  -g, --graph <path>  Graph path override
+  --json              JSON output
+```
+
+Useful for diagnosing missing provenance or empty domain layers.
+
+---
+
+## `graph visualize`
+
+Generate an HTML report to explore the graph in a browser.
+
+```bash
+npx ai-spector graph visualize [options]
+
+Options:
+  --open   Open in default browser after generating
+```
+
+---
+
+## `comments`
+
+Git-backed review comment threads. Comments live under `comments/{logical_path}/`.
+
+### `comments inbox`
+
+Triage list of open threads, formatted for Cursor chat.
+
+```bash
+npx ai-spector comments inbox --json
+```
+
+Output: JSON with `idePresentation.markdown` table, each row has thread id, anchor, status.
+
+### `comments list`
+
+Raw list of threads with optional filters.
+
+```bash
+npx ai-spector comments list [options]
+
+Options:
+  --file <path>   Filter by logical file path (e.g. srs/01-overview)
+  --json          JSON output
+```
+
+### `comments plan`
+
+Resolve plan for a thread: anchor excerpt, graph impact, IDE workflow hints.
+
+```bash
+npx ai-spector comments plan [threadId] [options]
+
+Options:
+  --json   JSON output
+```
+
+### `comments show`
+
+Thread detail: metadata, replies, events.
+
+```bash
+npx ai-spector comments show <threadId>
+```
+
+### `comments resolve`
+
+Mark a thread resolved.
+
+```bash
+npx ai-spector comments resolve <threadId>
+```
+
+---
+
+## `sync-cursor`
+
+Refresh `.cursor/skills/` from the bundled scaffold without re-initializing the whole project.
+
+```bash
+npx ai-spector sync-cursor [-C <path>]
+```
+
+Use when a new version of `ai-spector` ships updated skills.
+
+---
+
+## Output paths (multi-language)
+
+All document output paths follow:
+
+```
+docs/srs/{lang.code}/{filename}
+docs/basic-design/{lang.code}/{filename}
+docs/basic-design/{lang.code}/api/{slug}.md
+docs/basic-design/{lang.code}/screens/{slug}.md
+```
+
+Primary language is the **first** entry in `languages[]` inside `docflow.config.json`. Secondary languages are translated from the finished primary file — never generated independently from the graph.
+
+---
+
+## Common sequences
+
+**After analyzing data source:**
+```bash
+npx ai-spector graph merge --from-knowledge
+npx ai-spector graph validate
+npx ai-spector index --skip-merge
+```
+
+**After writing any doc file:**
+```bash
+npx ai-spector graph validate
+npx ai-spector index
+```
+
+**After adding a language:**
+```bash
+npx ai-spector lang add jp
+npx ai-spector index
+```
+
+**Before writing a section (query context):**
+```bash
+npx ai-spector graph query <seedNodeId> --json
+# → read projectionPaths, write section, then:
+npx ai-spector graph merge patch.json
+```
+
+**Check translation staleness:**
+```bash
+npx ai-spector graph impact --git --json
+# → inspect staleTranslations[] in output
+```

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

@@ -71,18 +71,43 @@ Case 3: build scope table (DAG id, output path, seed, reason, deps) → ask →
 - [ ] Load matching srs-context/ or bd-context/ section for this doc type
 - [ ] Read template from .ai-spector/templates/ — never invent structure
 - [ ] Write primary language file from summary + template
-- [ ] If secondary languages configured:
-        For each secondary language (can parallelize across languages):
-          Read the finished primary file from disk
-          Translate prose to target language (IDs/paths/code unchanged)
-          Write to docs/{docType}/{lang.code}/{filename}
+- [ ] [PAUSE — translation prompt] (see below)
 - [ ] Merge projection patch (rendersTo + dependsOn) for the wave
 - [ ] npx ai-spector graph validate
 - [ ] npx ai-spector index (basic design: every wave; SRS: see runbook)
 - [ ] /compact with plan summary before next wave
 ```
 
-Per target: Delegate → Receive summary → Write primary → Translate to secondaries → Log path/status → Ingest.
+Per target: Delegate → Receive summary → Write primary → Translation prompt → Translate if approved → Log path/status → Ingest.
+
+## Translation prompt (mandatory pause after each primary file write)
+
+After writing or updating **any primary language file**, and when secondary languages are configured in `docflow.config.json`, you **must** stop and ask:
+
+```
+I've updated `docs/{docType}/{primaryLang.code}/{filename}`.
+
+This project also has translations configured: {secondaryLangs joined by ", "}.
+Do you want me to update the translation(s) now?
+
+  1. Yes, update all translations now
+  2. Yes, but only: [user can name specific languages]
+  3. No, I'll handle translations separately
+```
+
+**Wait for the user's reply before proceeding.**
+
+- **Reply 1 or 2** → for each approved secondary language: read the finished primary file, translate prose, write to `docs/{docType}/{lang.code}/{filename}`. Then continue the checklist.
+- **Reply 3** → note which files have stale translations (so the user can run `ai-spector-lang-status` later), then continue the checklist without translating.
+
+### When to skip the prompt
+
+Skip the prompt (proceed directly to translation) only when the user has **already pre-approved** translations in this session with a phrase like:
+- "generate everything in all languages"
+- "update all translations automatically"
+- "yes to all translations"
+
+If pre-approved, translate immediately after each primary write without asking again for the rest of the session.
 
 ## Guardrails
 

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

@@ -1,6 +1,7 @@
 # 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).
+**Users do not run these.** Slash commands invoke CLI. **On failure:** [cli-failures.md](./cli-failures.md).
+**Full command reference (all commands + options + examples):** [cli-reference.md](./cli-reference.md).
 
 Run from project root: always `npx ai-spector …` (see [project-conventions.md](./project-conventions.md)).
 
@@ -10,7 +11,7 @@ Run from project root: always `npx ai-spector …` (see [project-conventions.md]
 2. If non-zero or `--json` is unparseable → **pause**; report and offer fix / workaround / pause per `cli-failures.md`.
 3. On success, use CLI output only — do not re-derive graph state in the agent.
 
-## Commands
+## Commands (quick)
 
 ```bash
 npx ai-spector analyze
@@ -21,6 +22,8 @@ npx ai-spector graph query <nodeId> --json
 npx ai-spector graph impact <nodeId> --json
 npx ai-spector graph impact --file <path> [--heading <text>] --json
 npx ai-spector graph impact --git --json
+npx ai-spector index
+npx ai-spector lang add <code>     # add a language (e.g. jp, vi)
 ```
 
 ## `graph query`
@@ -28,40 +31,31 @@ npx ai-spector graph impact --git --json
 ```bash
 npx ai-spector graph query <seedId> --direction both --depth 4 --json
 npx ai-spector graph query <depDocId> --edges rendersTo,dependsOn,listedIn,satisfies --depth 2 --json
-npx ai-spector graph impact <seedId> --change content_change --json
 ```
 
-**Generate:** query **before** write; **`graph merge`** projection patch **after** each file (`rendersTo` + `dependsOn`). See `generate-graph.md`.
+**Generate:** query **before** write; **`graph merge`** projection patch **after** each file (`rendersTo` + `dependsOn`). See [generate-graph.md](./generate-graph.md).
 
-Use `projectionPaths`, `nodes`, `edges` from JSON. **If command fails or JSON invalid:** stop — do not glob `docs/srs/**`.
+Use `projectionPaths`, `nodes`, `edges` from JSON. **If command fails or JSON invalid:** stop — do not glob `docs/**`.
 
-**If success but empty domain nodes:** report to user; suggest `/analyze` — still no folder-wide SRS reads.
+**If success but empty domain nodes:** report to user; suggest `/analyze` — still no folder-wide reads.
 
 ## `graph impact`
 
-Resolve the seed in the agent (see `/impact`), then:
-
 ```bash
 npx ai-spector graph impact <nodeId> --change content_change --json
+npx ai-spector graph impact --file docs/srs/en/03-use-cases.md --heading "3.2 List Use Case" --json
+npx ai-spector graph impact --git --change content_change --json
 ```
 
-Optional resolver flags (verify path/heading → id):
-
-```bash
-npx ai-spector graph impact --file docs/srs/3-use-cases.md --heading "3.2 List Use Case" --json
-```
-
-Current working tree (staged + unstaged vs `HEAD`, or unstaged + `--cached` before first commit):
+Note: doc file paths now always include a language subfolder: `docs/srs/{lang.code}/{filename}`.
 
-```bash
-npx ai-spector graph impact --git --change content_change --json
-```
+The JSON output includes a `staleTranslations` array when secondary-language documents are affected. Those nodes need **re-translation from the primary file**, not re-generation from the graph.
 
-If this fails, do not guess impact scope — show CLI output and fix.
+If impact fails, do not guess 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.
+Called from `/analyze`. On merge/validate failure, do not patch `traceability.graph.json` by hand — fix `knowledge.json` or section ids and re-run merge.
 
 ## Narrow fallback (success only)
 

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

@@ -48,7 +48,7 @@ docs/basic-design/jp/api/post-checkout.md
 
 Never write directly to `docs/basic-design/{filename}` — the language subfolder is always required.
 
-**Multi-language order:** generate the primary language file first (from graph + template). Then translate that file to each secondary language. Secondary languages are never generated independently from the graph — they are always translated from the finished primary file.
+**Multi-language order:** generate the primary language file first (from graph + template). After writing it, follow the **translation prompt** from [generate-workflow.md](../../ai-spector/references/generate-workflow.md#translation-prompt-mandatory-pause-after-each-primary-file-write) — ask the user whether to update translations before continuing. Secondary languages are always translated from the finished primary file, never generated independently from the graph.
 
 ## Waves (reference)
 

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

@@ -48,7 +48,7 @@ docs/srs/vi/01-introduction.md   ← Vietnamese
 
 Never write directly to `docs/srs/{filename}` — the language subfolder is always required.
 
-**Multi-language order:** generate the primary language file first (from graph + template). Then translate that file to each secondary language. Secondary languages are never generated independently from the graph — they are always translated from the finished primary file.
+**Multi-language order:** generate the primary language file first (from graph + template). After writing it, follow the **translation prompt** from [generate-workflow.md](../../ai-spector/references/generate-workflow.md#translation-prompt-mandatory-pause-after-each-primary-file-write) — ask the user whether to update translations before continuing. Secondary languages are always translated from the finished primary file, never generated independently from the graph.
 
 ## Waves (reference)
 

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

@@ -42,6 +42,7 @@ Read **one** runbook under `references/` for the user’s intent, then execute i
 
 ## Shared references
 
+- [../ai-spector/references/cli-reference.md](../ai-spector/references/cli-reference.md) — full CLI options + examples
 - [../ai-spector/references/graph.md](../ai-spector/references/graph.md)
 - [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md)
 - [references/graph-commands.md](references/graph-commands.md)

package/scaffold/cursor/skills/ai-spector-lang-status/SKILL.md

@@ -45,6 +45,21 @@ After the table, list actionable items:
 - Files that are MISSING: "Generate: `docs/srs/jp/02-actors.md`"
 - Files that are STALE: "Update: `docs/basic-design/vi/db-design.md` (primary changed 2026-06-01, translation last updated 2026-05-10)"
 
+## After any primary file edit (outside of generate skills)
+
+If the user edits a primary language file directly (not via a generate skill), and secondary languages are configured, ask:
+
+```
+You've edited `docs/{docType}/{primaryLang.code}/{filename}`.
+Do you want me to update the translation(s) now?
+
+  1. Yes, update all translations now
+  2. Yes, but only: [specific languages]
+  3. No — I'll handle it later
+```
+
+Wait for reply. On yes: read the updated primary file and re-translate to each approved secondary language. On no: note the file as stale so the user can run `ai-spector-lang-status` later.
+
 ## Updating stale translations
 
 If the user says "update stale JP" or "regenerate missing VI docs":