maestro-flow 0.5.46 → 0.5.47

package/.codex/skills/odyssey-ui/SKILL.md

@@ -40,6 +40,8 @@ $ARGUMENTS
 **Session**: `.workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`
 **Output**: `session.json` | `evidence.ndjson` | `understanding.md`
 
+**Output boundary**: ALL session artifacts MUST target the session directory (`.workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`) or `.workflow/state.json` only. Source code modifications during S_FIX are in-scope but MUST be committed per action. NEVER write session artifacts outside these paths.
+
 **session.json -- ui-specific fields:**
 ```json
 { "target": "", "dimensions": [], "audit_result": null, "diverge_result": null,
@@ -117,6 +119,53 @@ id,title,description,task_type,dimension,deps,wave,status,findings,evidence,erro
 Applies to: **S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE**. Logic in base.
 </self_iteration>
 
+<execution>
+Follow base execution discipline completely. Actions defined in state_machine below.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: INTAKE → SURVEY**
+- REQUIRED: Target resolved, SESSION_DIR created, session.json initialized.
+- REQUIRED: phase_goals[] derived from flags, understanding.md §1 written.
+- BLOCKED if: no target specified (E001) or target path not found (E002).
+
+**GATE 2: SURVEY → AUDIT**
+- REQUIRED: Design system inventory + current state analysis completed.
+- REQUIRED: Evidence phase=survey logged, understanding.md §2 updated, G1 marked done.
+- BLOCKED if: survey incomplete — token scan and styling analysis must both be attempted.
+
+**GATE 3: AUDIT → DIVERGE**
+- REQUIRED: All 6 dimension agents completed (or --dimensions subset), findings merged with severity classification.
+- REQUIRED: audit_result written to session.json, understanding.md §3 with severity matrix, G2 marked done.
+- BLOCKED if: zero dimensions reviewed (W002 partial is allowed, zero is not).
+
+**GATE 4: DIVERGE → FIX**
+- REQUIRED: Both parallel agents (Polish + Delight) completed, ideas consolidated with audit findings.
+- REQUIRED: diverge_result written, understanding.md §4 updated, G3 marked done.
+- BLOCKED if: divergent exploration not attempted.
+
+**GATE 5: FIX → VERIFY**
+- REQUIRED: ALL findings/ideas within fix_threshold fixed by priority tier.
+- REQUIRED: Per-fix evidence phase=fix logged.
+- BLOCKED if: tier incomplete — each tier must be fully addressed before advancing.
+
+**GATE 6: VERIFY → GENERALIZE**
+- REQUIRED: Tests pass (lint, unit, visual regression), delegate verification completed.
+- REQUIRED: confirmation written, understanding.md §5 updated, G4 marked done.
+- BLOCKED if: needs_rework → route back to S_FIX.
+
+**GATE 7: GENERALIZE → DISCOVER**
+- REQUIRED: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged.
+- REQUIRED: generalization_stats written with by_layer entries for all 3 layers, G5 marked done.
+- BLOCKED if: any layer not attempted (thoroughness floor violation).
+
+**GATE 8: DISCOVER → RECORD**
+- REQUIRED: All hits triaged with per-item classification and reason.
+- REQUIRED: remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged, G6 marked done.
+- BLOCKED if: unclassified hits remain.
+
+</execution>
+
 <state_machine>
 
 <states>

package/.codex/skills/quality-auto-test/SKILL.md

@@ -36,6 +36,8 @@ $ARGUMENTS -- phase number and optional flags.
 
 **Session**: `.tests/auto-test/.csv-session/`
 **Output**: scenarios.csv, results.csv, discoveries.ndjson, report.json, state.json, reflection-log.md
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-auto-test-P{N}-{slug}/` or `.workflow/state.json` only. Source code modifications are limited to test files generated by this command. NEVER modify existing production source code.
 </context>
 
 <csv_schema>

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

@@ -84,6 +84,8 @@ When `--yes` or `-y`: Auto-confirm hypothesis selection, skip interactive sympto
 
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
 **Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `understanding.md` (human-readable report)
+
+**Output boundary**: ALL file writes MUST target `DEBUG_DIR` or `.workflow/state.json` only. NEVER modify source code, test files, or other artifacts outside these paths during investigation.
 </context>
 
 <csv_schema>

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

@@ -32,6 +32,8 @@ $quality-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume e
 **Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-refactor-{slug}/`
+
+**Output boundary**: Refactoring modifies source files within the declared scope only. Ancillary outputs (reflection-log.md) MUST target `.workflow/scratch/{YYYYMMDD}-refactor-{slug}/`. NEVER modify files outside the confirmed scope without re-confirmation.
 </context>
 
 <csv_schema>

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

@@ -95,6 +95,8 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 - **test** → uat.md, .tests/ (UAT results, gaps, coverage)
 - Also reads: `.workflow/issues/issues.jsonl`, `.workflow/state.json`
 
+**Output boundary**: ALL file writes MUST target the phase's retrospective directory (`.workflow/scratch/{YYYYMMDD}-retrospective-P{N}/`), `.workflow/state.json`, `.workflow/issues.jsonl`, or `.workflow/specs/` (append-only). NEVER modify source code, verification.json, review.json, plan.json, or other existing artifacts.
+
 ### Agent Registry
 
 | Agent | task_name | fork_turns | Responsibility |

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

@@ -74,6 +74,8 @@ When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive validat
 
 **Output Directory**: `.workflow/.csv-wave/{session-id}/`
 **Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report) + `review.json` (structured review output)
+
+**Output boundary**: ALL file writes MUST target `.workflow/.csv-wave/{session-id}/`, `.workflow/state.json`, or `.workflow/issues/issues.jsonl` only. NEVER modify source code or files outside these paths. Review produces reports only — no source modifications.
 </context>
 
 <csv_schema>

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

@@ -24,10 +24,34 @@ $quality-sync "--since abc123 --dry-run"
 - `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
 - `--dry-run` -- Show what would be updated without writing
 
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/`, `.workflow/state.json`, or `doc-index.json` only. NEVER modify source code or files outside `.workflow/`. `--dry-run` MUST suppress all writes.
 </context>
 
+<invariants>
+1. **Source code is read-only** — sync reads source files to generate documentation. NEVER modify source code, test files, or any non-documentation files.
+2. **Dry-run is side-effect-free** — when `--dry-run` is set, NO file writes occur. Report only what would change.
+3. **Impact trace before refresh** — NEVER regenerate a doc file without first tracing which source changes affect it via doc-index.json. Untargeted full-refresh requires explicit `--full` flag.
+4. **Idempotent sync** — running sync twice with the same diff MUST produce identical results. State.json timestamp prevents redundant re-runs.
+5. **Incremental by default** — without `--full`, only changed components are refreshed. NEVER silently expand to a full rebuild.
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Diff → Impact Trace**
+- REQUIRED: Git diff computed (or --full flag set for all files).
+- BLOCKED if no diff and no --full: nothing to sync (W001).
+
+**GATE 2: Impact Trace → Refresh**
+- REQUIRED: Affected components traced via doc-index.json.
+- BLOCKED if trace fails: cannot refresh docs without impact mapping.
+
+**GATE 3: Refresh → Completion**
+- REQUIRED: `.workflow/codebase/` docs refreshed for affected components.
+- REQUIRED: If `--dry-run` is set, skip state.json write and report what would change. Otherwise, update state.json with sync timestamp.
+- BLOCKED if missing: do not report completion without updated docs.
+
 ### Step 1: Validate
 
 Verify `.workflow/` directory exists — if missing, raise E001.

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

@@ -27,6 +27,8 @@ $ARGUMENTS -- phase number and optional flags.
 - `{target_dir}/.tests/test-results.json` -- pass/fail results
 - `{target_dir}/.tests/coverage-report.json` -- requirement coverage
 - `.tests/.csv-session/diagnosis.csv` + `diagnosis-results.csv`
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-test-P{N}-{slug}/`, `.workflow/state.json`, or `.workflow/issues.jsonl` only. NEVER modify source code or execution artifacts outside these paths.
 </context>
 
 <csv_schema>

package/.codex/skills/security-audit/SKILL.md

@@ -25,10 +25,40 @@ $ARGUMENTS -- Parse tier and scope:
 | quick | Y | Y | -- | -- | -- | -- |
 | standard | Y | Y | Y | Y | -- | -- |
 | deep | Y | Y | Y | Y | Y | Y |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-security-audit-{tier}-{slug}/` or `.workflow/state.json` only. NEVER modify source code, configuration files, or dependencies. Audit is read-only analysis.
 </context>
 
+<invariants>
+1. **Audit is read-only** — NEVER modify source code, configuration, dependencies, or CI/CD files during audit. Security audit produces reports only.
+2. **Findings require file:line evidence** — every finding MUST reference a specific file:line location and include the vulnerable code pattern. No vague or category-only findings.
+3. **Severity NEVER downgraded without justification** — if a finding matches a known OWASP category, its severity follows OWASP guidance. Downgrading requires documented rationale (e.g., compensating control exists).
+4. **Tier coverage is mandatory** — all scan phases required by the selected tier MUST complete. NEVER skip a tier-required phase silently; failures are logged as W00x warnings.
+5. **False positive marking requires evidence** — marking a finding as false positive MUST include the compensating control or code path that prevents exploitation. NEVER dismiss findings without counter-evidence.
+6. **Secrets are never logged** — if secrets are discovered, report their location (file:line) and type but NEVER include the actual secret value in the report output.
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Recon → Scan**
+- REQUIRED: Tech stack detected and entry points identified.
+- REQUIRED: Auth/authz modules listed and data flow mapped.
+- BLOCKED if missing: cannot scan without entry points and data flow baseline.
+
+**GATE 2: Scan → Report** (tier-gated)
+- REQUIRED: OWASP Top 10 scan completed (all tiers).
+- REQUIRED: Dependency audit completed (all tiers).
+- REQUIRED: Secrets + CI/CD scan completed (standard/deep only).
+- REQUIRED: STRIDE + git history completed (deep only).
+- BLOCKED if tier-required scans incomplete: finish all tier-applicable phases before reporting.
+
+**GATE 3: Report → Completion**
+- REQUIRED: Severity matrix produced with file:line references and remediation.
+- REQUIRED: Artifact registered in state.json.
+- BLOCKED if missing: do not emit completion status without severity matrix.
+
 **Phase 1: Reconnaissance**
 
 1. Detect tech stack from package.json / go.mod / requirements.txt / Cargo.toml

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

@@ -45,10 +45,38 @@ $ARGUMENTS — `<category> <title> <content>` where category selects the target
 Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
 
 Category is determined by the first positional argument.
+
+**Output boundary**: ALL file writes MUST target `.workflow/specs/` only. NEVER modify source code or files outside this path.
 </context>
 
+<invariants>
+1. **Idempotent append** — duplicate entry ID MUST be rejected (E003-level check on title + category match before write)
+2. **Category validation** — category MUST be one of: coding, arch, quality, debug, test, review, learning, tools, bug, pattern, decision, rule, validation. Invalid category → E003
+3. **Confirmation gate** — MUST request_user_input before appending entry; NEVER write without user confirmation in interactive mode
+4. **Entry format invariance** — all entries MUST use `<spec-entry>` closed-tag format with id, keywords, and category attributes
+5. **Append-only** — MUST append to target file; NEVER overwrite or truncate existing spec content
+6. **Output boundary** — ALL file writes MUST target `.workflow/specs/` only. NEVER modify source code or files outside this path
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Validate**
+- REQUIRED: Category and content both parsed from arguments.
+- REQUIRED: Category is a valid value.
+- BLOCKED if: E001 (missing args), E003 (invalid category).
+
+**GATE 2: Validate → Format**
+- REQUIRED: `.workflow/specs/` directory exists.
+- REQUIRED: No duplicate entry with identical title + category already present in target file.
+- BLOCKED if: E002 (specs not initialized).
+
+**GATE 3: Format → Write**
+- REQUIRED: `<spec-entry>` block formatted with id, keywords, category attributes.
+- REQUIRED: User confirmation via request_user_input.
+- BLOCKED if: user declines confirmation — abort without writing.
+
 ### Step 1: Parse Input
 
 Extract category (first token), title (second token or quoted string), and content (remainder) from arguments.

package/.codex/skills/spec-load/SKILL.md

@@ -36,10 +36,36 @@ $spec-load "--category review"
 **--category loading**: Loads category's primary doc in full + matching entries from other files.
 
 **Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned.
+
+**Output boundary**: This command produces NO file writes. All output is conversation-context injection only.
 </context>
 
+<invariants>
+1. **Read-only** — NEVER modify, create, or delete any spec files during load. This command is purely a read operation
+2. **Output to context only** — loaded specs are injected into the conversation context; NEVER write loaded content to new files or modify existing files
+3. **Category primary doc** — when --category is specified, the primary category doc MUST be loaded in full before cross-file matching
+4. **Entry-level filtering** — --keyword filtering operates at `<spec-entry>` level via keywords attribute, NOT at file level; unmatched entries in a matching file are excluded
+5. **Graceful degradation** — if `.workflow/specs/` is missing but CLI search is available, fallback to CLI; only fail when both paths are exhausted
+6. **Output boundary** — this command produces NO file writes. All output is conversation-context injection only
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Discover**
+- REQUIRED: Arguments parsed — at least one of --category or --keyword provided, or empty args triggers full load.
+- BLOCKED if: invalid category value.
+
+**GATE 2: Discover → Load**
+- REQUIRED: At least one spec directory exists.
+- BLOCKED if: E001 — `.workflow/specs/` not initialized and no CLI fallback available.
+
+**GATE 3: Load → Display**
+- REQUIRED: Spec files read and entries parsed.
+- REQUIRED: Keyword filtering applied if --keyword was provided.
+- BLOCKED if: no readable spec files found.
+
 ### Step 1: Validate Specs Directory
 
 Verify `.workflow/specs/` exists (E001).

package/.codex/skills/spec-map/SKILL.md

@@ -53,6 +53,7 @@ $spec-map --continue "20260318-map-auth"
 
 **Output**: `.workflow/codebase/` (tech-stack.md, architecture.md, features.md, concerns.md)
 
+**Output boundary**: ALL file writes MUST target `.workflow/codebase/` (output docs) and `.workflow/.csv-wave/{sessionId}/` (session state). NEVER modify source code or files outside these paths.
 </context>
 
 <csv_schema>

package/.codex/skills/spec-remove/SKILL.md

@@ -27,10 +27,38 @@ $ARGUMENTS — entry ID to remove (e.g., `spec-learnings-003`)
 **Flags:**
 - `--cascade` — When the target spec has a `ref` attribute linking to a knowhow document, also delete the referenced knowhow file. Without this flag, removal leaves an orphan knowhow file. Cascade checks the entry's `ref` attribute in the `<spec-entry>` tag.
 - `-y` — Skip confirmation prompt and proceed with removal immediately.
+
+**Output boundary**: File modifications MUST target ONLY the spec container file (.workflow/specs/*.md) and optionally the referenced knowhow file (.workflow/knowhow/*) when --cascade is used. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Confirmation required** — MUST request_user_input before deletion (unless -y flag); NEVER remove entries silently
+2. **Referential integrity** — before removing, check if other spec entries reference the target entry; warn user if references exist
+3. **Cascade explicit** — ref-type entries MUST NOT cascade-delete the linked knowhow file unless --cascade is explicitly passed; default leaves orphan knowhow intact
+4. **Atomic removal** — use `maestro wiki remove-entry` for atomic operation; NEVER manually edit spec files to remove entries
+5. **Index consistency** — wiki index MUST be auto-updated after removal; stale index entries are a hard failure
+6. **Output boundary** — file modifications MUST target ONLY the spec container file (.workflow/specs/*.md) and optionally the referenced knowhow file (.workflow/knowhow/*) when --cascade is used. NEVER modify source code or files outside these paths
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Lookup**
+- REQUIRED: Entry ID parsed from arguments.
+- BLOCKED if: E001 — no entry ID provided.
+
+**GATE 2: Lookup → Confirm**
+- REQUIRED: `.workflow/specs/` directory exists.
+- REQUIRED: Entry found in wiki index as a spec sub-node.
+- REQUIRED: Entry content loaded for user preview.
+- BLOCKED if: E002 (specs not initialized), E003 (entry not found), E004 (wrong type).
+
+**GATE 3: Confirm → Remove**
+- REQUIRED: User confirmed removal via request_user_input (unless -y flag).
+- REQUIRED: If --cascade and entry has ref attribute, user additionally confirmed knowhow file deletion.
+- BLOCKED if: user declines — abort without modification.
+
 ### Step 1: Parse Input
 
 Extract entry ID from arguments.

package/.codex/skills/spec-setup/SKILL.md

@@ -16,10 +16,38 @@ $spec-setup
 
 <context>
 No arguments. Scans the codebase and generates spec files in `.workflow/specs/`.
+
+**Output boundary**: ALL file writes MUST target `.workflow/specs/` (spec files) and `.workflow/knowhow/` (recipe knowhow) only. NEVER modify source code, `.workflow/state.json`, or files outside these paths.
 </context>
 
+<invariants>
+1. **Non-destructive** — NEVER overwrite existing spec files; if a file already exists, skip it and report as already-initialized
+2. **Idempotent** — safe to re-run on an initialized project; re-running MUST NOT duplicate entries or corrupt existing content
+3. **Core files mandatory** — coding-conventions.md, architecture-constraints.md, and learnings.md MUST always be created (unless they already exist)
+4. **Signal-driven optionals** — optional spec files (quality-rules.md, test-conventions.md) MUST only be created when corresponding framework/tool signals are detected in the codebase; NEVER create optional files without evidence
+5. **Output boundary** — ALL file writes MUST target `.workflow/specs/` and `.workflow/knowhow/` only. NEVER modify source code or files outside these paths
+6. **Confirmation gate** — MUST present all files to be created before writing; NEVER write without user awareness
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Precondition → Scan**
+- REQUIRED: `.workflow/` directory exists.
+- REQUIRED: Project contains source files to scan.
+- BLOCKED if: E001 (`.workflow/` not initialized), E002 (no source files).
+
+**GATE 2: Scan → Generate**
+- REQUIRED: Codebase scan completed — framework, language, and tooling signals collected.
+- REQUIRED: Core spec file list determined (always 3: coding-conventions, architecture-constraints, learnings).
+- REQUIRED: Optional spec files determined by detected signals only.
+
+**GATE 3: Generate → Report**
+- REQUIRED: All planned files written to `.workflow/specs/`.
+- REQUIRED: Existing files skipped (not overwritten).
+- BLOCKED if: filesystem write errors.
+
 ### Step 1: Validate Preconditions
 
 Verify `.workflow/` exists (E001) and project contains source files (E002).

package/.codex/skills/wiki-connect/SKILL.md

@@ -21,8 +21,19 @@ $ARGUMENTS — optional flags.
 - `--max N` — Max suggestions (default: 20)
 
 **Output**: `.workflow/knowhow/KNW-wiki-connections-{date}.md`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/` (connection report) and `.workflow/specs/learnings.md` (graph insights). Wiki entry `related` field updates via `maestro wiki update` only. NEVER modify source code or files outside these paths.
 </context>
 
+<invariants>
+1. **Read-only analysis** — wiki entries are analyzed but NEVER modified during Stages 1-4; only Stage 5 (--fix) updates entries via CLI
+2. **Fix requires confirmation** — MUST request_user_input before applying link changes; NEVER auto-apply without user consent (unless both --fix and -y)
+3. **Bidirectional links** — when adding A→B, MUST also add B→A; unidirectional links are the problem this command solves
+4. **Scoring threshold** — candidates below --min-similarity MUST be filtered out; NEVER present sub-threshold suggestions
+5. **Append-only insights** — graph insights appended to specs/learnings.md; NEVER overwrite existing entries
+6. **Output boundary** — file writes limited to `.workflow/knowhow/` and `.workflow/specs/learnings.md`. Wiki updates via `maestro wiki update` CLI only
+</invariants>
+
 <execution>
 
 ### Stage 1: Load Wiki State

package/.codex/skills/wiki-digest/SKILL.md

@@ -27,8 +27,19 @@ $ARGUMENTS — scope and optional flags.
 - `--create-issues` — Auto-create knowledge-gap issues in issues.jsonl
 
 **Output**: `.workflow/knowhow/digest-{slug}-{date}.md`
+
+**Output boundary**: ALL file writes MUST target `.workflow/knowhow/` (digest document) and `.workflow/specs/learnings.md` (meta-insights). Issue creation targets `.workflow/issues/issues.jsonl` only when --create-issues is set. NEVER modify source code or wiki entries.
 </context>
 
+<invariants>
+1. **Read-only analysis** — wiki entries and source code are read but NEVER modified; this is a synthesis command
+2. **Issue dedup** — when --create-issues is set, MUST dedup against existing issues.jsonl before creating; NEVER create duplicate knowledge-gap issues
+3. **Confirmation for issues** — MUST request_user_input before creating issues; NEVER auto-create issues without user consent (unless both --create-issues and -y)
+4. **Theme minimum** — MUST cluster into 3-5 themes; fewer than 3 entries triggers W001 warning, not an error
+5. **Append-only insights** — meta-insights appended to specs/learnings.md; NEVER overwrite existing entries
+6. **Output boundary** — file writes limited to `.workflow/knowhow/` (digest), `.workflow/specs/learnings.md` (insights), and `.workflow/issues/issues.jsonl` (gap issues). NEVER modify source code or wiki entries
+</invariants>
+
 <execution>
 
 ### Stage 1: Scope & Load

package/dashboard/dist-server/dashboard/src/server/agents/api-explore-adapter.js

@@ -6,8 +6,10 @@
 // is inherited from StreamJsonAdapter. We only override argument building
 // and environment mapping.
 // ---------------------------------------------------------------------------
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { StreamJsonAdapter } from './stream-json-adapter.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
 function resolveAgentScript() {
     const distRoot = join(__dirname, '..', '..', '..', '..', 'dist', 'src', 'agents', 'api-explore', 'index.js');
     return `node "${distRoot}"`;

package/dashboard/dist-server/dashboard/src/server/agents/api-explore-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-explore-adapter.js","sourceRoot":"","sources":["../../../../../src/server/agents/api-explore-adapter.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,2BAA2B;AAC3B,8EAA8E;AAE9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,SAAS,kBAAkB;IACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;IAC7G,OAAO,SAAS,QAAQ,GAAG,CAAC;AAC9B,CAAC;AAED,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IACtD;QACE,KAAK,CAAC,kBAAkB,EAAE,EAAE,aAA0B,CAAC,CAAC;IAC1D,CAAC;IAEkB,SAAS,CAAC,MAAmB;QAC9C,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"api-explore-adapter.js","sourceRoot":"","sources":["../../../../../src/server/agents/api-explore-adapter.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,2BAA2B;AAC3B,8EAA8E;AAE9E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,kBAAkB;IACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;IAC7G,OAAO,SAAS,QAAQ,GAAG,CAAC;AAC9B,CAAC;AAED,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IACtD;QACE,KAAK,CAAC,kBAAkB,EAAE,EAAE,aAA0B,CAAC,CAAC;IAC1D,CAAC;IAEkB,SAAS,CAAC,MAAmB;QAC9C,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

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

@@ -77,6 +77,11 @@ export interface HardwareInfo {
 export declare function getHardwareInfo(): Promise<HardwareInfo>;
 export declare function getModelId(): string;
 export declare const DEFAULT_MODEL_ID = "Xenova/multilingual-e5-small";
+/**
+ * Check if the local ONNX model is already downloaded in the HuggingFace cache.
+ * Returns true for API mode (no local model needed).
+ */
+export declare function isModelCached(): boolean;
 export type ModelProgressCallback = (info: {
     status: string;
     file?: string;

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

@@ -10,7 +10,7 @@
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync, readdirSync } from 'node:fs';
 let _zvecModule;
 async function getZvec() {
     if (_zvecModule !== undefined)
@@ -330,6 +330,30 @@ export function getModelId() {
     return apiConf ? apiConf.model : DEFAULT_LOCAL_MODEL;
 }
 export const DEFAULT_MODEL_ID = DEFAULT_LOCAL_MODEL;
+/**
+ * Check if the local ONNX model is already downloaded in the HuggingFace cache.
+ * Returns true for API mode (no local model needed).
+ */
+export function isModelCached() {
+    if (isApiMode())
+        return true;
+    const cacheKey = DEFAULT_LOCAL_MODEL.replace('/', '--');
+    const hfHome = process.env.HF_HOME || join(homedir(), '.cache', 'huggingface');
+    for (const base of [hfHome, join(hfHome, 'hub')]) {
+        const snapshotsDir = join(base, `models--${cacheKey}`, 'snapshots');
+        if (!existsSync(snapshotsDir))
+            continue;
+        try {
+            const snapshots = readdirSync(snapshotsDir);
+            for (const snap of snapshots) {
+                if (existsSync(join(snapshotsDir, snap, 'onnx', 'model.onnx')))
+                    return true;
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return false;
+}
 const CACHE_FILE = 'embedding-index.json';
 let _pipeline = null;
 let _available = null;