akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/output/text.js

@@ -38,6 +38,13 @@ export function formatPlain(command, result, detail) {
         case "index": {
             const indexResult = result;
             let out = `Indexed ${indexResult.totalEntries ?? 0} entries from ${indexResult.directoriesScanned ?? 0} directories (mode: ${indexResult.mode ?? "unknown"})`;
+            const graphQuality = indexResult.graphQuality;
+            if (graphQuality) {
+                const coverage = typeof graphQuality.extractionCoverage === "number"
+                    ? `${Math.round(graphQuality.extractionCoverage * 100)}%`
+                    : "n/a";
+                out += `\nGraph quality: entities ${graphQuality.entityCount ?? 0}, relations ${graphQuality.relationCount ?? 0}, coverage ${coverage}, density ${graphQuality.density ?? 0}`;
+            }
             const warnings = indexResult.warnings;
             if (Array.isArray(warnings) && warnings.length > 0) {
                 out += `\nWarnings (${warnings.length}):`;
@@ -221,6 +228,31 @@ export function formatPlain(command, result, detail) {
         case "distill": {
             return formatDistillPlain(r);
         }
+        case "graph-summary":
+            return formatGraphSummaryPlain(r);
+        case "graph-entities":
+            return formatGraphEntitiesPlain(r);
+        case "graph-relations":
+            return formatGraphRelationsPlain(r);
+        case "graph-related":
+            return formatGraphRelatedPlain(r);
+        case "graph-export":
+            return formatGraphExportPlain(r);
+        case "improve": {
+            return formatImprovePlain(r);
+        }
+        case "consolidate": {
+            return formatConsolidatePlain(r);
+        }
+        // Output shape registration for `akm agent <profile>` (#agent-dispatch).
+        // In interactive mode stdout/stderr are empty (they went to the TTY), so
+        // we print only the profile name and exit status. In captured mode we
+        // emit stdout first, then stderr, then the exit code summary.
+        case "agent-result": {
+            return formatAgentResultPlain(r);
+        }
+        case "health":
+            return formatHealthPlain(r);
         case "info":
             return formatInfoPlain(r);
         case "config":
@@ -249,7 +281,7 @@ export function formatPlain(command, result, detail) {
         case "vault-list":
             return formatVaultListPlain(r);
         case "vault-create":
-            return `Created vault ${String(r.ref ?? "?")} at ${String(r.path ?? "?")}`;
+            return `Created vault ${String(r.ref ?? "?")}`;
         case "vault-set":
             return `Set ${String(r.key ?? "?")} in ${String(r.ref ?? "?")} (value not displayed)`;
         case "vault-unset": {
@@ -299,6 +331,50 @@ export function formatInfoPlain(r) {
         return JSON.stringify(r, null, 2);
     return lines.join("\n");
 }
+export function formatHealthPlain(r) {
+    const lines = [];
+    lines.push(`health: ${String(r.status ?? "unknown")}`);
+    if (typeof r.since === "string")
+        lines.push(`since: ${r.since}`);
+    const metrics = typeof r.metrics === "object" && r.metrics !== null ? r.metrics : undefined;
+    if (metrics) {
+        lines.push("metrics:");
+        lines.push(`  taskFailRate: ${String(metrics.taskFailRate ?? 0)}`);
+        lines.push(`  agentFailureRate: ${String(metrics.agentFailureRate ?? 0)}`);
+        lines.push(`  stuckActiveRuns: ${String(metrics.stuckActiveRuns ?? 0)}`);
+        lines.push(`  logBackingRate: ${String(metrics.logBackingRate ?? 0)}`);
+        lines.push(`  probeRoundTripMs: ${String(metrics.probeRoundTripMs ?? "null")}`);
+    }
+    const improve = typeof r.improve === "object" && r.improve !== null ? r.improve : undefined;
+    if (improve) {
+        const actions = typeof improve.actions === "object" && improve.actions !== null
+            ? improve.actions
+            : {};
+        lines.push("improve:");
+        lines.push(`  invoked: ${String(improve.invoked ?? 0)}`);
+        lines.push(`  completed: ${String(improve.completed ?? 0)}`);
+        lines.push(`  skipped: ${String(improve.skipped ?? 0)}`);
+        lines.push(`  plannedRefs: ${String(improve.plannedRefs ?? 0)}`);
+        lines.push(`  actions: reflect=${String(actions.reflect ?? 0)} distill=${String(actions.distill ?? 0)} distillSkipped=${String(actions.distillSkipped ?? 0)} memoryPrune=${String(actions.memoryPrune ?? 0)} memoryInference=${String(actions.memoryInference ?? 0)} graphExtraction=${String(actions.graphExtraction ?? 0)} error=${String(actions.error ?? 0)}`);
+        lines.push(`  coverageGapCount: ${String(improve.coverageGapCount ?? 0)}`);
+        lines.push(`  executionLogCandidateCount: ${String(improve.executionLogCandidateCount ?? 0)}`);
+        lines.push(`  deadUrlCount: ${String(improve.deadUrlCount ?? 0)}`);
+    }
+    const sections = [
+        ["hardChecks", r.hardChecks],
+        ["advisories", r.advisories],
+    ];
+    for (const [label, value] of sections) {
+        const checks = Array.isArray(value) ? value : [];
+        if (checks.length === 0)
+            continue;
+        lines.push(`${label}:`);
+        for (const check of checks) {
+            lines.push(`  - [${String(check.status ?? "unknown")}] ${String(check.name ?? "check")}: ${String(check.message ?? "")}`);
+        }
+    }
+    return lines.join("\n");
+}
 export function formatConfigPlain(r) {
     // Recursive flattener: prints `key=value` lines, and nested objects as
     // `parent.child=value`. Arrays render as JSON for compactness.
@@ -404,22 +480,7 @@ export function formatRegistryBuildIndexPlain(r) {
     return `Wrote registry index ${version} (${total} kits) → ${outPath}`.replace(/\s+/g, " ").trim();
 }
 export function formatVaultListPlain(r) {
-    // Single-vault listing: { ref, path, entries: [{ key, comment? }, ...] }
-    if (typeof r.ref === "string" && Array.isArray(r.entries)) {
-        const ref = r.ref;
-        const entries = r.entries;
-        if (entries.length === 0) {
-            return `No keys in ${ref}. Set one with \`akm vault set ${ref} KEY=VALUE\`.`;
-        }
-        const lines = [ref];
-        for (const e of entries) {
-            const key = String(e.key ?? "?");
-            const comment = typeof e.comment === "string" && e.comment ? `  # ${e.comment}` : "";
-            lines.push(`  ${key}${comment}`);
-        }
-        return lines.join("\n");
-    }
-    // Multi-vault listing: { vaults: [{ ref, path, keyCount }, ...] }
+    // Multi-vault listing: { vaults: [{ ref, path, keys }, ...] }
     const vaults = Array.isArray(r.vaults) ? r.vaults : [];
     if (vaults.length === 0) {
         return "No vaults. Create one with `akm vault create <name>` then `akm vault set vault:<name> KEY=VALUE`.";
@@ -427,8 +488,17 @@ export function formatVaultListPlain(r) {
     const lines = [];
     for (const v of vaults) {
         const ref = String(v.ref ?? "?");
-        const keyCount = typeof v.keyCount === "number" ? v.keyCount : 0;
-        lines.push(`${ref}\t${keyCount} key(s)`);
+        const keys = Array.isArray(v.keys) ? v.keys.map(String) : [];
+        if (lines.length > 0)
+            lines.push("");
+        lines.push(`## ${ref}`);
+        if (keys.length === 0) {
+            lines.push("- (no keys)");
+            continue;
+        }
+        for (const key of keys) {
+            lines.push(`- ${key}`);
+        }
     }
     return lines.join("\n");
 }
@@ -446,6 +516,57 @@ export function formatWorkflowValidatePlain(r) {
     const stepCount = typeof r.stepCount === "number" ? r.stepCount : 0;
     return `workflow validate: ok — ${title || pathValue} (${stepCount} step(s))`;
 }
+export function formatGraphSummaryPlain(r) {
+    const lines = [
+        `Graph: ${String(r.graphPath ?? "?")}`,
+        `Generated: ${String(r.generatedAt ?? "?")}`,
+        `Files: ${String(r.fileCount ?? 0)}  Entities: ${String(r.entityCount ?? 0)}  Relations: ${String(r.relationCount ?? 0)}`,
+    ];
+    const quality = r.quality;
+    if (quality) {
+        const coverage = typeof quality.extractionCoverage === "number" ? `${Math.round(quality.extractionCoverage * 100)}%` : "n/a";
+        lines.push(`Coverage: ${coverage}  Density: ${String(quality.density ?? 0)}`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphEntitiesPlain(r) {
+    const entities = Array.isArray(r.entities) ? r.entities : [];
+    if (entities.length === 0)
+        return "No entities found in graph.";
+    const lines = [`Entities (${String(r.total ?? entities.length)} total):`];
+    for (const entity of entities) {
+        lines.push(`- ${String(entity.name ?? "?")} (${String(entity.fileCount ?? 0)} files)`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphRelationsPlain(r) {
+    const relations = Array.isArray(r.relations) ? r.relations : [];
+    if (relations.length === 0)
+        return "No relations found in graph.";
+    const lines = [`Relations (${String(r.total ?? relations.length)} total):`];
+    for (const relation of relations) {
+        const type = relation.type ? ` [${String(relation.type)}]` : "";
+        lines.push(`- ${String(relation.from ?? "?")} -> ${String(relation.to ?? "?")}${type} x${String(relation.count ?? 0)}`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphRelatedPlain(r) {
+    const related = Array.isArray(r.related) ? r.related : [];
+    if (related.length === 0)
+        return String(r.tip ?? "No related graph neighbors were found.");
+    const lines = [`Related (${String(r.total ?? related.length)} total) for ${String(r.ref ?? "?")}:`];
+    for (const hit of related) {
+        const shared = Array.isArray(hit.sharedEntities) ? hit.sharedEntities.map(String).join(", ") : "";
+        lines.push(`- ${String(hit.type ?? "?")}: ${formatRelatedLabel(hit)}`);
+        if (shared)
+            lines.push(`  shared: ${shared}`);
+        lines.push(`  relationCount: ${String(hit.relationCount ?? 0)}`);
+    }
+    return lines.join("\n");
+}
+export function formatGraphExportPlain(r) {
+    return `Exported graph (${String(r.format ?? "json")}, ${String(r.bytes ?? 0)} bytes) to ${String(r.outPath ?? "?")}`;
+}
 export function formatProposalProducerPlain(command, r) {
     if (r.ok === false) {
         const reason = String(r.reason ?? "unknown");
@@ -470,7 +591,7 @@ export function formatProposalListPlain(r) {
     const proposals = Array.isArray(r.proposals) ? r.proposals : [];
     const total = typeof r.totalCount === "number" ? r.totalCount : proposals.length;
     if (proposals.length === 0) {
-        return `${total} proposal(s).\nNo proposals.\nGenerate one with \`akm reflect <ref>\`, \`akm propose <type> <name> --task ...\`, or \`akm distill <ref>\`.`;
+        return `${total} proposal(s).\nNo proposals.\nGenerate one with \`akm improve\`, \`akm propose <type> <name> --task ...\`, or \`akm improve <ref>\`.`;
     }
     const lines = [`${total} proposal(s)`, ""];
     for (const p of proposals) {
@@ -535,7 +656,7 @@ export function formatDistillPlain(r) {
     const lessonRef = String(r.lessonRef ?? "?");
     if (outcome === "queued") {
         const id = String(r.proposalId ?? "?");
-        return `Distilled ${inputRef} → proposal ${id} (${lessonRef}). Run \`akm proposal show ${id}\` to review.`;
+        return `Distilled ${inputRef} → proposal ${id} (${lessonRef}). Run \`akm show proposal ${id}\` to review.`;
     }
     if (outcome === "validation_failed") {
         const findings = Array.isArray(r.findings) ? r.findings : [];
@@ -549,6 +670,50 @@ export function formatDistillPlain(r) {
     const message = typeof r.message === "string" ? r.message : "feature disabled or LLM unavailable";
     return `Distill skipped for ${inputRef}: ${message}`;
 }
+export function formatConsolidatePlain(r) {
+    const processed = typeof r.processed === "number" ? r.processed : 0;
+    const merged = typeof r.merged === "number" ? r.merged : 0;
+    const deleted = typeof r.deleted === "number" ? r.deleted : 0;
+    const promoted = Array.isArray(r.promoted) ? r.promoted.length : 0;
+    const warnings = Array.isArray(r.warnings) ? r.warnings : [];
+    const lines = [];
+    if (r.dryRun === true) {
+        lines.push(`[consolidate] dry-run: ${processed} memories found, no AI call`);
+    }
+    else if (r.previewOnly === true) {
+        lines.push(`[consolidate] preview: processed=${processed}`);
+        const planned = Array.isArray(r.planned) ? r.planned : [];
+        for (const op of planned) {
+            if (op.op === "merge") {
+                lines.push(`  merge: ${String(op.primary)} ← ${String(Array.isArray(op.secondaries) ? op.secondaries.join(", ") : "")}`);
+            }
+            else if (op.op === "delete") {
+                lines.push(`  delete: ${String(op.ref)} (${String(op.reason ?? "")})`);
+            }
+            else if (op.op === "promote") {
+                lines.push(`  promote: ${String(op.ref)} → ${String(op.knowledgeRef)}`);
+            }
+        }
+    }
+    else {
+        lines.push(`[consolidate] processed=${processed} merged=${merged} deleted=${deleted} promoted=${promoted}`);
+    }
+    for (const w of warnings) {
+        lines.push(`  warning: ${w}`);
+    }
+    return lines.join("\n");
+}
+export function formatImprovePlain(r) {
+    const scope = r.scope ?? {};
+    const mode = String(scope.mode ?? "all");
+    const value = typeof scope.value === "string" ? ` ${scope.value}` : "";
+    const plannedRefs = Array.isArray(r.plannedRefs) ? r.plannedRefs.length : 0;
+    if (r.dryRun === true) {
+        return `Improve dry-run:${mode === "all" ? " all assets" : value} (${plannedRefs} planned ref(s))`;
+    }
+    const actions = Array.isArray(r.actions) ? r.actions.length : 0;
+    return `Improve:${mode === "all" ? " all assets" : value} queued ${actions} action(s) across ${plannedRefs} ref(s)`;
+}
 export function formatProposalDiffPlain(r) {
     const header = r.isNew
         ? `# proposal ${String(r.id ?? "?")} (new asset: ${String(r.ref ?? "?")})`
@@ -558,18 +723,25 @@ export function formatProposalDiffPlain(r) {
         return `${header}\n(no changes)`;
     return `${header}\n${unified}`;
 }
-export function formatEventsPlain(r) {
-    const events = Array.isArray(r.events) ? r.events : [];
-    const headerParts = [];
+/**
+ * Build the summary header line shared by formatEventsPlain and formatHistoryPlain.
+ * Accumulates ref/type/since label parts then appends the count label.
+ */
+function buildEventHeader(r, countLabel, totalCount) {
+    const parts = [];
     if (typeof r.ref === "string" && r.ref)
-        headerParts.push(`ref: ${r.ref}`);
+        parts.push(`ref: ${r.ref}`);
     if (typeof r.type === "string" && r.type)
-        headerParts.push(`type: ${r.type}`);
+        parts.push(`type: ${r.type}`);
     if (typeof r.since === "string" && r.since)
-        headerParts.push(`since: ${r.since}`);
+        parts.push(`since: ${r.since}`);
+    parts.push(`${totalCount} ${countLabel}`);
+    return parts.join("  ");
+}
+export function formatEventsPlain(r) {
+    const events = Array.isArray(r.events) ? r.events : [];
     const totalCount = typeof r.totalCount === "number" ? r.totalCount : events.length;
-    headerParts.push(`${totalCount} event(s)`);
-    const header = headerParts.join("  ");
+    const header = buildEventHeader(r, "event(s)", totalCount);
     if (events.length === 0) {
         return `${header}\nNo events.`;
     }
@@ -592,13 +764,8 @@ export function formatEventLine(event) {
 }
 export function formatHistoryPlain(r) {
     const entries = Array.isArray(r.entries) ? r.entries : [];
-    const headerParts = [];
-    if (typeof r.ref === "string" && r.ref)
-        headerParts.push(`ref: ${r.ref}`);
-    if (typeof r.since === "string" && r.since)
-        headerParts.push(`since: ${r.since}`);
     const totalCount = typeof r.totalCount === "number" ? r.totalCount : entries.length;
-    headerParts.push(`${totalCount} event(s)`);
+    const headerParts = [buildEventHeader(r, "event(s)", totalCount)];
     // Show active event sources so operators know which streams were consulted.
     if (Array.isArray(r.sources) && r.sources.length > 0) {
         headerParts.push(`sources: ${r.sources.join(", ")}`);
@@ -676,6 +843,19 @@ function formatShowPlain(r, detail) {
         if (r.schemaVersion !== undefined)
             lines.push(`schemaVersion: ${String(r.schemaVersion)}`);
     }
+    const related = typeof r.related === "object" && r.related !== null ? r.related : undefined;
+    const relatedHits = related && Array.isArray(related.hits) ? related.hits : [];
+    if (related) {
+        lines.push("");
+        lines.push(`related: ${String(related.total ?? relatedHits.length)}`);
+        for (const hit of relatedHits) {
+            lines.push(`  - ${String(hit.type ?? "?")}: ${formatRelatedLabel(hit)}`);
+            const shared = Array.isArray(hit.sharedEntities) ? hit.sharedEntities.map(String) : [];
+            if (shared.length > 0)
+                lines.push(`    shared: ${shared.join(", ")}`);
+            lines.push(`    relationCount: ${String(hit.relationCount ?? 0)}`);
+        }
+    }
     const payloads = [r.content, r.template, r.prompt].filter((value) => value != null).map(String);
     if (Array.isArray(r.steps) && r.steps.length > 0) {
         if (lines.length > 0)
@@ -792,10 +972,17 @@ function isCommandOutputSkill(lines) {
     const yamlCount = codeLines.filter((l) => yamlPattern.test(l)).length;
     return cliCount > yamlCount && cliCount > 0;
 }
+function formatRelatedLabel(hit) {
+    const ref = typeof hit.ref === "string" ? hit.ref : undefined;
+    if (ref)
+        return ref;
+    const pathValue = typeof hit.path === "string" ? hit.path : "?";
+    return pathValue.split("/").pop() ?? pathValue;
+}
 export function formatWorkflowListPlain(result) {
     const runs = Array.isArray(result.runs) ? result.runs : [];
     if (runs.length === 0) {
-        return "No workflow runs. Start one with `akm workflow next workflow:<name>` or author one with `akm workflow create <name>`.";
+        return "No workflow runs in the current working scope. Start one with `akm workflow next workflow:<name>` or author one with `akm workflow create <name>`.";
     }
     return runs
         .map((run) => {
@@ -906,6 +1093,8 @@ export function formatSearchPlain(r, detail) {
             lines.push(`  ref: ${String(hit.ref)}`);
         if (hit.origin !== undefined)
             lines.push(`  origin: ${String(hit.origin)}`);
+        if (Array.isArray(hit.keys) && hit.keys.length > 0)
+            lines.push(`  keys: ${hit.keys.join(", ")}`);
         if (hit.size)
             lines.push(`  size: ${String(hit.size)}`);
         if (hit.action)
@@ -922,6 +1111,24 @@ export function formatSearchPlain(r, detail) {
         if (Array.isArray(hit.warnings) && hit.warnings.length > 0) {
             lines.push(`  warnings: ${hit.warnings.join("; ")}`);
         }
+        const graph = typeof hit.graph === "object" && hit.graph !== null ? hit.graph : undefined;
+        if (graph) {
+            const entities = Array.isArray(graph.entities) ? graph.entities : [];
+            if (entities.length > 0) {
+                const matched = entities
+                    .filter((entity) => String(entity.kind ?? "") === "matched")
+                    .map((entity) => String(entity.name ?? "?"));
+                const neighbors = entities
+                    .filter((entity) => String(entity.kind ?? "") !== "matched")
+                    .map((entity) => String(entity.name ?? "?"));
+                lines.push(`  graph: ${[
+                    matched.length > 0 ? `query match=${matched.join(", ")}` : undefined,
+                    neighbors.length > 0 ? `neighbors=${neighbors.join(", ")}` : undefined,
+                ]
+                    .filter(Boolean)
+                    .join("; ")}`);
+            }
+        }
         if (detail === "full") {
             if (hit.path)
                 lines.push(`  path: ${String(hit.path)}`);
@@ -1088,6 +1295,9 @@ export function formatCuratePlain(r, detail) {
             lines.push(`  ref: ${String(item.ref)}`);
         if (item.id)
             lines.push(`  id: ${String(item.id)}`);
+        if (Array.isArray(item.keys) && item.keys.length > 0) {
+            lines.push(`  keys: ${item.keys.join(", ")}`);
+        }
         if (Array.isArray(item.parameters) && item.parameters.length > 0) {
             lines.push(`  parameters: ${item.parameters.join(", ")}`);
         }
@@ -1114,3 +1324,31 @@ export function formatCuratePlain(r, detail) {
     lines.push("To search further: akm search '<query>'");
     return lines.join("\n");
 }
+/**
+ * Render the result of `akm agent <profile>`.
+ *
+ * Interactive mode: stdout and stderr are empty (output went to the TTY).
+ * Print only the profile name and exit code so the caller knows the agent
+ * finished.
+ *
+ * Captured mode: emit stdout (if non-empty), then stderr (if non-empty),
+ * then the profile/exit-code summary line.
+ */
+export function formatAgentResultPlain(r) {
+    const profile = String(r.profileName ?? "agent");
+    const exitCode = r.exitCode !== undefined && r.exitCode !== null ? Number(r.exitCode) : 0;
+    const stdout = typeof r.stdout === "string" ? r.stdout : "";
+    const stderr = typeof r.stderr === "string" ? r.stderr : "";
+    // Interactive mode: both streams are empty.
+    if (!stdout && !stderr) {
+        return `[${profile}] agent exited with code ${exitCode}`;
+    }
+    // Captured mode: stream content + summary.
+    const parts = [];
+    if (stdout)
+        parts.push(stdout.trimEnd());
+    if (stderr)
+        parts.push(stderr.trimEnd());
+    parts.push(`[${profile}] agent exited with code ${exitCode}`);
+    return parts.join("\n");
+}

package/dist/registry/providers/skills-sh.js

@@ -1,13 +1,9 @@
-import fs from "node:fs";
-import path from "node:path";
 import { fetchWithRetry } from "../../core/common";
-import { getRegistryIndexCacheDir } from "../../core/paths";
+import { closeDatabase, getRegistryIndexCache, openDatabase, upsertRegistryIndexCache } from "../../indexer/db";
 import { registerProvider } from "../factory";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Per-query cache TTL in milliseconds (15 minutes). */
 const QUERY_CACHE_TTL_MS = 15 * 60 * 1000;
-/** Maximum age before query cache is considered stale but still usable (1 day). */
-const QUERY_CACHE_STALE_MS = 24 * 60 * 60 * 1000;
 // ── Provider class ──────────────────────────────────────────────────────────
 class SkillsShProvider {
     type = "skills-sh";
@@ -89,13 +85,33 @@ class SkillsShProvider {
         return ref.source === "github";
     }
     async fetchSkills(query, limit) {
-        // Check per-query cache first
-        const cachePath = this.queryCachePath(query, limit);
-        const cached = this.readQueryCache(cachePath);
-        if (cached && !isExpired(cached.mtime, QUERY_CACHE_TTL_MS)) {
-            return cached.entries;
+        // Build a stable DB cache key for this query
+        const dbCacheKey = this.queryDbCacheKey(query, limit);
+        // ── Step 1: Try DB cache (index.db) ───────────────────────────────────
+        let db;
+        let dbCacheResult;
+        try {
+            db = openDatabase();
+            dbCacheResult = getRegistryIndexCache(db, dbCacheKey, QUERY_CACHE_TTL_MS);
+        }
+        catch {
+            // index.db not available yet (pre-migration install or test env) — fall through
+        }
+        if (dbCacheResult) {
+            try {
+                const parsed = JSON.parse(dbCacheResult.indexJson);
+                if (Array.isArray(parsed)) {
+                    const entries = parsed.filter(isValidSkillsEntry);
+                    if (db)
+                        closeDatabase(db);
+                    return entries;
+                }
+            }
+            catch {
+                /* corrupt DB entry — fall through */
+            }
         }
-        // Fetch from API
+        // ── Step 2: Fetch from API ─────────────────────────────────────────────
         const baseUrl = this.config.url.replace(/\/+$/, "");
         const url = `${baseUrl}/api/search?q=${encodeURIComponent(query)}&limit=${limit}`;
         try {
@@ -105,13 +121,40 @@ class SkillsShProvider {
             }
             const data = (await response.json());
             const entries = parseSkillsResponse(data);
-            this.writeQueryCache(cachePath, entries);
+            // Write to DB cache (primary)
+            if (db) {
+                try {
+                    upsertRegistryIndexCache(db, dbCacheKey, JSON.stringify(entries));
+                }
+                catch {
+                    /* best-effort */
+                }
+                closeDatabase(db);
+            }
             return entries;
         }
         catch (err) {
-            // Fall back to stale cache if available
-            if (cached && !isExpired(cached.mtime, QUERY_CACHE_STALE_MS)) {
-                return cached.entries;
+            if (db) {
+                try {
+                    closeDatabase(db);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            // Fetch failed — use stale DB cache if available
+            if (dbCacheResult) {
+                try {
+                    const parsed = JSON.parse(dbCacheResult.indexJson);
+                    if (Array.isArray(parsed)) {
+                        const entries = parsed.filter(isValidSkillsEntry);
+                        if (entries.length > 0)
+                            return entries;
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
             }
             throw err;
         }
@@ -167,9 +210,8 @@ class SkillsShProvider {
         });
         return hits.length > 0 ? hits : undefined;
     }
-    // ── Per-query cache ─────────────────────────────────────────────────────
-    queryCachePath(query, limit) {
-        const cacheDir = getRegistryIndexCacheDir();
+    // ── DB cache key ────────────────────────────────────────────────────────
+    queryDbCacheKey(query, limit) {
         const hasher = new Bun.CryptoHasher("md5");
         hasher.update(this.config.url);
         hasher.update("\0");
@@ -177,33 +219,7 @@ class SkillsShProvider {
         hasher.update("\0");
         hasher.update(String(limit));
         const hash = hasher.digest("hex");
-        return path.join(cacheDir, `skills-sh-search-${hash}.json`);
-    }
-    readQueryCache(cachePath) {
-        try {
-            const stat = fs.statSync(cachePath);
-            const raw = JSON.parse(fs.readFileSync(cachePath, "utf8"));
-            if (!Array.isArray(raw))
-                return null;
-            const entries = raw.filter(isValidSkillsEntry);
-            return { entries, mtime: stat.mtimeMs };
-        }
-        catch {
-            return null;
-        }
-    }
-    writeQueryCache(cachePath, entries) {
-        try {
-            const dir = path.dirname(cachePath);
-            fs.mkdirSync(dir, { recursive: true });
-            const tmpPath = `${cachePath}.tmp.${process.pid}`;
-            // 0o600: owner read/write only — cache may contain search terms tied to API keys
-            fs.writeFileSync(tmpPath, JSON.stringify(entries), { encoding: "utf8", mode: 0o600 });
-            fs.renameSync(tmpPath, cachePath);
-        }
-        catch {
-            // Best-effort caching
-        }
+        return `skills-sh:${hash}`;
     }
 }
 // ── Self-register ───────────────────────────────────────────────────────────
@@ -226,7 +242,3 @@ function isValidSkillsEntry(entry) {
         typeof obj.installs === "number" &&
         typeof obj.source === "string");
 }
-// ── Utilities ───────────────────────────────────────────────────────────────
-function isExpired(mtimeMs, ttlMs) {
-    return Date.now() - mtimeMs > ttlMs;
-}