ai-spector 0.8.6 → 0.8.15

package/README.md

@@ -1,57 +1,139 @@
 # AI Spector
 
-Documentation workflow in **Cursor**: traceability graph, SRS / basic / detail design. **Describe what you need in chat** — skills route the agent, which runs `ai-spector` CLI. You usually do not run CLI yourself.
+Documentation workflow in **Cursor** or **Claude Code**: traceability graph, SRS / basic / detail design. **Describe what you need in chat** — skills route the agent, which runs `ai-spector` CLI or MCP tools. You usually do not run CLI yourself.
 
-**Needs:** Node 20+, [Cursor](https://cursor.com), [uv](https://docs.astral.sh/uv/) (Graphify MCP after `init`).
+**Needs:** Node 20+, Git, [Cursor](https://cursor.com) and/or [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(optional — CocoIndex semantic search)*.
+
+Full setup reference: [docs/setup-guide.md](docs/setup-guide.md)
+
+**Tiếng Việt:** [README.vi.md](README.vi.md)
+
+---
 
 ## Setup (once)
 
-**In Cursor:** ask **"setup ai-spector project"** (agent runs the setup skill).
+### Prerequisites
+
+| Requirement | Check |
+|-------------|-------|
+| Node.js ≥ 20 | `node --version` |
+| Git repository | `git status` |
+| Cursor and/or Claude Code | IDE open in project root |
+| Python ≥ 3.11 *(optional)* | only for CocoIndex semantic search |
+
+---
 
-**CLI:**
+### Step 1 — Scaffold *(only CLI step)*
+
+Run once at your project root. On the **first** run, pass `--registry` so `npx` can download the package from the internal Verdaccio registry (`http://10.101.0.239:4873`). No `npm login` required.
 
 ```bash
-npm install -D ai-spector
-npx ai-spector setup              # guided wizard
-npx ai-spector setup -y -l en,jp  # non-interactive
-npx ai-spector setup --check      # audit checklist
+npx ai-spector@latest init --registry http://10.101.0.239:4873
 ```
 
-1. Open the project in Cursor → reload **MCP** → enable **all** skills under `.cursor/skills/`.
-2. Put source material in `docs/data-source/`.
+The wizard prompts for editor (Cursor, Claude Code, or both), languages, git hook, and optional CocoIndex.
 
-Re-init scaffold: `npx ai-spector init --force` or `npx ai-spector setup -y --force`. After upgrading: `npx ai-spector sync-cursor`.
+This creates:
 
-## Workflow
+- `.ai-spector/` — config, graph, templates
+- `docs/data-source/`, `docs/srs/`, `docs/basic-design/`
+- **Cursor:** `.cursor/` — skills, rules, `mcp.json`
+- **Claude Code:** `CLAUDE.md` + `.claude/skills/` + `.mcp.json`
+- Pre-commit hook (when git is available)
 
-See `.cursor/WORKFLOW.md` after `init`. Enable all skills under `.cursor/skills/`.
+---
 
-### First run (natural language)
+### Step 2 — Finish setup in chat
+
+Open the project in **Cursor** or **Claude Code** and say:
 
 ```text
-“analyze the data source”
-“validate the graph”
-“generate the SRS”
-“refresh the index”
+setup ai-spector project
 ```
 
-Then: “generate basic design” → “generate detail design” as needed.
+The agent installs the npm dependency (if needed), verifies the checklist, offers CocoIndex, and reminds you what is left to do manually.
 
-HTML prototype:
+---
 
-```bash
-npx ai-spector prototype themes
+### Step 3 — Enable the agent *(manual, one-time)*
+
+**Cursor**
+
+1. **Settings → Rules → Agent Skills** — enable **all** folders under `.cursor/skills/` (see `.cursor/skills/README.md`)
+2. **Reload MCP** — `.cursor/mcp.json` registers the `ai-spector` MCP server
+
+**Claude Code**
+
+1. Skills load automatically from `.claude/skills/` (see `CLAUDE.md`)
+2. **Reload MCP** — `.mcp.json` registers the `ai-spector` MCP server
+
+---
+
+### Step 4 — Add source material
+
+Drop requirements docs, meeting notes, user stories, or any input into `docs/data-source/`. Supported formats: `.md`, `.txt`, `.pdf`.
+
+---
+
+### Step 5 — Start the pipeline
+
+In chat:
+
+```text
+analyze my data source
 ```
 
-Ask in chat: **“generate HTML prototype”** — if no theme is saved, the agent recommends 3 themes, opens previews in your browser, and waits for you to pick. Or name one upfront: “prototype with stripe theme”.
+Then continue in chat as needed — see [Workflow](#workflow) below.
 
-```bash
-npx ai-spector prototype auth --username demo --password '<secret>'  # once per project
-npx ai-spector prototype preview stripe --open   # optional: preview yourself
-npx ai-spector prototype setup --theme vercel    # after you choose
+---
+
+### Optional — CocoIndex semantic search
+
+Enables `docs_search` and `graph_query_fuzzy` MCP tools. Requires Python ≥ 3.11.
+
+In chat:
+
+```text
+enable CocoIndex for this project
 ```
 
-Then ask: “generate HTML prototype for all screens” → `npx ai-spector prototype manifest` → `prototype validate --strict`.
+See [docs/setup-guide.md](docs/setup-guide.md) for Postgres / OpenAI embedding options.
+
+---
+
+### Add another editor later
+
+In chat:
+
+```text
+add Claude Code support to ai-spector
+sync ai-spector cursor skills
+```
+
+After upgrading ai-spector, say **"sync ai-spector cursor skills"** in chat.
+
+---
+
+## Workflow
+
+See `.cursor/WORKFLOW.md` (Cursor) or `CLAUDE.md` (Claude Code) after `init`.
+
+### First run
+
+Say in chat:
+
+```text
+“analyze the data source”
+“validate the graph”
+“generate the SRS”
+“refresh the index”
+```
+
+Then: **“generate basic design”** → **“generate detail design”** as needed.
+
+**HTML prototype** — say **“generate HTML prototype”**. If no theme is saved, the agent recommends 3 themes, opens previews in your browser, and waits for you to pick. Or name one upfront: **“prototype with stripe theme”**.
+
+Then: **“generate HTML prototype for all screens”**.
 
 ### Day to day
 
@@ -75,21 +157,46 @@ docs/data-source/  →  analyze  →  validate graph  →  generate SRS  →  in
                               →  prototype setup  →  generate HTML screens
 ```
 
+---
+
 ## CLI (optional)
 
-For scripts or debugging: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. See `npx ai-spector --help`.
+For scripts or debugging only: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. See `npx ai-spector --help`.
+
+---
 
 ## If something breaks
 
 | Issue | Fix |
 |-------|-----|
-| Graphify / MCP | Install `uv`, reload MCP — `.cursor/commands/_cli-failures.md` |
-| Validate errors after edits | `/index` |
-| Old slash commands | `npx ai-spector sync-cursor` |
+| MCP tools unavailable | Reload MCP; confirm `.cursor/mcp.json` or `.mcp.json` has `ai-spector` server |
+| Setup incomplete | In chat: **“check ai-spector setup”** |
+| Skills not routing (Cursor) | Re-enable all folders under `.cursor/skills/` in Settings → Rules |
+| Validate errors after edits | In chat: **“re-index the graph”** |
+| Pre-commit hook missing | In chat: **“install ai-spector git hook”** |
+| Agent stuck on CLI error | `.cursor/skills/ai-spector/references/cli-failures.md` |
+
+---
+
+## Node SDK
+
+For **scripts, CI, or custom backends** that call the same operations as the CLI and MCP server:
+
+- **[SDK guide](docs/sdk.md)** — install, entry points, examples, API reference
+
+```bash
+npm install ai-spector
+```
+
+```ts
+import { runIndex, runGraphImpact, validateGraph } from "ai-spector";
+```
+
+---
 
 ## Web / graph SDK
 
-For **browser or custom dashboards** (not the Cursor CLI), use the read-only npm package **`ai-spector-graph`**. Your backend serves repo JSON; the frontend loads it into `ProjectSession`.
+For **browser or custom dashboards** (not the Cursor/Claude CLI), use the read-only npm package **`ai-spector-graph`**. Your backend serves repo JSON; the frontend loads it into `ProjectSession`.
 
 - **[Integration guide](docs/ai-spector-graph-integration-guide.md)** — architecture, API examples, React, recipes
 - **[API reference](docs/ai-spector-graph.md)** — types and exports
@@ -98,6 +205,8 @@ For **browser or custom dashboards** (not the Cursor CLI), use the read-only npm
 npm install ai-spector-graph
 ```
 
+---
+
 ## Develop
 
 ```bash

package/README.vi.md

@@ -0,0 +1,216 @@
+# AI Spector
+
+Công cụ làm tài liệu phần mềm trên **Cursor** hoặc **Claude Code**: sơ đồ liên kết, SRS, basic design, detail design. **Bạn chỉ cần nói trong chat** — agent sẽ tự chạy lệnh `ai-spector` hoặc MCP. Thường bạn không cần gõ lệnh terminal.
+
+**Cần có:** Node 20+, Git, [Cursor](https://cursor.com) và/hoặc [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(không bắt buộc — dùng cho tìm kiếm thông minh với CocoIndex)*.
+
+Hướng dẫn chi tiết: [docs/setup-guide.md](docs/setup-guide.md)
+
+**English:** [README.md](README.md)
+
+---
+
+## Cài đặt (làm một lần)
+
+### Cần chuẩn bị gì
+
+| Cần có | Cách kiểm tra |
+|--------|---------------|
+| Node.js ≥ 20 | `node --version` |
+| Git | `git status` |
+| Cursor và/hoặc Claude Code | Mở IDE ở thư mục gốc project |
+| Python ≥ 3.11 *(không bắt buộc)* | chỉ cần nếu bật CocoIndex |
+
+---
+
+### Bước 1 — Khởi tạo project *(bước duy nhất cần gõ lệnh)*
+
+Chạy một lần ở thư mục gốc project. **Lần đầu** cần thêm `--registry` để `npx` tải gói từ registry nội bộ (`http://10.101.0.239:4873`). **Không cần** `npm login`.
+
+```bash
+npx ai-spector@latest init --registry http://10.101.0.239:4873
+```
+
+Lệnh sẽ hỏi: dùng Cursor, Claude Code hay cả hai; ngôn ngữ tài liệu; git hook; và có bật CocoIndex không.
+
+Sau khi chạy xong sẽ có:
+
+- `.ai-spector/` — cấu hình, sơ đồ, mẫu tài liệu
+- `docs/data-source/`, `docs/srs/`, `docs/basic-design/`
+- **Cursor:** `.cursor/` — skills, rules, `mcp.json`
+- **Claude Code:** `CLAUDE.md` + `.claude/skills/` + `.mcp.json`
+- Hook git trước khi commit *(nếu project có git)*
+
+---
+
+### Bước 2 — Hoàn tất setup trong chat
+
+Mở project bằng **Cursor** hoặc **Claude Code**, rồi gõ:
+
+```text
+setup ai-spector project
+```
+
+Agent sẽ cài gói npm (nếu thiếu), kiểm tra xem còn thiếu gì, hỏi bạn có muốn bật CocoIndex không, và nhắc các bước còn lại.
+
+---
+
+### Bước 3 — Bật skills *(làm tay một lần)*
+
+**Cursor**
+
+1. Vào **Settings → Rules → Agent Skills** — bật **hết** các thư mục trong `.cursor/skills/` (xem `.cursor/skills/README.md`)
+2. **Reload MCP** — file `.cursor/mcp.json` đã cấu hình sẵn server `ai-spector`
+
+**Claude Code**
+
+1. Skills tự load từ `.claude/skills/` (xem `CLAUDE.md`)
+2. **Reload MCP** — file `.mcp.json` đã cấu hình sẵn server `ai-spector`
+
+---
+
+### Bước 4 — Thêm tài liệu đầu vào
+
+Copy file yêu cầu, biên bản họp, user story… vào `docs/data-source/`. Hỗ trợ: `.md`, `.txt`, `.pdf`.
+
+---
+
+### Bước 5 — Bắt đầu làm việc
+
+Trong chat, gõ:
+
+```text
+analyze my data source
+```
+
+Các bước tiếp theo cũng nói trong chat — xem [Quy trình làm việc](#quy-trình-làm-việc) bên dưới.
+
+---
+
+### Tùy chọn — Bật CocoIndex (tìm kiếm thông minh)
+
+Giúp agent tìm tài liệu và sơ đồ theo nghĩa, không chỉ theo từ khóa. Cần Python ≥ 3.11.
+
+Trong chat:
+
+```text
+enable CocoIndex for this project
+```
+
+Xem thêm [docs/setup-guide.md](docs/setup-guide.md) nếu muốn dùng Postgres hoặc OpenAI embedding.
+
+---
+
+### Thêm editor khác sau này
+
+Trong chat:
+
+```text
+add Claude Code support to ai-spector
+sync ai-spector cursor skills
+```
+
+Sau khi nâng cấp ai-spector, gõ **"sync ai-spector cursor skills"** trong chat.
+
+---
+
+## Quy trình làm việc
+
+Sau khi `init`, xem thêm `.cursor/WORKFLOW.md` (Cursor) hoặc `CLAUDE.md` (Claude Code).
+
+### Lần đầu chạy
+
+Gõ trong chat:
+
+```text
+“analyze the data source”
+“validate the graph”
+“generate the SRS”
+“refresh the index”
+```
+
+Tiếp theo: **“generate basic design”** → **“generate detail design”** khi cần.
+
+**Làm prototype HTML** — gõ **“generate HTML prototype”**. Nếu chưa chọn theme, agent gợi ý 3 theme, mở xem trên trình duyệt, rồi chờ bạn chọn. Hoặc nói luôn: **“prototype with stripe theme”**.
+
+Sau đó: **“generate HTML prototype for all screens”**.
+
+### Dùng hàng ngày
+
+| Khi nào | Gõ trong chat (ví dụ) |
+|---------|------------------------|
+| Có tài liệu nguồn mới hoặc sửa | “analyze data source” |
+| Kiểm tra sơ đồ | “validate the graph” |
+| Tạo lại tài liệu | “generate SRS”, “generate basic design”, … |
+| Làm prototype HTML | “generate prototype with stripe theme” |
+| Chọn theme | “help me pick a prototype theme”, “show me theme options” |
+| Vừa sửa tài liệu xong | “re-index the graph” |
+| Xem phần nào bị ảnh hưởng | “what’s the impact of my changes” |
+| Xử lý comment | “resolve comments” |
+| Xem sơ đồ trực quan | “visualize the graph” |
+
+### Quy trình thường gặp
+
+```text
+docs/data-source/  →  analyze  →  validate graph  →  generate SRS  →  index
+                              →  generate basic design  →  generate detail design
+                              →  prototype setup  →  generate HTML screens
+```
+
+---
+
+## CLI (nếu cần)
+
+Chỉ dùng khi viết script hoặc debug: `npx ai-spector index`, `graph validate`, `graph visualize --open`, `graph impact --git`, `prototype auth|themes|preview|setup|manifest|validate`. Gõ `npx ai-spector --help` để xem đầy đủ.
+
+---
+
+## Gặp lỗi thì làm gì
+
+| Lỗi | Cách xử lý |
+|-----|------------|
+| MCP không chạy | Reload MCP; kiểm tra `.cursor/mcp.json` hoặc `.mcp.json` có server `ai-spector` |
+| Setup chưa xong | Trong chat: **“check ai-spector setup”** |
+| Agent không hiểu lệnh (Cursor) | Bật lại hết thư mục trong `.cursor/skills/` ở Settings → Rules |
+| Validate báo lỗi sau khi sửa | Trong chat: **“re-index the graph”** |
+| Thiếu hook git | Trong chat: **“install ai-spector git hook”** |
+| Agent bị kẹt vì lỗi CLI | Xem `.cursor/skills/ai-spector/references/cli-failures.md` |
+
+---
+
+## Node SDK
+
+Dùng khi bạn viết **script, CI, hoặc backend tùy chỉnh** — cùng các thao tác typed như CLI và MCP:
+
+- **[Hướng dẫn SDK](docs/sdk.md)** — cài đặt, entry points, ví dụ, tham chiếu API
+
+```bash
+npm install ai-spector
+```
+
+```ts
+import { runIndex, runGraphImpact, validateGraph } from "ai-spector";
+```
+
+---
+
+## Web / graph SDK
+
+Dùng khi bạn muốn **hiển thị sơ đồ trên web hoặc dashboard riêng** (không qua Cursor/Claude). Cài gói **`ai-spector-graph`**, backend trả JSON từ repo, frontend load vào `ProjectSession`.
+
+- **[Hướng dẫn tích hợp](docs/ai-spector-graph-integration-guide.md)** — kiến trúc, ví dụ API, React
+- **[Tham chiếu API](docs/ai-spector-graph.md)** — types và exports
+
+```bash
+npm install ai-spector-graph
+```
+
+---
+
+## Phát triển (cho người đóng góp code)
+
+```bash
+npm install && npm run build && npm test
+```
+
+MIT — [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spector",
-  "version": "0.8.6",
+  "version": "0.8.15",
   "description": "Cursor-first documentation workflow: traceability graph, SRS/basic/detail design templates, and ai-spector CLI",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,7 @@
     "scaffold",
     "assets",
     "README.md",
+    "README.vi.md",
     "LICENSE"
   ],
   "exports": {
@@ -63,7 +64,9 @@
     "graph:visualize": "node dist/cli.js -r example graph visualize --open",
     "ai-spector": "node dist/cli.js",
     "themes:install-previews": "node dist/cli.js prototype install-previews",
-    "themes:preview": "node dist/cli.js prototype preview"
+    "themes:preview": "node dist/cli.js prototype preview",
+    "deploy": "bash scripts/deploy.sh",
+    "deploy:npm": "bash scripts/deploy.sh --npm"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/scaffold/claude/.claude/skills/ai-spector-graph/skill.md

@@ -13,86 +13,88 @@ description: "Runs AI Spector traceability graph operations: analyze data-source
 - "what's the impact of my changes", "what should I regenerate"
 - "visualize the graph"
 
-## Workflow
+## Invocation rule
 
-```
-1. Identify intent → pick runbook below
-2. Run CLI from project root (npx ai-spector)
-3. On failure: show output, offer fix/workaround/pause
-4. If the tool or workflow caused friction (even if recovered): offer to write a feedback report to docs/feedback/
-```
+Use **MCP tools** when `ai-spector` server is configured. CLI is fallback only.
 
 ## Runbooks by intent
 
 ### Analyze (ingest data-source)
 
-```bash
-npx ai-spector analyze
+```
+analyze({})                              # MCP — prepare graph scaffold
+# agent extracts entities → writes knowledge.json
+knowledge_validate({})                   # MCP — validate before merge
+knowledge_status({})                     # MCP — confirm entity counts
+graph_merge({ fromKnowledge: true })     # MCP — commit to graph
+graph_validate({})                       # MCP — verify result
 ```
 
-Reads `docs/data-source/`, builds knowledge graph, writes `.ai-spector/graph/`. Run after adding or changing source files.
+CLI fallback: `npx ai-spector analyze` → `npx ai-spector graph merge --from-knowledge` → `npx ai-spector graph validate`
 
 ### Index (refresh after doc edits)
 
-```bash
-npx ai-spector index
 ```
+index({ cocoindexSync: true })           # MCP — refresh graph + embeddings
+```
+
+CLI fallback: `npx ai-spector index && npx ai-spector cocoindex index`
 
-Updates fingerprints, reconciles translation queue. Run after any doc edit. **Always run index before checking translation status.**
+**Always run index before checking translation status.**
 
 ### Validate
 
-```bash
-npx ai-spector graph validate
+```
+graph_validate({})                       # MCP
+graph_report({})                         # MCP — layer health audit
 ```
 
-Reports broken references, missing nodes, DAG errors. Fix errors before generating docs.
+CLI fallback: `npx ai-spector graph validate`
 
 ### Impact (what to regenerate)
 
-```bash
-# Current git diff (most common)
-npx ai-spector graph impact --git --change content_change --json
-
-# Specific file
-npx ai-spector graph impact --file <repo-relative-path> --json
-
-# Specific node
-npx ai-spector graph impact <originId> --change content_change --json
+```
+graph_impact({ git: true, change: "content_change" })        # git diff
+graph_impact({ originId: "<id>", change: "content_change" }) # specific node
+graph_impact({ file: "<path>", change: "content_change" })   # specific file
 ```
 
-Output buckets: `regenerate` (must redo), `review` (may need update).
-- `noTraceabilityImpact: true` → changed files not in graph (config, source code, etc.) — no doc regen needed
-- `truncated: true` → BFS hit propagation cap — results may be incomplete, warn user
+CLI fallback: `npx ai-spector graph impact --git --change content_change --json`
 
-Report the table with `projectionPath`. For each `regenerate` entry, suggest the appropriate generate skill.
+Output buckets: `regenerate` (must redo), `review` (may need update), `semanticSuggestions` (CocoIndex).
+- `noTraceabilityImpact: true` → changed files not in graph — no doc regen needed
+- `truncated: true` → BFS hit cap — results may be incomplete, warn user
 
-**Run this after every doc edit**, then run `npx ai-spector index`.
+**Run after every doc edit**, then `index({ cocoindexSync: true })`.
 
-### Visualize
+### Query a node
 
-```bash
-npx ai-spector graph visualize --open
+```
+graph_query({ seedId: "<id>" })          # MCP — walk subgraph
+graph_query_fuzzy({ query: "…" })       # MCP — natural language lookup
 ```
 
-### Query a node
+CLI fallback: `npx ai-spector graph query <id> --json`
+
+### Visualize
 
 ```bash
-npx ai-spector graph query <id-or-text> --json
+npx ai-spector graph visualize --open    # CLI only — no MCP equivalent
 ```
 
 ## Checklist
 
 ```
 - [ ] Identified correct runbook
-- [ ] Ran CLI from project root
+- [ ] Used MCP tools (not CLI) when ai-spector server is configured
+- [ ] After doc edits: graph_impact + index({ cocoindexSync: true })
 - [ ] Presented output to user (impact table, validate errors, etc.)
-- [ ] After doc edits: ran impact + index
 - [ ] On failure: showed output, offered fix/workaround
 ```
 
 ## Rules
 
-- Do not implement impact BFS manually — always use CLI
-- Do not invent regen lists if impact CLI failed
-- Do not run whole-repo regen outside CLI buckets
+- Do not implement impact BFS manually — always use MCP or CLI tool
+- Do not invent regen lists if impact tool failed
+- Do not run whole-repo regen outside tool buckets
+- Never skip `cocoindexSync` when CocoIndex is configured and docs changed

package/scaffold/claude/.claude/skills/ai-spector-lang-status/skill.md

@@ -21,14 +21,23 @@ If only one language: reply "Only one language configured — nothing to compare
 
 ### 2. Refresh the index first (MANDATORY)
 
-```bash
-npx ai-spector index
+```
+index({})                    # MCP preferred
+npx ai-spector index         # CLI fallback
 ```
 
 The queue is only accurate after indexing. **Never skip this step** — reading `pending.json` without indexing shows stale data.
 
 ### 3. Read the queue
 
+**MCP (preferred):**
+```
+lang_queue({})                      # pending + summary
+lang_queue({ status: "failed" })    # failed jobs
+lang_queue({ lang: "jp" })          # filter by language
+```
+
+**CLI fallback:**
 ```bash
 npx ai-spector lang queue pending --json
 npx ai-spector lang queue failed --json
@@ -70,9 +79,9 @@ If queue is empty or missing after index, fall back to git mtime comparison acro
 
 ```
 - [ ] Read docflow.config.json → languages[]
-- [ ] Ran npx ai-spector index (mandatory before queue read)
-- [ ] Ran lang queue pending --json
-- [ ] Ran lang queue failed --json
+- [ ] Ran index({}) MCP (or npx ai-spector index) — mandatory before queue read
+- [ ] Ran lang_queue({}) MCP (or lang queue pending --json)
+- [ ] Ran lang_queue({ status: "failed" }) MCP (or lang queue failed --json)
 - [ ] Rendered pending + failed tables
 - [ ] Offered resolve-translation if pending jobs exist
 ```

package/scaffold/claude/CLAUDE.md

@@ -30,33 +30,46 @@ npx ai-spector index         # CLI fallback
 
 Then read the queue. **Never read `.ai-spector/.docflow/translation-queue/pending.json` without running index first** — the queue is only accurate after indexing.
 
-### 3. Check impact before finishing any doc edit
+### 3. Check impact and refresh embeddings after any doc edit
 
-After editing any file under `docs/srs/`, `docs/basic-design/`, or `docs/detail-design/`, run impact before closing the task:
+After editing any file under `docs/srs/`, `docs/basic-design/`, or `docs/detail-design/`:
 
+**a) Impact:**
 ```
 graph_impact({ git: true, change: "content_change" })   # MCP preferred
 npx ai-spector graph impact --git --change content_change --json  # CLI fallback
 ```
 
-Then refresh index:
+**b) Re-index + embeddings (mandatory when CocoIndex is configured):**
+```
+index({ cocoindexSync: true })    # preferred — refreshes graph + embeddings in one call
+```
 
+Or separately:
 ```
 index({})
+cocoindex_index({})
 ```
 
-Skip only when the user explicitly says it was a typo-only fix with no traceability concern.
+CLI fallback: `npx ai-spector index && npx ai-spector cocoindex index`
+
+Skip impact/index only when the user explicitly says it was a typo-only fix with no traceability concern. **Never skip `cocoindexSync` when CocoIndex is configured** — semantic search goes stale silently.
 
 ### 4. Use MCP/graph — not file search
 
 | Need | MCP (preferred) | CLI fallback |
 |------|-----------------|--------------|
+| Prepare graph scaffold | `analyze({})` | `npx ai-spector analyze` |
+| Check knowledge.json before merge | `knowledge_status({})` · `knowledge_validate({})` | *(no CLI)* |
+| Merge knowledge → graph | `graph_merge({ fromKnowledge: true })` | `npx ai-spector graph merge --from-knowledge` |
 | Find what needs regeneration | `graph_impact({ git: true, change: "content_change" })` | `npx ai-spector graph impact --git --json` |
-| Find node by exact ID | `graph_query({ id: "…" })` | `npx ai-spector graph query <id> --json` |
-| Find node by concept | `graph_query_fuzzy(query: "…")` — requires CocoIndex | — |
-| Search docs by meaning | `docs_search(query: "…")` — requires CocoIndex | — |
-| Check graph health | `graph_validate({})` | `npx ai-spector graph validate` |
-| See pending translations | *(CLI only)* | `npx ai-spector lang queue pending --json` (after index) |
+| Find node by exact ID | `graph_query({ seedId: "…" })` | `npx ai-spector graph query <id> --json` |
+| Find node by concept | `graph_query_fuzzy({ query: "…" })` — requires CocoIndex | — |
+| Search docs by meaning | `docs_search({ query: "…" })` — requires CocoIndex | — |
+| Check graph health | `graph_validate({})` · `graph_report({})` | `npx ai-spector graph validate` |
+| Translation queue | `lang_queue({})` | `npx ai-spector lang queue pending --json` (after index) |
+| CocoIndex readiness | `cocoindex_status({})` | `npx ai-spector setup --check` |
+| Rebuild embeddings | `cocoindex_index({})` or `index({ cocoindexSync: true })` | `npx ai-spector cocoindex index` |
 
 **Only fall back to `grep` or `Read` when the tool returns no results or you need raw file content for editing.**
 
@@ -83,11 +96,21 @@ Skip only when the user explicitly says it was a typo-only fix with no traceabil
 
 | Tool | Purpose |
 |------|---------|
-| `index({})` | Refresh fingerprints + translation queue |
+| `analyze({})` | Prepare graph scaffold from templates |
+| `knowledge_status({})` | Check knowledge.json entity counts |
+| `knowledge_validate({})` | Validate knowledge.json schema |
 | `graph_merge({ fromKnowledge: true })` | Merge knowledge.json into graph |
 | `graph_validate({})` | Check graph integrity |
-| `graph_impact({ git: true, change: "content_change" })` | Impact of current git diff |
-| `graph_query({ id: "…" })` | Walk graph from a node |
+| `graph_report({})` | Graph layer health audit |
+| `graph_impact({ git: true, change: "…" })` | Impact of current git diff |
+| `graph_query({ seedId: "…" })` | Walk graph from a node |
+| `index({})` | Refresh graph + translation queue |
+| `index({ cocoindexSync: true })` | Refresh graph + translation queue + embeddings |
+| `lang_queue({})` | Translation queue status |
+| `cocoindex_status({})` | CocoIndex readiness check |
+| `cocoindex_index({})` | Rebuild semantic embeddings |
+| `docs_search({ query })` | Semantic doc search (CocoIndex) |
+| `graph_query_fuzzy({ query })` | Natural language graph lookup (CocoIndex) |
 
 ### CLI (fallback / MCP-unavailable or no tool equivalent)
 

package/scaffold/cursor/WORKFLOW.md

@@ -1,6 +1,6 @@
 # AI Spector workflow
 
-**You describe what you need in chat.** Cursor picks the right **skill**; the agent runs **`npx ai-spector`** CLI. You do not need to memorize command names.
+**You describe what you need in chat.** Cursor picks the right **skill**; the agent calls **MCP tools** (when `ai-spector` server is configured) or falls back to **`npx ai-spector`** CLI. You do not need to memorize command names.
 
 Enable all skills under `.cursor/skills/` (see [skills/README.md](./skills/README.md)). On CLI or tool failure: agent pauses, shows output, and offers fix / workaround / pause — [cli-failures](./skills/ai-spector/references/cli-failures.md).
 
@@ -21,24 +21,24 @@ Then: add files under `docs/data-source/`, enable **all** skills under `.cursor/
 
 ## What to say → skill → agent does
 
-| You want to… | Say (examples) | Skill | Agent runs (summary) |
-|--------------|----------------|-------|----------------------|
+| You want to… | Say (examples) | Skill | Agent runs (MCP preferred) |
+|--------------|----------------|-------|---------------------------|
 | **Setup project** | “setup ai-spector”, “initialize project”, “get started” | `ai-spector-setup` | `setup --check` → `setup -y` → enable skills checklist |
-| 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` | `npx ai-spector index` |
-| Write SRS | “generate SRS”, “write use cases” | `ai-spector-generate-srs` | DAG waves → docs/srs → merge → index |
-| Basic design | “screen list”, “API design”, “wireframes” | `ai-spector-generate-basic-design` | docs/basic-design → merge → index each wave |
+| Ingest sources | “analyze my data source”, “build the knowledge graph” | `ai-spector-graph` | `analyze({})` → agent extracts → `knowledge_validate` → `graph_merge` → `graph_validate` |
+| Check graph health | “validate the graph”, “graph errors”, “graph report” | `ai-spector-graph` | `graph_validate({})` · `graph_report({})` |
+| Refresh after edits | “re-index”, “sync the graph” | `ai-spector-graph` | `index({ cocoindexSync: true })` (or `index({})` if no CocoIndex) |
+| Write SRS | “generate SRS”, “write use cases” | `ai-spector-generate-srs` | DAG waves → docs/srs → `graph_merge` → `index({ cocoindexSync: true })` |
+| Basic design | “screen list”, “API design”, “wireframes” | `ai-spector-generate-basic-design` | docs/basic-design → `graph_merge` → `index({ cocoindexSync: true })` each wave |
 | Detail design | “detail design for checkout” | `ai-spector-generate-detail-design` | docs/detail-design |
 | HTML prototype | “HTML mockup”, “prototype with stripe theme” | `ai-spector-generate-prototype` | auth picker (if needed) → theme picker → setup → HTML → validate |
-| Pick / preview UI theme | “help me pick a theme”, “show me themes”, “what fits my app?” | `ai-spector-generate-prototype` | read project context → recommend 3 → `prototype preview` ×3 |
-| What to redo | “what’s impacted”, “what should I regenerate” | `ai-spector-graph` | `graph impact` / git diff — includes semantic suggestions if CocoIndex configured |
-| Find docs by concept | “find all mentions of rate limiting”, “which docs describe login?” | `ai-spector-search` | `docs_search` MCP tool or `cocoindex search --query` |
-| Find graph node by name | “show graph for user login” (node ID unknown) | `ai-spector-search` | `graph_query_fuzzy` MCP tool |
-| Translation status | “what’s stale in JP”, “pending translations” | `ai-spector-lang-status` | `lang queue pending` |
-| Sync translations | “resolve translations”, “update JP from EN” | `ai-spector-resolve-translation` | read queue → translate → `index` |
+| Pick / preview UI theme | “help me pick a theme”, “show me themes” | `ai-spector-generate-prototype` | read project context → recommend 3 → `prototype preview` ×3 |
+| What to redo | “what’s impacted”, “what should I regenerate” | `ai-spector-graph` | `graph_impact({ git: true, change: “…” })` — includes `semanticSuggestions` when CocoIndex ready |
+| Find docs by concept | “find all mentions of rate limiting”, “which docs describe login?” | `ai-spector-search` | `docs_search({ query })` MCP |
+| Find graph node by name | “show graph for user login” (node ID unknown) | `ai-spector-search` | `graph_query_fuzzy({ query })` MCP |
+| Translation status | “what’s stale in JP”, “pending translations” | `ai-spector-lang-status` | `lang_queue({})` MCP |
+| Sync translations | “resolve translations”, “update JP from EN” | `ai-spector-resolve-translation` | read queue → translate → `index({ cocoindexSync: true })` |
 | Review comments | “resolve comments”, “fix C-001” | `ai-spector-resolve-comments` | inbox → plan → edit → commit |
-| Explore graph | “show the graph” | `ai-spector-graph` | `graph visualize --open` |
+| Explore graph | “show the graph” | `ai-spector-graph` | `npx ai-spector graph visualize --open` (no MCP equivalent) |
 
 Unsure? The agent uses [skills/_skill-router.md](./skills/_skill-router.md) or asks one clarifying question.
 

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

@@ -18,14 +18,40 @@ When the `ai-spector` MCP server is enabled (`.cursor/mcp.json` or `.mcp.json` l
 
 | Operation | MCP tool | CLI fallback |
 |-----------|----------|--------------|
-| Re-index project | `index({})` | `npx ai-spector index` |
+| Prepare graph scaffold | `analyze({})` | `npx ai-spector analyze` |
+| Check knowledge.json entity counts | `knowledge_status({})` | *(no CLI equivalent)* |
+| Validate knowledge.json schema | `knowledge_validate({})` | *(no CLI equivalent)* |
 | Merge knowledge → graph | `graph_merge({ fromKnowledge: true })` | `npx ai-spector graph merge --from-knowledge` |
 | Validate graph | `graph_validate({})` | `npx ai-spector graph validate` |
+| Graph layer health audit | `graph_report({})` | `npx ai-spector graph report --json` |
 | Impact analysis | `graph_impact({ originId, change })` | `npx ai-spector graph impact …` |
-| Walk graph from node | `graph_query({ id, … })` | `npx ai-spector graph query <id> --json` |
-| **Analyze data-source** | *(no MCP tool — CLI only)* | `npx ai-spector analyze` |
+| Walk graph from node | `graph_query({ seedId })` | `npx ai-spector graph query <id> --json` |
+| Re-index project | `index({})` | `npx ai-spector index` |
+| Re-index + refresh embeddings | `index({ cocoindexSync: true })` | `npx ai-spector index && npx ai-spector cocoindex index` |
+| Translation queue status | `lang_queue({})` | `npx ai-spector lang queue pending --json` |
+| CocoIndex readiness | `cocoindex_status({})` | `npx ai-spector setup --check` |
+| Rebuild semantic embeddings | `cocoindex_index({})` | `npx ai-spector cocoindex index` |
+| Semantic doc search | `docs_search({ query })` | `npx ai-spector cocoindex search --query …` |
+| Natural language graph lookup | `graph_query_fuzzy({ query })` | *(no CLI equivalent)* |
+| **Visualize graph** | *(no MCP tool)* | `npx ai-spector graph visualize --open` |
+
+Use CLI **only** when: MCP server is not configured, the tool errors, or no MCP equivalent exists (visualize, `lang add`, template mutations).
+
+### After any batch of doc edits
+
+When you finish editing files under `docs/` — always close out with:
+
+```
+index({ cocoindexSync: true })   # preferred: refreshes graph + embeddings in one call
+```
+
+Or if CocoIndex is not configured:
+
+```
+index({})
+```
 
-Use CLI **only** when: MCP server is not configured, the tool errors and MCP is unavailable, or the operation has no MCP equivalent (e.g. `analyze`).
+**Never skip the embedding refresh** when CocoIndex is set up — semantic search and `graph_impact` `semanticSuggestions` go stale silently.
 
 ## CLI and tool failure (non-negotiable)
 

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

@@ -2,7 +2,7 @@
 
 Ingest `docs/data-source/` and commit knowledge into the traceability graph.
 
-Step 0 (`npx ai-spector analyze`) is **CLI-only** — no MCP equivalent. Steps B (merge, validate) use **MCP when available**.
+All steps have MCP equivalents. Use MCP when the `ai-spector` server is configured.
 
 ## Usage
 
@@ -20,6 +20,12 @@ Step 0 (`npx ai-spector analyze`) is **CLI-only** — no MCP equivalent. Steps B
 
 ### 0. Prepare graph structure
 
+**MCP (preferred):**
+```
+analyze({})
+```
+
+**CLI fallback:**
 ```bash
 npx ai-spector analyze
 ```
@@ -82,7 +88,10 @@ Update `state.json`: `analysis.lastRunAt`, `analysis.dataSource`, scope hash. Me
 
 | Step | MCP (preferred) | CLI fallback |
 |------|-----------------|--------------|
-| 0 | *(CLI only — no MCP tool)* | `npx ai-spector analyze` |
+| 0 prepare | `analyze({})` | `npx ai-spector analyze` |
+| A extraction | Agent writes `knowledge.json` | Agent writes `knowledge.json` |
+| A verify | `knowledge_status({})` → check `ready: true` | *(no CLI)* |
+| A validate | `knowledge_validate({})` → check `valid: true` | *(no CLI)* |
 | B merge | `graph_merge({ fromKnowledge: true })` | `npx ai-spector graph merge --from-knowledge` |
 | B validate | `graph_validate({})` | `npx ai-spector graph validate` |
 

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

@@ -20,14 +20,24 @@ paths:
 
 2. **Refresh the index first** — the queue is only accurate after indexing:
 
-```bash
-npx ai-spector index
 ```
+index({})                    # MCP preferred
+npx ai-spector index         # CLI fallback
+```
+
+Skip only if the user explicitly says they just ran it.
 
-This scans all doc files, updates fingerprints, and reconciles pending/resolved jobs in the translation queue. Skip only if the user explicitly says they just ran it.
+3. Read the translation queue (primary source of truth):
 
-3. Run the translation queue CLI (primary source of truth):
+**MCP (preferred):**
+```
+lang_queue({})                          # pending jobs + summary
+lang_queue({ status: "failed" })        # failed jobs
+lang_queue({ status: "all" })           # everything
+lang_queue({ lang: "jp" })              # filter by language
+```
 
+**CLI fallback:**
 ```bash
 npx ai-spector lang queue pending --json
 npx ai-spector lang queue failed --json
@@ -113,7 +123,7 @@ List actionable items per job:
 
 ## After any file edit (outside of generate skills)
 
-When the user edits any language file directly, run `npx ai-spector index` (or `lang queue scan`). The queue enqueues section-level sync jobs automatically — no manual stale notes needed.
+When the user edits any language file directly, run `index({})` (MCP) or `npx ai-spector index`. The queue enqueues section-level sync jobs automatically — no manual stale notes needed.
 
 If the user defers translation, the job stays in `pending.json` until processed.
 

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

@@ -35,15 +35,16 @@ surface related docs that have no formal graph edge.
 
 Find all document sections about a concept:
 
-```bash
-npx ai-spector cocoindex search --query "rate limiting" --json
-```
-
-Or via MCP:
+**MCP (preferred):**
 ```
 docs_search(query: "rate limiting", limit: 5)
 ```
 
+**CLI fallback:**
+```bash
+npx ai-spector cocoindex search --query "rate limiting" --json
+```
+
 Response includes `graphNodeId` when the matched section maps to a traceability node.
 Use that to run `graph_query` for full context.
 
@@ -109,19 +110,37 @@ No code change needed — chain two MCP calls:
 
 ## Setup check
 
-Before using any semantic workflow, verify CocoIndex is configured:
+Before using any semantic workflow, verify CocoIndex is ready:
+
+**MCP (preferred):**
+```
+cocoindex_status({})
+```
+
+Check `ready: true`. If any issue is listed, fix it before searching.
 
+**CLI fallback:**
 ```bash
 npx ai-spector setup --check
 ```
 
-If CocoIndex is missing:
-```bash
-npx ai-spector cocoindex setup
-cd .ai-spector/.docflow/cocoindex
-cp .env.example .env   # edit if needed
-pip install -r requirements.txt
-python pipeline.py cocoindex update
+If CocoIndex is missing, run `npx ai-spector cocoindex setup` (or ask agent to set it up via `ai-spector-setup` skill).
+
+---
+
+## Rebuild embeddings after doc edits
+
+Semantic search goes stale when docs change. After any batch of doc edits:
+
+**Preferred — one call:**
+```
+index({ cocoindexSync: true })
+```
+
+**Or separately:**
+```
+cocoindex_index({})
+index({})
 ```
 
 ---
@@ -129,8 +148,8 @@ python pipeline.py cocoindex update
 ## Checklist
 
 ```
-- [ ] CocoIndex configured (pipeline.py present)
-- [ ] Embeddings up to date (run pipeline.py cocoindex update after doc edits)
+- [ ] cocoindex_status({}) → ready: true (or setup done)
+- [ ] Embeddings refreshed after doc edits: index({ cocoindexSync: true })
 - [ ] Used graph_query_fuzzy when node ID is unknown (not graph_query with a guess)
 - [ ] Treated semanticSuggestions as "review recommended", not "must regenerate"
 ```