ai-spector 0.8.6 → 0.8.7

package/package.json

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

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"
 ```