maestro-flow 0.5.48 → 0.5.49

package/.agents/skills/manage-harvest/SKILL.md

@@ -48,7 +48,7 @@ Additional flags, source registry (scan paths), and storage locations defined in
 2. **Never modify source artifacts** — harvest is purely extractive; source files remain untouched
 3. **Dedup before write** — MUST check harvest-log.jsonl and existing stores before each write to prevent duplicates
 4. **Source tagging** — MUST set `source: "harvest"` on every issues.jsonl row so concurrent writers can be distinguished
-5. **Conflict pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category; set `confidence="low"` and log conflict note if semantic conflict detected
+5. **Relationship pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category. Classify the relationship: **supersede** (new replaces old) → attach `supersedes = <old-sid>`, after add run `maestro spec supersede`; **conflict** (genuine dispute) → set `confidence="low"` and log conflict note; **independent** → no metadata
 6. **Provenance tracking** — every routed item MUST be logged in harvest-log.jsonl with fragment ID, target store, and timestamp
 7. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview only
 </invariants>
@@ -88,8 +88,10 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 | Wiki graph needs linking | `/manage-wiki connect --fix` |
 | Issues created | `/manage-issue list --source harvest` |
 | Specs extracted | `/spec-load --role implement` |
-| Specs extracted (冲突审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾 |
+| Specs extracted (审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾或替代 |
+| 查看演化链 | `maestro spec history <sid>` — 确认 supersede 链完整 |
 | Spec 冲突标记已存在 | `maestro spec conflict list` — 查看当前冲突状态 |
+| 知识健康检查 | `maestro spec health` — 悬空/循环 supersedes 校验 |
 | Full phase retrospective | `/quality-retrospective` |
 </completion>
 

package/.agents/skills/manage-knowledge-audit/SKILL.md

@@ -83,15 +83,17 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 
 ### Conflict Resolution Integration
 
-四态决策（扩展自三态 keep/deprecate/delete）：
+五态决策（扩展自三态 keep/deprecate/delete）：
 
 | 动作 | 适用场景 | 执行 |
 |------|---------|------|
 | `keep` | 内容正确，无需变更 | 写 audit-log ignore 记录 |
 | `contest` | 矛盾真实存在，需进一步审查 | `maestro spec conflict mark <file> <line> --note "<evidence>"` |
-| `deprecate` | 内容过时或被取代 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
+| `supersede` | 内容过时，已有更新版本替代 | `maestro spec supersede <old-sid> --by <new-sid>`（保留演化链） |
+| `deprecate` | 内容过时，无替代版本 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
 | `delete` | 内容明确错误 | 移除 entry + `maestro spec conflict clear <file> <line>` |
 
+**supersede vs deprecate**: supersede 用于有明确替代条目的场景（建立演化链），deprecate 用于无替代条目的场景。
 **关键**: deprecate/delete 执行时，如果目标条目有 conflict-marker，必须同步调用 `maestro spec conflict clear` 清除标记，避免悬空冲突。
 
 ### Code-as-Truth 校验（审查核心原则）
@@ -117,6 +119,9 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 | 验证 spec 现状 | `/spec-load --role implement` |
 | 查看冲突标记 | `maestro spec conflict list` |
 | 清除已解决冲突 | `maestro spec conflict clear-all <file>` |
+| 查看演化链 | `maestro spec history <sid>` |
+| 知识健康检查 | `maestro spec health` |
+| 回填存量 sid | `maestro spec backfill-sid` |
 | 周期巡检 | `--scope all --report` |
 </completion>
 

package/.agents/skills/quality-review/SKILL.md

@@ -66,7 +66,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 3. **Verdict is data-driven** — NEVER change verdict severity to accommodate user preference without new evidence. Verdicts flow from findings, not negotiation.
 4. **Dimension independence** — each review dimension produces findings independently. One dimension's results MUST NOT suppress or override another's.
 5. **Prior review delta** — when a prior review.json exists for the same phase, findings MUST be compared. Do NOT re-report already-resolved findings as new.
-6. **Spec conflict integrity** — if code contradicts a spec entry, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
+6. **Spec conflict integrity** — if code contradicts a spec entry: if the code is the evolved practice (spec outdated), suggest `maestro spec supersede`; if genuinely disputed, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
 </invariants>
 
 <execution>
@@ -87,7 +87,7 @@ Follow '~/.maestro/workflows/review.md' completely.
 - REQUIRED: review.json written with findings, severity distribution, and verdict.
 - REQUIRED: Issues auto-created based on level thresholds.
 - REQUIRED: index.json updated with review status.
-- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule), suggest `maestro spec conflict mark` on the spec entry. Code is the single source of truth.
+- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule): if spec is outdated (code evolved), suggest `maestro spec supersede`; if genuinely disputed, suggest `maestro spec conflict mark`. Code is the single source of truth.
 
 **Output writes to REVIEW_DIR** (not EXEC_DIR):
 - `REVIEW_DIR/review.json` — findings, severity distribution, verdict

package/.agents/skills/spec-add/SKILL.md

@@ -25,6 +25,7 @@ $ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
 
 **Options:**
 - `--description <desc>` — One-line description for search results (falls back to content[:240])
+- `--json` — Output JSON with generated `sid` (needed for supersession: `maestro spec supersede <old-sid> --by <new-sid>`)
 - `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
 - `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
 
@@ -104,6 +105,9 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 | Condition | Suggestion |
 |-----------|-----------|
 | Verify entry added | `maestro load --type spec --scope <scope> --keyword {keyword}` |
+| New entry replaces old one | `maestro spec supersede <old-sid> --by <new-sid>` |
+| View evolution chain | `maestro spec history <sid>` |
 | Add more entries | `/spec-add <category>` |
 | View all specs | `/spec-load --category <category>` |
+| Check knowledge health | `maestro spec health` |
 </completion>

package/.agy/skills/manage-harvest/SKILL.md

@@ -48,7 +48,7 @@ Additional flags, source registry (scan paths), and storage locations defined in
 2. **Never modify source artifacts** — harvest is purely extractive; source files remain untouched
 3. **Dedup before write** — MUST check harvest-log.jsonl and existing stores before each write to prevent duplicates
 4. **Source tagging** — MUST set `source: "harvest"` on every issues.jsonl row so concurrent writers can be distinguished
-5. **Conflict pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category; set `confidence="low"` and log conflict note if semantic conflict detected
+5. **Relationship pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category. Classify the relationship: **supersede** (new replaces old) → attach `supersedes = <old-sid>`, after add run `maestro spec supersede`; **conflict** (genuine dispute) → set `confidence="low"` and log conflict note; **independent** → no metadata
 6. **Provenance tracking** — every routed item MUST be logged in harvest-log.jsonl with fragment ID, target store, and timestamp
 7. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview only
 </invariants>
@@ -88,8 +88,10 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 | Wiki graph needs linking | `/manage-wiki connect --fix` |
 | Issues created | `/manage-issue list --source harvest` |
 | Specs extracted | `/spec-load --role implement` |
-| Specs extracted (冲突审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾 |
+| Specs extracted (审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾或替代 |
+| 查看演化链 | `maestro spec history <sid>` — 确认 supersede 链完整 |
 | Spec 冲突标记已存在 | `maestro spec conflict list` — 查看当前冲突状态 |
+| 知识健康检查 | `maestro spec health` — 悬空/循环 supersedes 校验 |
 | Full phase retrospective | `/quality-retrospective` |
 </completion>
 

package/.agy/skills/manage-knowledge-audit/SKILL.md

@@ -83,15 +83,17 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 
 ### Conflict Resolution Integration
 
-四态决策（扩展自三态 keep/deprecate/delete）：
+五态决策（扩展自三态 keep/deprecate/delete）：
 
 | 动作 | 适用场景 | 执行 |
 |------|---------|------|
 | `keep` | 内容正确，无需变更 | 写 audit-log ignore 记录 |
 | `contest` | 矛盾真实存在，需进一步审查 | `maestro spec conflict mark <file> <line> --note "<evidence>"` |
-| `deprecate` | 内容过时或被取代 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
+| `supersede` | 内容过时，已有更新版本替代 | `maestro spec supersede <old-sid> --by <new-sid>`（保留演化链） |
+| `deprecate` | 内容过时，无替代版本 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
 | `delete` | 内容明确错误 | 移除 entry + `maestro spec conflict clear <file> <line>` |
 
+**supersede vs deprecate**: supersede 用于有明确替代条目的场景（建立演化链），deprecate 用于无替代条目的场景。
 **关键**: deprecate/delete 执行时，如果目标条目有 conflict-marker，必须同步调用 `maestro spec conflict clear` 清除标记，避免悬空冲突。
 
 ### Code-as-Truth 校验（审查核心原则）
@@ -117,6 +119,9 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 | 验证 spec 现状 | `/spec-load --role implement` |
 | 查看冲突标记 | `maestro spec conflict list` |
 | 清除已解决冲突 | `maestro spec conflict clear-all <file>` |
+| 查看演化链 | `maestro spec history <sid>` |
+| 知识健康检查 | `maestro spec health` |
+| 回填存量 sid | `maestro spec backfill-sid` |
 | 周期巡检 | `--scope all --report` |
 </completion>
 

package/.agy/skills/quality-review/SKILL.md

@@ -66,7 +66,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 3. **Verdict is data-driven** — NEVER change verdict severity to accommodate user preference without new evidence. Verdicts flow from findings, not negotiation.
 4. **Dimension independence** — each review dimension produces findings independently. One dimension's results MUST NOT suppress or override another's.
 5. **Prior review delta** — when a prior review.json exists for the same phase, findings MUST be compared. Do NOT re-report already-resolved findings as new.
-6. **Spec conflict integrity** — if code contradicts a spec entry, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
+6. **Spec conflict integrity** — if code contradicts a spec entry: if the code is the evolved practice (spec outdated), suggest `maestro spec supersede`; if genuinely disputed, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
 </invariants>
 
 <execution>
@@ -87,7 +87,7 @@ Follow '~/.maestro/workflows/review.md' completely.
 - REQUIRED: review.json written with findings, severity distribution, and verdict.
 - REQUIRED: Issues auto-created based on level thresholds.
 - REQUIRED: index.json updated with review status.
-- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule), suggest `maestro spec conflict mark` on the spec entry. Code is the single source of truth.
+- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule): if spec is outdated (code evolved), suggest `maestro spec supersede`; if genuinely disputed, suggest `maestro spec conflict mark`. Code is the single source of truth.
 
 **Output writes to REVIEW_DIR** (not EXEC_DIR):
 - `REVIEW_DIR/review.json` — findings, severity distribution, verdict

package/.agy/skills/spec-add/SKILL.md

@@ -22,6 +22,7 @@ $ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
 
 **Options:**
 - `--description <desc>` — One-line description for search results (falls back to content[:240])
+- `--json` — Output JSON with generated `sid` (needed for supersession: `maestro spec supersede <old-sid> --by <new-sid>`)
 - `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
 - `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
 
@@ -101,6 +102,9 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 | Condition | Suggestion |
 |-----------|-----------|
 | Verify entry added | `maestro load --type spec --scope <scope> --keyword {keyword}` |
+| New entry replaces old one | `maestro spec supersede <old-sid> --by <new-sid>` |
+| View evolution chain | `maestro spec history <sid>` |
 | Add more entries | `/spec-add <category>` |
 | View all specs | `/spec-load --category <category>` |
+| Check knowledge health | `maestro spec health` |
 </completion>

package/.claude/commands/manage-harvest.md

@@ -46,7 +46,7 @@ Additional flags, source registry (scan paths), and storage locations defined in
 2. **Never modify source artifacts** — harvest is purely extractive; source files remain untouched
 3. **Dedup before write** — MUST check harvest-log.jsonl and existing stores before each write to prevent duplicates
 4. **Source tagging** — MUST set `source: "harvest"` on every issues.jsonl row so concurrent writers can be distinguished
-5. **Conflict pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category; set `confidence="low"` and log conflict note if semantic conflict detected
+5. **Relationship pre-check on spec routing** — when routing to spec, MUST compare against existing specs with same keywords/category. Classify the relationship: **supersede** (new replaces old) → attach `supersedes = <old-sid>`, after add run `maestro spec supersede`; **conflict** (genuine dispute) → set `confidence="low"` and log conflict note; **independent** → no metadata
 6. **Provenance tracking** — every routed item MUST be logged in harvest-log.jsonl with fragment ID, target store, and timestamp
 7. **Dry-run safety** — `--dry-run` MUST NOT write any files; preview only
 </invariants>
@@ -86,8 +86,10 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 | Wiki graph needs linking | `/manage-wiki connect --fix` |
 | Issues created | `/manage-issue list --source harvest` |
 | Specs extracted | `/spec-load --role implement` |
-| Specs extracted (冲突审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾 |
+| Specs extracted (审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾或替代 |
+| 查看演化链 | `maestro spec history <sid>` — 确认 supersede 链完整 |
 | Spec 冲突标记已存在 | `maestro spec conflict list` — 查看当前冲突状态 |
+| 知识健康检查 | `maestro spec health` — 悬空/循环 supersedes 校验 |
 | Full phase retrospective | `/quality-retrospective` |
 </completion>
 

package/.claude/commands/manage-knowledge-audit.md

@@ -81,15 +81,17 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 
 ### Conflict Resolution Integration
 
-四态决策（扩展自三态 keep/deprecate/delete）：
+五态决策（扩展自三态 keep/deprecate/delete）：
 
 | 动作 | 适用场景 | 执行 |
 |------|---------|------|
 | `keep` | 内容正确，无需变更 | 写 audit-log ignore 记录 |
 | `contest` | 矛盾真实存在，需进一步审查 | `maestro spec conflict mark <file> <line> --note "<evidence>"` |
-| `deprecate` | 内容过时或被取代 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
+| `supersede` | 内容过时，已有更新版本替代 | `maestro spec supersede <old-sid> --by <new-sid>`（保留演化链） |
+| `deprecate` | 内容过时，无替代版本 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
 | `delete` | 内容明确错误 | 移除 entry + `maestro spec conflict clear <file> <line>` |
 
+**supersede vs deprecate**: supersede 用于有明确替代条目的场景（建立演化链），deprecate 用于无替代条目的场景。
 **关键**: deprecate/delete 执行时，如果目标条目有 conflict-marker，必须同步调用 `maestro spec conflict clear` 清除标记，避免悬空冲突。
 
 ### Code-as-Truth 校验（审查核心原则）
@@ -115,6 +117,9 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 | 验证 spec 现状 | `/spec-load --role implement` |
 | 查看冲突标记 | `maestro spec conflict list` |
 | 清除已解决冲突 | `maestro spec conflict clear-all <file>` |
+| 查看演化链 | `maestro spec history <sid>` |
+| 知识健康检查 | `maestro spec health` |
+| 回填存量 sid | `maestro spec backfill-sid` |
 | 周期巡检 | `--scope all --report` |
 </completion>
 

package/.claude/commands/quality-review.md

@@ -64,7 +64,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 3. **Verdict is data-driven** — NEVER change verdict severity to accommodate user preference without new evidence. Verdicts flow from findings, not negotiation.
 4. **Dimension independence** — each review dimension produces findings independently. One dimension's results MUST NOT suppress or override another's.
 5. **Prior review delta** — when a prior review.json exists for the same phase, findings MUST be compared. Do NOT re-report already-resolved findings as new.
-6. **Spec conflict integrity** — if code contradicts a spec entry, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
+6. **Spec conflict integrity** — if code contradicts a spec entry: if the code is the evolved practice (spec outdated), suggest `maestro spec supersede`; if genuinely disputed, flag via `maestro spec conflict mark`. NEVER silently accept the contradiction or edit the spec inline.
 </invariants>
 
 <execution>
@@ -85,7 +85,7 @@ Follow '~/.maestro/workflows/review.md' completely.
 - REQUIRED: review.json written with findings, severity distribution, and verdict.
 - REQUIRED: Issues auto-created based on level thresholds.
 - REQUIRED: index.json updated with review status.
-- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule), suggest `maestro spec conflict mark` on the spec entry. Code is the single source of truth.
+- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule): if spec is outdated (code evolved), suggest `maestro spec supersede`; if genuinely disputed, suggest `maestro spec conflict mark`. Code is the single source of truth.
 
 **Output writes to REVIEW_DIR** (not EXEC_DIR):
 - `REVIEW_DIR/review.json` — findings, severity distribution, verdict

package/.claude/commands/spec-add.md

@@ -23,6 +23,7 @@ $ARGUMENTS -- expects `[--scope <scope>] [--uid <uid>] <category> <content>`
 
 **Options:**
 - `--description <desc>` — One-line description for search results (falls back to content[:240])
+- `--json` — Output JSON with generated `sid` (needed for supersession: `maestro spec supersede <old-sid> --by <new-sid>`)
 - `--ref <path>` — Create as index entry referencing a knowhow document. If the path exists, only creates the spec index entry. If path doesn't exist, also creates the knowhow file.
 - `--knowhow-type <type>` — Knowhow document type when creating with --ref (asset, blueprint, document, template, recipe, reference, decision)
 
@@ -102,6 +103,9 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 | Condition | Suggestion |
 |-----------|-----------|
 | Verify entry added | `maestro load --type spec --scope <scope> --keyword {keyword}` |
+| New entry replaces old one | `maestro spec supersede <old-sid> --by <new-sid>` |
+| View evolution chain | `maestro spec history <sid>` |
 | Add more entries | `/spec-add <category>` |
 | View all specs | `/spec-load --category <category>` |
+| Check knowledge health | `maestro spec health` |
 </completion>

package/dashboard/dist-server/dashboard/src/server/wiki/embedding.d.ts

@@ -100,7 +100,7 @@ export declare function vectorSearch(queryVector: Float32Array, index: Embedding
  * Falls back to flat cosine scan when zvec is unavailable or feature flag is set.
  */
 export declare function vectorSearchZvec(queryVector: Float32Array, dir: string, limit: number): Promise<VectorSearchResult[]>;
-export declare function saveEmbeddingIndex(index: EmbeddingIndex, dir: string): void;
+export declare function saveEmbeddingIndex(index: EmbeddingIndex, dir: string): Promise<void>;
 export declare function loadEmbeddingIndex(dir: string): EmbeddingIndex | null;
 export interface DocForEmbedding {
     id: string;
@@ -109,7 +109,7 @@ export interface DocForEmbedding {
     tags: string[];
     body?: string;
 }
-export declare function hashDocContent(d: DocForEmbedding): string;
+export declare function hashDocContent(d: DocForEmbedding, enrichedText?: string): string;
 /**
  * Split a document into multiple chunks for embedding.
  * Short docs (<500 chars body) produce a single chunk.

package/dashboard/dist-server/dashboard/src/server/wiki/embedding.js

@@ -198,8 +198,6 @@ async function callEmbeddingApi(texts, config) {
     }
     if (firstErr) {
         const filled = results.filter(Boolean).length;
-        if (filled === 0)
-            throw firstErr;
         if (filled < texts.length)
             throw firstErr;
     }
@@ -472,12 +470,6 @@ const ZVEC_DIR = 'embedding.zvec';
 export function vectorSearch(queryVector, index, limit) {
     if (index.dimension && queryVector.length !== index.dimension)
         return [];
-    // Feature flag: force flat cosine scan (bypass zvec)
-    if (process.env.MAESTRO_EMBEDDING_FLAT_SCAN) {
-        return flatCosineSearch(queryVector, index, limit);
-    }
-    // Sync path — zvec requires async setup, so use flat scan here.
-    // For zvec-accelerated search, callers should use vectorSearchZvec.
     return flatCosineSearch(queryVector, index, limit);
 }
 /**
@@ -533,7 +525,7 @@ const SQLITE_FILE = 'embedding-index.db';
 import { createRequire } from 'node:module';
 const _require = createRequire(import.meta.url);
 const BINARY_FILE = 'embedding-index.bin';
-export function saveEmbeddingIndex(index, dir) {
+export async function saveEmbeddingIndex(index, dir) {
     mkdirSync(dir, { recursive: true });
     // --- Binary format (kept for backward compat and feature flag fallback) ---
     const dim = index.dimension;
@@ -573,10 +565,8 @@ export function saveEmbeddingIndex(index, dir) {
     const tmpPath = join(dir, BINARY_FILE + '.tmp');
     writeFileSync(tmpPath, buf);
     renameSync(tmpPath, join(dir, BINARY_FILE));
-    // --- zvec collection save (async, best-effort) ---
-    saveZvecIndex(index, dir).catch(() => {
-        // zvec save failed — binary format still available as fallback
-    });
+    // --- zvec collection save ---
+    await saveZvecIndex(index, dir);
     // Remove legacy files
     for (const f of [CACHE_FILE, SQLITE_FILE, SQLITE_FILE + '-shm', SQLITE_FILE + '-wal', SQLITE_FILE + '-journal']) {
         try {
@@ -586,14 +576,26 @@ export function saveEmbeddingIndex(index, dir) {
         catch { /* ignore */ }
     }
 }
+let _zvecSaving = false;
 /**
  * Save embedding index to zvec collection format.
  * Creates/replaces a zvec collection at `dir/embedding.zvec`.
  */
 async function saveZvecIndex(index, dir) {
+    if (_zvecSaving)
+        return;
     const zvec = await getZvec();
     if (!zvec)
         return;
+    _zvecSaving = true;
+    try {
+        await _saveZvecIndexInner(zvec, index, dir);
+    }
+    finally {
+        _zvecSaving = false;
+    }
+}
+async function _saveZvecIndexInner(zvec, index, dir) {
     const collectionPath = join(dir, ZVEC_DIR);
     const dim = index.dimension;
     // Remove existing collection directory if present
@@ -692,7 +694,7 @@ export function loadEmbeddingIndex(dir) {
     if (existsSync(dbPath)) {
         try {
             const idx = loadFromSqlite(dir);
-            saveEmbeddingIndex(idx, dir);
+            void saveEmbeddingIndex(idx, dir);
             return idx;
         }
         catch { /* fall through */ }
@@ -702,7 +704,7 @@ export function loadEmbeddingIndex(dir) {
     if (existsSync(jsonPath)) {
         try {
             const idx = loadFromLegacyJson(jsonPath);
-            saveEmbeddingIndex(idx, dir);
+            void saveEmbeddingIndex(idx, dir);
             return idx;
         }
         catch {
@@ -848,9 +850,11 @@ function loadFromLegacyJson(filePath) {
         buildTimeMs: raw.buildTimeMs,
     };
 }
-export function hashDocContent(d) {
-    const text = [d.title, d.summary, d.tags.join(','), d.body ?? ''].join('|');
-    return createHash('md5').update(text).digest('hex');
+export function hashDocContent(d, enrichedText) {
+    const parts = [d.title, d.summary, d.tags.join(','), d.body ?? ''];
+    if (enrichedText)
+        parts.push(enrichedText);
+    return createHash('md5').update(parts.join('|')).digest('hex');
 }
 /**
  * Extract meaningful content from a markdown body: first paragraph + heading lines,
@@ -938,7 +942,7 @@ export async function buildEmbeddingIndex(docs, existingIndex, precomputedHashes
     const apiMode = isApiMode();
     const config = apiMode ? null : await detectDevice();
     const t0 = Date.now();
-    const currentHashes = precomputedHashes ?? docs.map(hashDocContent);
+    const currentHashes = precomputedHashes ?? docs.map(d => hashDocContent(d));
     // Split all docs into chunks (1:N doc-to-chunk mapping)
     const allChunkIds = [];
     const allChunkDocIds = [];
@@ -957,34 +961,21 @@ export async function buildEmbeddingIndex(docs, existingIndex, precomputedHashes
     }
     let vectors;
     const activeModel = getModelId();
-    // Model changed → discard all cached vectors, force full rebuild
-    const modelMatch = existingIndex && existingIndex.modelId === activeModel;
+    const activeDim = apiMode ? (loadEmbeddingApiConfig()?.dimensions ?? 0) : 384;
+    // Model, dimensions, or mode changed → discard all cached vectors, force full rebuild
+    const modelMatch = existingIndex
+        && existingIndex.modelId === activeModel
+        && (activeDim === 0 || existingIndex.dimension === activeDim);
     if (modelMatch && existingIndex.docIds.length > 0) {
-        // Build existing chunk cache: chunkId → { vector, parentDocId }
         const existingChunkMap = new Map();
-        const existingDocHashes = new Map();
-        // Reconstruct per-doc hashes from existing index
         if (existingIndex.chunkDocIds && existingIndex.contentHashes) {
             for (let i = 0; i < existingIndex.docIds.length; i++) {
                 existingChunkMap.set(existingIndex.docIds[i], existingIndex.vectors[i]);
             }
-            // contentHashes are per-doc; find unique doc→hash mapping
-            const seen = new Set();
-            for (let i = 0; i < existingIndex.chunkDocIds.length; i++) {
-                const parentId = existingIndex.chunkDocIds[i];
-                if (!seen.has(parentId) && existingIndex.contentHashes[i] !== undefined) {
-                    // contentHashes in chunk-based index: stored per-doc in the order of docChunkRanges
-                    seen.add(parentId);
-                }
-            }
         }
         else {
-            // Legacy index without chunkDocIds — docIds are direct doc IDs
             for (let i = 0; i < existingIndex.docIds.length; i++) {
                 existingChunkMap.set(existingIndex.docIds[i], existingIndex.vectors[i]);
-                if (existingIndex.contentHashes?.[i]) {
-                    existingDocHashes.set(existingIndex.docIds[i], existingIndex.contentHashes[i]);
-                }
             }
         }
         // Determine which docs changed (hash comparison at doc level)