maestro-flow 0.5.34 → 0.5.35

package/.codex/skills/maestro-ralph-execute/SKILL.md

@@ -128,19 +128,44 @@ S_FALLBACK:
 | maestro-brainstorm | topic | `"{intent}"` |
 | maestro-roadmap | description | `"{intent}"` |
 | maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
-| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
-| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| maestro-plan | phase, --from, or --dir | see --from auto-injection below |
+| maestro-execute | phase or --dir | see --from auto-injection below |
 | quality-debug | gap context | Read previous step's error/gap |
 | quality-* | phase | `{phase}` |
 
-**Artifact dir resolution for --dir:**
+**--from auto-injection (phase-level artifact chaining):**
+
+Phase-level steps 在 build 阶段无法预知前序 artifact ID。A_RESOLVE_ARGS 运行时从 state.json 查找并注入显式引用，打通 analyze→plan→execute 数据管道：
+
 ```
-Read state.json → filter artifacts by milestone + phase
-plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
-execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
+Read state.json.artifacts（含 milestone_history 内归档 artifacts）
+→ filter by milestone={session.milestone} + phase={session.phase} + status=="completed"
+
+plan step（含 {phase} 占位符，args 无 --from 且无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="analyze" artifact → id = ANL-xxx
+  2. 命中 → args 追加 --from analyze:{id}
+  3. 写 step.source_artifact_ref = "analyze:{id}"
+
+execute step（含 {phase} 占位符，args 无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="plan" artifact → id = PLN-xxx, path = scratch/...
+  2. 命中 → args 追加 --dir .workflow/scratch/{path}
+  3. 写 step.source_artifact_ref = "plan:{id}"
 ```
 
-Write enriched args back to status.json.
+兜底：查询无结果 → 不注入，由命令自身 discovery 逻辑处理。已有 `--from` 或 `--dir` 的 step 不覆盖。
+
+**Goal context injection:**
+
+当 step.goal_ref 非空且 session.task_decomposition 存在时：
+```
+goal = session.task_decomposition.find(g => g.id == step.goal_ref)
+if goal:
+  goal_snippet = { id: goal.id, goal: goal.goal, done_when: goal.done_when,
+                   boundary: goal.boundary, evidence: goal.evidence }
+  → 传递给 A_EXEC_STEP 用于 inline execution 前注入（见 step 2 goal context pre-injection）
+```
+
+Write enriched args + source_artifact_ref back to status.json.
 
 ### A_EXEC_DECISION
 
@@ -156,13 +181,24 @@ Write enriched args back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
-3. **Complete**:
+2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+   ```
+   <goal_context>
+   Sub-goal: {goal.id} — {goal.goal}
+   Done when: {goal.done_when}
+   Boundary: {goal.boundary}
+   Evidence target: {goal.evidence}
+   Execution criteria: {session.execution_criteria joined by '; '}
+   </goal_context>
+   ```
+   无 goal_snippet 时跳过此步。goal_context block 不替换 ralph next 的 stdout 内容，仅在其前方拼接。
+3. **Inline execution** — 按 stdout（含 goal_context 前置）执行；deferred_reading 按需 Read
+4. **Complete**:
    - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
    - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
    - `Bash("maestro ralph retry N")`
    - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
-4. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
+5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `$maestro-ralph-execute` 直调自调用。
 
@@ -240,5 +276,10 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。$maestro
 - [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
 - [ ] 只处理 session.platform == "codex" 的会话
+- [ ] --from auto-injection：phase-level plan step 运行时从 state.json 查找同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `source_artifact_ref`
+- [ ] --from auto-injection：phase-level execute step 运行时查找同 phase+milestone 最新 completed plan artifact → 注入 `--dir`，写 `source_artifact_ref`
+- [ ] Goal context injection：step.goal_ref 非空时从 task_decomposition 提取 goal_snippet，A_EXEC_STEP 在 ralph next stdout 顶部前置 `<goal_context>` block
+- [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
+- [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
 
 </appendix>

package/.codex/skills/maestro-roadmap/SKILL.md

@@ -29,6 +29,11 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-roadmap-{slug}/`
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.workflow/roadmap.md`
+
+### Pre-load (runs unconditionally, including -y auto mode)
+1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge for dependency and scope analysis
+3. All optional — proceed without if unavailable (log warning)
 </context>
 
 <interview_protocol>
@@ -176,7 +181,22 @@ Assembly agent produces roadmap.md with Milestone > Phase hierarchy (goal, depen
 3. Generate context.md (summary + analysis findings + roadmap stats)
 4. Write .workflow/roadmap.md with Milestone > Phase hierarchy
 5. Update state.json milestones + current_milestone
-6. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-impeccable build; need formal specs -> maestro-blueprint
+6. **Generate context-package.json** (schema `context-package/1.0`):
+   ```jsonc
+   {
+     "$schema": "context-package/1.0",
+     "source": { "type": "roadmap", "artifact_id": "RDM-{id}", "session_path": "...", "generated_at": "..." },
+     "requirements": [],       // from milestone phase goals → { id, title, acceptance }
+     "constraints": [],         // from scope decisions → locked items
+     "domain": {},              // inherit from upstream --from context-package if loaded
+     "non_goals": [],           // deferred scope items
+     "insights": [],            // from risk analysis and dependency findings
+     "open_questions": [],      // unresolved scope areas
+     "references": [{ "type": "roadmap", "path": "roadmap.md" }]
+   }
+   ```
+   Register `context_package` path in RDM artifact entry so downstream `--from roadmap:ID` can resolve.
+7. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-impeccable build; need formal specs -> maestro-blueprint
 
 </actions>
 
@@ -215,5 +235,14 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] context.md generated
 - [ ] Uncertainty assessed, strategy selected, milestones with phases + success criteria
 - [ ] Artifact registered in state.json with milestone entries
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
+
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
 </output>

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

@@ -413,4 +413,13 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"vulnerability","data":{"location":"s
 - [ ] Issues auto-created for qualifying severity findings
 - [ ] Phase index.json updated with review status
 - [ ] discoveries.ndjson append-only throughout
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
+
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>

package/README.md

@@ -36,7 +36,7 @@ Maestro-Flow is built on two interconnected systems that reinforce each other:
           ┌──────────────┴──────────────┐  ┌──────────────────┴───────────────┐
           │   Workflow Orchestration     │  │      Knowledge System            │
           │                             │  │                                  │
-          │  Intent Router              │  │  Knowledge Graph (SQLite)        │
+          │  Intent Router              │  │  MaestroGraph (SQLite)            │
           │    └─ 40+ chain types       │  │    └─ Code + Knowledge unified   │
           │  Ralph Decision Engine      │  │  Spec Injection (Hooks)          │
           │    └─ 11-state FSM          │  │    └─ Auto-inject into prompts   │
@@ -67,6 +67,8 @@ maestro install
 
 **Prerequisites**: Node.js ≥ 18, Claude Code CLI. Optional: Codex CLI, Gemini CLI for multi-agent workflows.
 
+`maestro install` provides an interactive component selector — choose which assets (commands, hooks, MCP, agents) to install. Use `maestro workspace link` to share knowledge (specs, knowhow, domain) across multiple projects.
+
 ---
 
 ## Quick Start
@@ -95,6 +97,18 @@ Ralph automatically determines where you are (brainstorm → plan → execute
 | `/maestro-quick` | Quick fixes, small features (analyze → plan → execute) |
 | `/maestro-*` | Step-by-step: brainstorm, blueprint, analyze, plan, execute, verify |
 
+### Odyssey — Long-Running Iterative Cycles
+
+Odyssey commands run extended, self-correcting loops that combine archaeology, diagnosis, fix, verification, and knowledge persistence until acceptance criteria are met:
+
+| Command | Focus |
+|---------|-------|
+| `odyssey-debug` | Debug cycle — archaeology, diagnosis, fix, confirmation, generalization |
+| `odyssey-planex` | Requirement-driven cycle — plan, execute, strict verify, fix loop |
+| `odyssey-improve` | Codebase improvement — multi-dimensional audit, targeted fix, verify |
+| `odyssey-review-test-fix` | Deep review + fix — multi-dimensional review, targeted fix, generalization |
+| `odyssey-ui` | UI optimization — visual survey, audit, divergent exploration, fix |
+
 ---
 
 ## Workflow Orchestration
@@ -159,9 +173,9 @@ These patterns compose: a team coordinator can delegate subtasks to different LL
 
 ## Knowledge System
 
-### Knowledge Graph
+### Knowledge Graph (MaestroGraph)
 
-A SQLite-backed unified graph that stores both **code structure** (functions, classes, call chains via tree-sitter extraction) and **project knowledge** (specs, knowhow, domain terms, issues) in one queryable structure.
+**MaestroGraph** is the unified code index engine that replaces the former CodeGraph dependency. Built on `web-tree-sitter` for AST-level extraction, it stores both **code structure** (functions, classes, call chains) and **project knowledge** (specs, knowhow, domain terms, issues) in a single SQLite-backed graph with dual FTS5 indexes.
 
 ```bash
 maestro kg search <symbol>        # Find nodes
@@ -187,6 +201,10 @@ Agent executes task
 
 Four learning tools feed this cycle: `learn-retro` (retrospective), `learn-follow` (pattern study), `learn-decompose` (architecture breakdown), `learn-investigate` (deep dive).
 
+### Domain Knowledge
+
+A semantic glossary layer that defines **what things mean** in your project. Domain terms (`maestro domain`) standardize terminology, map concept relationships, and serve as a MaestroGraph knowledge source — bridging the gap between code-level symbols and business-level concepts.
+
 ### Wiki & Search
 
 WikiIndexer walks the `.workflow/` directory, parses frontmatter, builds backlink graphs, and creates a **BM25 inverted index** for full-text search across all project knowledge — specs, knowhow, issues, and KG nodes as virtual entries.
@@ -225,7 +243,7 @@ Built with React 19, Zustand, Tailwind CSS 4, Framer Motion, Hono, WebSocket.
 
 | Metric | Count |
 |--------|-------|
-| Source files (TypeScript) | 446 |
+| Source files (TypeScript) | 454 |
 | Lines of code | ~111,000 |
 | Slash commands | 64 |
 | Workflow definitions | 115 |
@@ -233,7 +251,7 @@ Built with React 19, Zustand, Tailwind CSS 4, Framer Motion, Hono, WebSocket.
 | Agent definitions | 23 |
 | CLI commands | 32 |
 | Templates | 92 |
-| Guides (bilingual) | 66 |
+| Guides (bilingual) | 67 |
 
 ### Tech Stack
 
@@ -277,6 +295,7 @@ maestro/
 
 **Getting Started**
 - **[Quick Start Guide](guide/quick-start-guide.en.md)** — Install, first workflow, key concepts
+- **[Install Guide](guide/install-guide.md)** — Step-by-step installation, component selection, workspace setup
 - **[Maestro Ralph Guide](guide/maestro-ralph-guide.en.md)** — Adaptive lifecycle engine, decision nodes, quality modes
 
 **Workflow**
@@ -288,6 +307,9 @@ maestro/
 
 **Knowledge**
 - **[Knowledge Management Guide](guide/knowledge-management-guide.en.md)** — KG, specs, knowhow, wiki
+- **[Search System Guide](guide/search-system-guide.md)** — Unified BM25F search, MaestroGraph integration, type filtering
+- **[MaestroGraph Plan](guide/plan-maestrograph.md)** — Unified KG engine design, CodeGraph replacement, tree-sitter integration
+- **[Domain Knowledge Plan](guide/plan-domain-knowledge.md)** — Semantic glossary, term relationships, concept layer
 - **[Spec System Guide](guide/spec-system-guide.en.md)** — Spec entries, keyword loading, validation hooks
 - **[Hooks Guide](guide/hooks-guide.en.md)** — 17 hooks, spec injection, context budget
 - **[Learning Tools Guide](guide/learn-tools-guide.en.md)** — Retro, follow, decompose, investigate
@@ -296,6 +318,7 @@ maestro/
 - **[Delegate Async Guide](guide/delegate-async-guide.en.md)** — Multi-CLI delegation, message injection, chaining
 - **[Overlay Guide](guide/overlay-guide.en.md)** — Non-invasive command extensions
 - **[Worktree Guide](guide/worktree-guide.en.md)** — Milestone-level parallel development
+- **[Workspace Guide](guide/workspace-guide.md)** — Cross-workspace knowledge sharing, link/unlink
 - **[MCP Tools Reference](guide/mcp-tools-guide.en.md)** — All 9 MCP endpoint tools
 - **[Collab Guide](guide/team-lite-guide.en.md)** — 2-8 person team collaboration
 

package/README.zh-CN.md

@@ -36,7 +36,7 @@ Maestro-Flow 建立在两个相互增强的系统之上：
           ┌──────────────┴──────────────┐  ┌──────────────────┴───────────────┐
           │      工作流编排              │  │         知识系统                  │
           │                             │  │                                  │
-          │  意图路由                    │  │  知识图谱 (SQLite)               │
+          │  意图路由                    │  │  MaestroGraph (SQLite)            │
           │    └─ 40+ 链类型            │  │    └─ 代码 + 知识统一存储        │
           │  Ralph 决策引擎             │  │  Spec 注入 (Hooks)               │
           │    └─ 11 状态 FSM           │  │    └─ 自动注入 agent 提示词      │
@@ -66,6 +66,8 @@ maestro install
 
 **前置条件**：Node.js ≥ 18，Claude Code CLI。可选：Codex CLI、Gemini CLI 用于多智能体工作流。
 
+`maestro install` 提供交互式组件选择器 — 可选择安装哪些资产（命令、Hook、MCP、Agent）。使用 `maestro workspace link` 跨多个项目共享知识（spec、knowhow、domain）。
+
 ---
 
 ## 快速开始
@@ -94,6 +96,18 @@ Ralph 自动判断你在哪个阶段（brainstorm → plan → execute → verif
 | `/maestro-quick` | 快速修复、小功能（analyze → plan → execute） |
 | `/maestro-*` | 逐步执行：brainstorm、blueprint、analyze、plan、execute、verify |
 
+### Odyssey — 长周期迭代循环
+
+Odyssey 命令运行扩展的自校正循环，组合考古式分析、诊断、修复、验证和知识持久化，直到满足验收标准：
+
+| 命令 | 聚焦场景 |
+|------|---------|
+| `odyssey-debug` | 调试循环 — 考古分析、诊断、修复、确认、泛化 |
+| `odyssey-planex` | 需求驱动循环 — 计划、执行、严格验证、修复迭代 |
+| `odyssey-improve` | 代码库改进 — 多维审计、定向修复、验证 |
+| `odyssey-review-test-fix` | 深度审查 + 修复 — 多维审查、定向修复、泛化 |
+| `odyssey-ui` | UI 优化 — 视觉巡检、审计、发散探索、修复 |
+
 ---
 
 ## 工作流编排
@@ -158,9 +172,9 @@ Maestro 通过四种可组合的编排模式协调 **Claude Code、Codex、Gemin
 
 ## 知识系统
 
-### 知识图谱
+### 知识图谱（MaestroGraph）
 
-SQLite 支撑的统一图数据库，同时存储**代码结构**（函数、类、调用链，通过 tree-sitter 提取）和**项目知识**（spec、knowhow、领域术语、issue），合并在一个可查询的结构中。
+**MaestroGraph** 是统一的代码索引引擎，替代了原有的 CodeGraph 外部依赖。基于 `web-tree-sitter` 实现 AST 级提取，将**代码结构**（函数、类、调用链）和**项目知识**（spec、knowhow、领域术语、issue）存储在同一个 SQLite 图数据库中，配备双 FTS5 索引。
 
 ```bash
 maestro kg search <symbol>        # 查找节点
@@ -186,6 +200,10 @@ Agent 执行任务
 
 四个学习工具驱动这个循环：`learn-retro`（复盘）、`learn-follow`（模式学习）、`learn-decompose`（架构拆解）、`learn-investigate`（深度探究）。
 
+### 领域知识
+
+语义词汇表层，定义项目中**事物的含义**。Domain 术语（`maestro domain`）标准化命名、映射概念关系，并作为 MaestroGraph 的知识源之一 — 桥接代码级符号与业务级概念。
+
 ### Wiki 与搜索
 
 WikiIndexer 遍历 `.workflow/` 目录，解析 frontmatter，构建反向链接图，并创建 **BM25 倒排索引**用于全文搜索 — 覆盖所有项目知识：spec、knowhow、issue 以及 KG 节点的虚拟条目。
@@ -224,7 +242,7 @@ maestro command-help           # 交互式命令参考（别名: ch）
 
 | 指标 | 数量 |
 |------|------|
-| 源文件 (TypeScript) | 446 |
+| 源文件 (TypeScript) | 454 |
 | 代码行数 | ~111,000 |
 | 斜杠命令 | 64 |
 | 工作流定义 | 115 |
@@ -232,7 +250,7 @@ maestro command-help           # 交互式命令参考（别名: ch）
 | Agent 定义 | 23 |
 | CLI 命令 | 32 |
 | 模板 | 92 |
-| 指南（双语） | 66 |
+| 指南（双语） | 67 |
 
 ### 技术栈
 
@@ -276,6 +294,7 @@ maestro/
 
 **快速入门**
 - **[快速开始指南](guide/quick-start-guide.md)** — 安装、第一个工作流、核心概念
+- **[安装指南](guide/install-guide.md)** — 分步安装、组件选择、工作空间配置
 - **[Maestro Ralph 指南](guide/maestro-ralph-guide.md)** — 自适应生命周期引擎、decision 节点、质量模式
 
 **工作流**
@@ -287,6 +306,9 @@ maestro/
 
 **知识系统**
 - **[知识管理指南](guide/knowledge-management-guide.md)** — KG、spec、knowhow、wiki
+- **[搜索系统指南](guide/search-system-guide.md)** — 统一 BM25F 搜索、MaestroGraph 集成、类型过滤
+- **[MaestroGraph 设计文档](guide/plan-maestrograph.md)** — 统一 KG 引擎设计、CodeGraph 替代、tree-sitter 集成
+- **[领域知识设计文档](guide/plan-domain-knowledge.md)** — 语义词汇表、术语关系、概念层
 - **[Spec 系统指南](guide/spec-system-guide.md)** — spec 条目、关键词加载、验证 Hook
 - **[Hook 系统指南](guide/hooks-guide.md)** — 17 个 Hook、Spec 注入、上下文预算
 - **[学习工具指南](guide/learn-tools-guide.md)** — 复盘、跟读、拆解、探究
@@ -295,6 +317,7 @@ maestro/
 - **[Delegate 异步执行指南](guide/delegate-async-guide.md)** — 多 CLI 委派、消息注入、链式调用
 - **[Overlay 系统指南](guide/overlay-guide.md)** — 非侵入式命令扩展
 - **[Worktree 并行开发指南](guide/worktree-guide.md)** — 里程碑级并行开发
+- **[跨工作空间指南](guide/workspace-guide.md)** — 跨项目知识共享、link/unlink
 - **[MCP 工具参考](guide/mcp-tools-guide.md)** — 全部 9 个 MCP 端点工具
 - **[Collab 协作指南](guide/team-lite-guide.md)** — 2-8 人团队协作
 

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

@@ -0,0 +1,82 @@
+/**
+ * Embedding-based semantic search using @huggingface/transformers (ONNX backend).
+ *
+ * Features:
+ * - Smart device detection: auto-benchmarks CPU vs GPU (DirectML), picks fastest
+ * - Batch inference: processes documents in configurable batch sizes (4-5x faster)
+ * - Incremental indexing: only re-embeds new or changed documents
+ * - Graceful degradation: falls back to pure BM25 when transformers is unavailable
+ */
+export interface EmbeddingIndex {
+    modelId: string;
+    dimension: number;
+    docIds: string[];
+    vectors: Float32Array[];
+    contentHashes?: string[];
+    builtAt: number;
+    deviceUsed?: string;
+    buildTimeMs?: number;
+}
+export interface VectorSearchResult {
+    docId: string;
+    score: number;
+}
+export type DeviceType = 'cpu' | 'gpu';
+export type DtypeType = 'fp32' | 'fp16' | 'q8' | 'q4';
+export interface DeviceConfig {
+    device: DeviceType;
+    dtype: DtypeType;
+    batchSize: number;
+}
+export interface RankedResult {
+    docId: string;
+    score: number;
+}
+export interface RRFSignal {
+    name: string;
+    weight: number;
+    results: RankedResult[];
+}
+export declare function mergeRRFSignals(signals: RRFSignal[], limit: number, k?: number): RankedResult[];
+export declare function mergeRRF(bm25Results: RankedResult[], vectorResults: RankedResult[], limit: number, k?: number, bm25Weight?: number, vectorWeight?: number): RankedResult[];
+/**
+ * Hybrid fusion: RRF for ordering stability + BM25 magnitude for score discrimination.
+ * finalScore = alpha * rrfNorm + (1-alpha) * bm25Norm
+ */
+export declare function mergeHybrid(bm25Results: RankedResult[], vectorResults: RankedResult[], limit: number, options?: {
+    k?: number;
+    alpha?: number;
+    bm25Weight?: number;
+    vectorWeight?: number;
+}): RankedResult[];
+interface BackendInfo {
+    name: string;
+    bundled: boolean;
+}
+export declare function detectDevice(): Promise<DeviceConfig>;
+export declare function getDeviceSummary(): string;
+export interface HardwareInfo {
+    backends: BackendInfo[];
+    gpuAvailable: boolean;
+    selectedDevice: DeviceConfig;
+    reason: string;
+}
+export declare function getHardwareInfo(): Promise<HardwareInfo>;
+export declare const DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
+export declare function isAvailable(): Promise<boolean>;
+export declare function getUnavailableReason(): string | null;
+export declare function embedTexts(texts: string[]): Promise<Float32Array[]>;
+export declare function embedQuery(query: string): Promise<Float32Array>;
+export declare function vectorSearch(queryVector: Float32Array, index: EmbeddingIndex, limit: number): VectorSearchResult[];
+export declare function saveEmbeddingIndex(index: EmbeddingIndex, dir: string): void;
+export declare function loadEmbeddingIndex(dir: string): EmbeddingIndex | null;
+export interface DocForEmbedding {
+    id: string;
+    title: string;
+    summary: string;
+    tags: string[];
+    body?: string;
+}
+export declare function hashDocContent(d: DocForEmbedding): string;
+export declare function buildEmbeddingIndex(docs: DocForEmbedding[], existingIndex?: EmbeddingIndex | null): Promise<EmbeddingIndex>;
+export {};