akm-cli 0.9.0-beta.4 → 0.9.0-beta.41

package/dist/integrations/harnesses/opencode/session-log.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { openDatabase } from "../../../storage/database.js";
 import { extractInlineRefMentions } from "../../session-logs/inline-refs.js";
 function getOpenCodeBaseDir() {
     if (process.platform === "darwin") {
@@ -12,20 +13,49 @@ function getOpenCodeBaseDir() {
     return path.join(os.homedir(), ".local", "share", "opencode");
 }
 /**
- * Opencode storage layout (observed 2026-05):
- *   <base>/storage/session/<projectId>/<sessionId>.json    — metadata
- *   <base>/storage/message/<sessionId>/<messageId>.json    — one per message
+ * Opencode storage layouts:
+ *
+ *   SQLite (current, observed 2026-06): `<base>/opencode.db` — a Drizzle-managed
+ *   database with `session` / `message` / `part` tables. Message text lives in
+ *   `part` rows (`data` JSON, `type: "text"`); `message.data` holds role/timing.
+ *   This is the layout current opencode builds write; it is preferred whenever
+ *   `opencode.db` exists.
+ *
+ *   JSON files (legacy, observed 2026-05): `<base>/storage/session/<projectId>/
+ *   <sessionId>.json` (metadata) + `<base>/storage/message/<sessionId>/
+ *   <messageId>.json` (one per message). Read only when `opencode.db` is absent.
  *
  * Older builds wrote logs directly into `<base>/log/` and `<base>/*.log`;
  * those are still scanned by {@link OpenCodeProvider.readEvents} for
  * backward compatibility with the existing failure-pattern aggregator.
  */
+/** Filename of opencode's SQLite session store, relative to its base dir. */
+const OPENCODE_DB_FILENAME = "opencode.db";
 export class OpenCodeProvider {
     name = "opencode";
     #baseDir = getOpenCodeBaseDir();
     isAvailable() {
         return fs.existsSync(this.#baseDir);
     }
+    /** Absolute path to opencode's SQLite store under `base`. */
+    #dbPath(base) {
+        return path.join(base, OPENCODE_DB_FILENAME);
+    }
+    /**
+     * Directories/files opencode writes session data under. Returns the base dir
+     * when the SQLite store (`opencode.db`) exists, the legacy JSON session root
+     * (`<base>/storage/session`) when present, or both during a migration overlap.
+     * Empty when neither exists. See {@link SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const roots = [];
+        if (fs.existsSync(this.#dbPath(this.#baseDir)))
+            roots.push(this.#baseDir);
+        const sessionRoot = path.join(this.#baseDir, "storage", "session");
+        if (fs.existsSync(sessionRoot))
+            roots.push(sessionRoot);
+        return roots;
+    }
     *readEvents(input) {
         // Legacy behavior: stream raw log lines from the top-level dir and `log/`
         // subdirectory. Kept to keep `getExecutionLogCandidates` working without
@@ -82,6 +112,9 @@ export class OpenCodeProvider {
     listSessions(input = {}) {
         const base = input.location ?? this.#baseDir;
         const sinceMs = input.sinceMs ?? 0;
+        const dbPath = this.#dbPath(base);
+        if (fs.existsSync(dbPath))
+            return this.#listSessionsFromDb(dbPath, sinceMs);
         const sessionRoot = path.join(base, "storage", "session");
         if (!fs.existsSync(sessionRoot))
             return [];
@@ -142,6 +175,8 @@ export class OpenCodeProvider {
         return summaries.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
     }
     readSession(ref) {
+        if (path.basename(ref.filePath) === OPENCODE_DB_FILENAME)
+            return this.#readSessionFromDb(ref);
         let meta = {};
         try {
             meta = JSON.parse(fs.readFileSync(ref.filePath, "utf8"));
@@ -199,6 +234,141 @@ export class OpenCodeProvider {
             inlineRefs,
         };
     }
+    /**
+     * List sessions from the SQLite store. `filePath` on each summary is the
+     * `opencode.db` path so {@link readSession} can route back to the DB reader.
+     * Returns `[]` (never throws) when the DB is unreadable or lacks the expected
+     * schema — callers treat a missing harness as "no sessions".
+     */
+    #listSessionsFromDb(dbPath, sinceMs) {
+        let db;
+        try {
+            db = openDatabase(dbPath, { readonly: true, create: false });
+        }
+        catch {
+            return [];
+        }
+        try {
+            const rows = db
+                .prepare("SELECT id, title, directory, time_created, time_updated FROM session WHERE time_updated >= ? ORDER BY time_updated DESC")
+                .all(sinceMs);
+            return rows.map((r) => {
+                const startedAt = typeof r.time_created === "number" ? r.time_created : undefined;
+                const endedAt = typeof r.time_updated === "number" ? r.time_updated : undefined;
+                const title = typeof r.title === "string" && r.title.length > 0 ? r.title : undefined;
+                const projectHint = typeof r.directory === "string" && r.directory.length > 0 ? r.directory : undefined;
+                return {
+                    harness: this.name,
+                    sessionId: r.id,
+                    filePath: dbPath,
+                    ...(startedAt !== undefined ? { startedAt } : {}),
+                    ...(endedAt !== undefined ? { endedAt } : {}),
+                    ...(projectHint ? { projectHint } : {}),
+                    ...(title ? { title } : {}),
+                };
+            });
+        }
+        catch {
+            // Missing `session` table / unexpected schema — treat as no sessions.
+            return [];
+        }
+        finally {
+            db.close();
+        }
+    }
+    /**
+     * Read one session from the SQLite store. Message text lives in `part` rows
+     * (`type: "text"`); `message.data` carries role + timing. One event per
+     * message, text-parts concatenated in time order. Returns empty events
+     * (never throws) when the DB is unreadable.
+     */
+    #readSessionFromDb(ref) {
+        const emptyRef = { harness: this.name, sessionId: ref.sessionId, filePath: ref.filePath };
+        let db;
+        try {
+            db = openDatabase(ref.filePath, { readonly: true, create: false });
+        }
+        catch {
+            return { ref: emptyRef, events: [], inlineRefs: [] };
+        }
+        try {
+            const meta = db
+                .prepare("SELECT title, directory, time_created, time_updated FROM session WHERE id = ?")
+                .get(ref.sessionId);
+            const startedAt = typeof meta?.time_created === "number" ? meta.time_created : undefined;
+            const endedAt = typeof meta?.time_updated === "number" ? meta.time_updated : undefined;
+            const title = typeof meta?.title === "string" && meta.title.length > 0 ? meta.title : undefined;
+            const projectHint = typeof meta?.directory === "string" && meta.directory.length > 0 ? meta.directory : undefined;
+            const messages = db
+                .prepare("SELECT id, data, time_created FROM message WHERE session_id = ? ORDER BY time_created ASC, id ASC")
+                .all(ref.sessionId);
+            const parts = db
+                .prepare("SELECT message_id, data FROM part WHERE session_id = ? ORDER BY time_created ASC, id ASC")
+                .all(ref.sessionId);
+            // Group text-part bodies by their parent message.
+            const textByMessage = new Map();
+            for (const part of parts) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(part.data);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed?.type !== "text")
+                    continue;
+                const text = parsed.text;
+                if (typeof text !== "string" || text.length < 1)
+                    continue;
+                const bucket = textByMessage.get(part.message_id) ?? [];
+                bucket.push(text);
+                textByMessage.set(part.message_id, bucket);
+            }
+            const events = [];
+            const inlineRefs = [];
+            for (const message of messages) {
+                let mdata = {};
+                try {
+                    mdata = JSON.parse(message.data);
+                }
+                catch {
+                    // role/timing unavailable — fall through with defaults
+                }
+                const role = typeof mdata.role === "string" ? mdata.role : "unknown";
+                const mtime = mdata.time?.created;
+                const ts = typeof mtime === "number"
+                    ? mtime
+                    : typeof message.time_created === "number"
+                        ? message.time_created
+                        : undefined;
+                const text = (textByMessage.get(message.id) ?? []).join("\n").trim();
+                if (text.length < 1)
+                    continue;
+                events.push({ harness: this.name, text, ts, sessionId: ref.sessionId, role, filePath: ref.filePath });
+                inlineRefs.push(...extractInlineRefMentions(text, ts));
+            }
+            events.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+            return {
+                ref: {
+                    harness: this.name,
+                    sessionId: ref.sessionId,
+                    filePath: ref.filePath,
+                    ...(startedAt !== undefined ? { startedAt } : {}),
+                    ...(endedAt !== undefined ? { endedAt } : {}),
+                    ...(projectHint ? { projectHint } : {}),
+                    ...(title ? { title } : {}),
+                },
+                events,
+                inlineRefs,
+            };
+        }
+        catch {
+            return { ref: emptyRef, events: [], inlineRefs: [] };
+        }
+        finally {
+            db.close();
+        }
+    }
     /**
      * Derive opencode base dir from a session metadata file path so a caller
      * passing a custom `--location` can still find the message dir.

package/dist/integrations/session-logs/index.js

@@ -28,6 +28,22 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
+/**
+ * Map each available harness to its `{ harnessName, roots }` watch target,
+ * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
+ * result). This is the one stable entry point the watcher uses so it never
+ * reaches into providers directly.
+ */
+export function getWatchTargets() {
+    const targets = [];
+    for (const harness of getAvailableHarnesses()) {
+        const roots = harness.watchRoots?.() ?? [];
+        if (roots.length === 0)
+            continue;
+        targets.push({ harnessName: harness.name, roots });
+    }
+    return targets;
+}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)

package/dist/llm/client.js

@@ -119,9 +119,23 @@ function looksLikeContextOverflow(message) {
 /**
  * Decide whether a first-attempt {@link LlmCallError} is eligible for a single
  * retry. Retryable: HTTP 5xx (`provider_error` with statusCode >= 500) and
- * `network_error` whose message looks like a transient connection reset
- * (ECONNRESET / EPIPE / "fetch failed"). NOT retryable: 4xx, `rate_limited`
- * (429), `timeout`, `parse_error`, and context-overflow-classified errors.
+ * `network_error` whose message looks like a transient connection drop.
+ * NOT retryable: 4xx, `rate_limited` (429), `timeout`, `parse_error`, and
+ * context-overflow-classified errors.
+ *
+ * The connection-drop heuristic covers the substrings emitted across runtimes
+ * for a mid-flight socket close:
+ *  - `ECONNRESET` / `EPIPE` — Node/libuv socket reset codes
+ *  - `fetch failed` — undici's generic wrapper message
+ *  - `socket connection was closed` — Bun's message for a dropped connection
+ *    (e.g. "The socket connection was closed unexpectedly.")
+ *  - `terminated` / `other side closed` — undici's phrasings for the same
+ *
+ * These all describe a transient transport failure where a second attempt can
+ * legitimately succeed, which is exactly the case a single bounded retry is
+ * meant to absorb. Before this list was widened, Bun's "socket connection was
+ * closed unexpectedly" fell through unretried and surfaced as a recurring
+ * failure in the improve/reflect and capability-probe flows.
  */
 function isRetryable(err) {
     if (looksLikeContextOverflow(err.message))
@@ -131,7 +145,12 @@ function isRetryable(err) {
     }
     if (err.code === "network_error") {
         const lower = err.message.toLowerCase();
-        return lower.includes("econnreset") || lower.includes("epipe") || lower.includes("fetch failed");
+        return (lower.includes("econnreset") ||
+            lower.includes("epipe") ||
+            lower.includes("fetch failed") ||
+            lower.includes("socket connection was closed") ||
+            lower.includes("terminated") ||
+            lower.includes("other side closed"));
     }
     return false;
 }

package/dist/llm/embedder.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
-import { isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
@@ -52,7 +52,8 @@ export async function embed(text, embeddingConfig, signal) {
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for the local transformer pipeline.
+ * Uses the LocalEmbedder.embedBatch path for the local transformer pipeline,
+ * which processes texts in chunks of 32 for genuine batched inference.
  */
 export async function embedBatch(texts, embeddingConfig, signal) {
     if (texts.length === 0)
@@ -60,8 +61,13 @@ export async function embedBatch(texts, embeddingConfig, signal) {
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal);
     }
-    // Local transformer: process sequentially (pipeline handles one at a time)
+    // Local transformer: use the batched path (chunks of 32 via LocalEmbedder).
+    // When a localModel override is set we cannot share the singleton (which uses
+    // the default model), so fall back to per-text embedWithModel in that case.
     const localModel = embeddingConfig?.localModel;
+    if (!localModel) {
+        return getLocalEmbedder().embedBatch(texts, signal);
+    }
     const results = [];
     for (const text of texts) {
         if (signal?.aborted) {
@@ -77,6 +83,24 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // facade and its `@huggingface/transformers` import chain. Re-export
 // preserves the existing public API.
 export { cosineSimilarity } from "./embedders/types.js";
+// ── Model ID resolution ─────────────────────────────────────────────────────
+/**
+ * Derive a stable string identifier for the embedding model in use.
+ * This is the `model_id` stored in `body_embeddings` (and used for the
+ * drop-all-on-mismatch purge when the model changes).
+ *
+ * Rules:
+ *   - Remote endpoint: use `config.model` (the API-level model name).
+ *   - Local transformers: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
+ *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
+ */
+export function resolveEmbeddingModelId(embeddingConfig) {
+    if (!embeddingConfig)
+        return DEFAULT_LOCAL_MODEL;
+    if (hasRemoteEndpoint(embeddingConfig))
+        return embeddingConfig.model ?? "remote";
+    return embeddingConfig.localModel ?? DEFAULT_LOCAL_MODEL;
+}
 // ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check whether embedding is available with a detailed reason on failure.

package/dist/llm/embedders/local.js

@@ -19,8 +19,24 @@ import { getDirname, resolveModule } from "../../runtime.js";
  * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
  */
 export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
+/** Type-guard: true when the value looks like a batch Tensor (has .dims). */
+function isBatchTensor(v) {
+    return (v !== null &&
+        typeof v === "object" &&
+        "data" in v &&
+        "dims" in v &&
+        Array.isArray(v.dims) &&
+        v.dims.length >= 2);
+}
 const LOCAL_EMBEDDER_DTYPE = "fp32";
 const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
+/**
+ * Maximum texts per batch for the local transformers pipeline. The pipeline
+ * can run genuine batched inference over a string array; 32 is a safe default
+ * that fits well inside most model context budgets while providing 10–50×
+ * throughput improvement over one-at-a-time calls on the cold minority.
+ */
+const LOCAL_BATCH_SIZE = 32;
 /**
  * Return the local model name that will be used for embedding.
  * When `overrideModel` is provided it takes precedence; otherwise
@@ -77,15 +93,63 @@ export class LocalEmbedder {
         }
         return this.embedWithModel(text, this.defaultModel);
     }
+    /**
+     * Embed a batch of texts. Processes in chunks of `LOCAL_BATCH_SIZE` (32) so
+     * the transformers pipeline can run genuine batched inference rather than one
+     * call per text. Falls back to one-at-a-time if the pipeline does not support
+     * array input (older versions of @huggingface/transformers). Each chunk is
+     * checked against the AbortSignal between calls.
+     */
     async embedBatch(texts, signal) {
         if (texts.length === 0)
             return [];
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+        }
+        const pipeline = await this.getPipeline(this.defaultModel);
         const results = [];
-        for (const text of texts) {
+        for (let i = 0; i < texts.length; i += LOCAL_BATCH_SIZE) {
             if (signal?.aborted) {
                 throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
             }
-            results.push(await this.embedWithModel(text, this.defaultModel));
+            const chunk = texts.slice(i, i + LOCAL_BATCH_SIZE);
+            try {
+                // @huggingface/transformers feature-extraction pipeline accepts a
+                // string[] and returns a batch Tensor (NOT an Array<{data}>).
+                // The Tensor has .data (flat Float32Array, length = batch * dim) and
+                // .dims = [batch, dim]. Slice .data into per-row vectors using .dims.
+                const batchResult = await pipeline(chunk, {
+                    pooling: "mean",
+                    normalize: true,
+                });
+                if (isBatchTensor(batchResult)) {
+                    const dim = batchResult.dims[1];
+                    for (let row = 0; row < chunk.length; row++) {
+                        results.push(Array.from(batchResult.data.subarray(row * dim, (row + 1) * dim)));
+                    }
+                }
+                else if (Array.isArray(batchResult)) {
+                    // Older versions of @huggingface/transformers returned Array<{data}>.
+                    for (const r of batchResult) {
+                        results.push(Array.from(r.data));
+                    }
+                }
+                else {
+                    // Single-text result returned for a chunk — should not happen for
+                    // string[] input, but handle defensively.
+                    throw new Error("unexpected pipeline return shape for batch input");
+                }
+            }
+            catch {
+                // Fallback: process one-at-a-time (older pipeline versions or mismatched
+                // return type). Fail-open per text: a single failure aborts the chunk.
+                for (const text of chunk) {
+                    if (signal?.aborted) {
+                        throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+                    }
+                    results.push(await this.embedWithModel(text, this.defaultModel));
+                }
+            }
         }
         return results;
     }

package/dist/llm/feature-gate.js

@@ -30,10 +30,14 @@ const FEATURE_LOCATION = {
     proposal_quality_gate: (cfg) => cfg.profiles?.improve?.default?.processes?.reflect?.qualityGate?.enabled ?? false,
     // Legacy default: false
     memory_contradiction_detection: (cfg) => cfg.profiles?.improve?.default?.processes?.consolidate?.contradictionDetection?.enabled ?? false,
-    // Default: true. Session extraction replaces the akm-plugin checkpoint hook
-    // and is the primary path for capturing durable signal from real sessions.
-    // Opt out via `profiles.improve.default.processes.extract.enabled: false`.
-    session_extraction: (cfg) => cfg.profiles?.improve?.default?.processes?.extract?.enabled ?? true,
+    // Always on at the LLM-wrapper level. Enablement is decided ONCE at the
+    // extract entry point (`akmExtract`): the `extract.enabled` process toggle
+    // gates extract as a STAGE of `akm improve` (the active improve profile, per
+    // #593/#594), while an explicit `akm extract` command always runs. Gating the
+    // inner LLM calls on `default.processes.extract.enabled` here was a footgun —
+    // dropping extract from the daily improve profile silently disabled the
+    // standalone `akm extract` command. (cfg unused — kept for resolver signature.)
+    session_extraction: (_cfg) => true,
 };
 /**
  * Pure predicate: is the named feature gate enabled in `config`?

package/dist/llm/graph-extract.js

@@ -20,6 +20,7 @@
  * the connection via `resolveIndexPassLLM("graph", config)` and pass it
  * straight through.
  */
+import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" with { type: "text" };
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn, warnVerbose } from "../core/warn.js";
@@ -41,7 +42,7 @@ const NON_ARRAY_BATCH_DISABLE_THRESHOLD = 2;
 const MAX_ENTITIES_PER_ASSET = 32;
 /** Hard cap on relations returned per asset. */
 const MAX_RELATIONS_PER_ASSET = 32;
-const SYSTEM_PROMPT = "You extract a knowledge graph from developer notes. Return ONLY valid JSON — no prose, no markdown fences, no preamble.";
+const SYSTEM_PROMPT = systemPromptTemplate;
 const USER_PROMPT_PREFIX = userPromptTemplate
     .replace("{{MAX_ENTITIES}}", String(MAX_ENTITIES_PER_ASSET))
     .replace("{{MAX_RELATIONS}}", String(MAX_RELATIONS_PER_ASSET));

package/dist/llm/memory-infer.js

@@ -18,20 +18,16 @@
  * the connection via `resolveIndexPassLLM("memory", config)` and pass it
  * straight through.
  */
+import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" with { type: "text" };
+import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn } from "../core/warn.js";
 import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 /** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
 const MAX_BODY_CHARS = 4000;
-const SYSTEM_PROMPT = "You compress a developer memory into one high-signal derived memory for later retrieval. " +
-    "Return only valid JSON. No prose outside the JSON object. No markdown fences.";
-const USER_PROMPT_PREFIX = `Compress the memory below into one derived memory. Output ONLY JSON:
-{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
-Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
-
-Memory:
-`;
+const SYSTEM_PROMPT = memoryInferSystemPrompt;
+const USER_PROMPT_PREFIX = memoryInferUserPrompt;
 /**
  * Strict JSON Schema for the derived-memory payload. Sent to providers that
  * opt in via `LlmConnectionConfig.supportsJsonSchema = true`; the client

package/dist/llm/metadata-enhance.js

@@ -1,9 +1,17 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * LLM-driven metadata enhancement for stash entries.
+ *
+ * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
+ * improve descriptions/tags/searchHints) lives separately from the low-level
+ * transport client in `client.ts`.
+ */
+import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
 import { chatCompletion, parseJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
-const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
+const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
  * generate searchHints, and suggest tags.

package/dist/output/renderers.js

@@ -468,6 +468,44 @@ const sessionMdRenderer = {
         };
     },
 };
+// ── 9. fact-md ───────────────────────────────────────────────────────────────
+/**
+ * Renderer for the `fact` asset type. A fact is durable stash-level semantic
+ * knowledge (personal/team/project details, coding conventions, stash-meta).
+ * It carries `category` (personal|team|project|convention|meta) and an
+ * optional `pinned` flag marking it as part of the always-injected core. The
+ * renderer surfaces a one-liner (category + pinned marker) so an agent can tell
+ * at a glance what kind of fact it is and whether it is core context.
+ */
+const factMdRenderer = {
+    name: "fact-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsed = parseFrontmatter(ctx.content());
+        const fm = parsed.data;
+        const category = asNonEmptyString(fm.category);
+        const description = asNonEmptyString(fm.description);
+        const pinned = fm.pinned === true;
+        const headerParts = [
+            category ? `category: ${category}` : undefined,
+            pinned ? "pinned (core context)" : undefined,
+        ].filter((p) => !!p);
+        const action = [
+            "Durable stash fact — apply it as background context.",
+            headerParts.length > 0 ? headerParts.join("  ") : undefined,
+        ]
+            .filter((p) => !!p)
+            .join("\n");
+        return {
+            type: "fact",
+            name,
+            path: ctx.absPath,
+            action,
+            description,
+            content: parsed.content,
+        };
+    },
+};
 function applySessionMetadata(entry, ctx) {
     try {
         const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
@@ -501,6 +539,34 @@ function applyTocMetadata(entry, ctx) {
         // Non-fatal: skip TOC if file can't be read
     }
 }
+/**
+ * Fact metadata: surface `category` and the `pinned` core marker as tags +
+ * search hints (no dedicated DB columns — same encoding pattern as session /
+ * task). `pinned` is mirrored to both a `pinned` tag and a `pinned` search
+ * hint so the ranking contributor can detect it and queries can target it.
+ */
+function applyFactMetadata(entry, ctx) {
+    try {
+        const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
+        const tags = new Set([...(entry.tags ?? []), "fact"]);
+        const hints = new Set(entry.searchHints ?? []);
+        const category = asNonEmptyString(fm.category);
+        if (category) {
+            tags.add(category);
+            hints.add(`category:${category}`);
+        }
+        if (fm.pinned === true) {
+            tags.add("pinned");
+            hints.add("pinned");
+        }
+        entry.tags = Array.from(tags).filter(Boolean);
+        if (hints.size > 0)
+            entry.searchHints = Array.from(hints).filter(Boolean);
+    }
+    catch {
+        // Non-fatal: skip metadata extraction on parse error
+    }
+}
 /**
  * Parse frontmatter, apply description (if not already set) and merge tags
  * into `entry`. Returns the raw frontmatter data object so callers can access
@@ -660,6 +726,11 @@ registerMetadataContributor({
     appliesTo: ({ rendererName }) => rendererName === "session-md",
     contribute: (entry, ctx) => applySessionMetadata(entry, ctx.renderContext),
 });
+registerMetadataContributor({
+    name: "fact-md-metadata",
+    appliesTo: ({ rendererName }) => rendererName === "fact-md",
+    contribute: (entry, ctx) => applyFactMetadata(entry, ctx.renderContext),
+});
 // ── Registration ─────────────────────────────────────────────────────────────
 /** All built-in renderers. */
 const builtinRenderers = [
@@ -676,6 +747,7 @@ const builtinRenderers = [
     secretFileRenderer,
     taskMdRenderer,
     sessionMdRenderer,
+    factMdRenderer,
 ];
 /**
  * Register all built-in renderers with the file-context registry.
@@ -687,4 +759,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, envFileRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, secretFileRenderer, skillMdRenderer, wikiMdRenderer, workflowMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, envFileRenderer, factMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, secretFileRenderer, skillMdRenderer, wikiMdRenderer, workflowMdRenderer, };

package/dist/output/shapes/curate.js

@@ -5,7 +5,7 @@ import { capDescription, NORMAL_DESCRIPTION_LIMIT, pickFields } from "./helpers.
 // Curation is a small, high-signal top-N. Even at `brief` we keep `followUp`
 // (the actionable `akm show <ref>` command) and `reason` (why this asset was
 // selected) — these are the point of curate, unlike a bulk search listing.
-const BRIEF_FIELDS = ["source", "type", "name", "ref", "id", "followUp", "reason"];
+const BRIEF_FIELDS = ["source", "type", "name", "ref", "id", "supportRefs", "followUp", "reason"];
 const NORMAL_FIELDS = [
     "source",
     "type",
@@ -17,12 +17,24 @@ const NORMAL_FIELDS = [
     "keys",
     "parameters",
     "run",
+    "supportRefs",
     "followUp",
     "reason",
     "score",
 ];
 // Agent shape: the minimal field set an LLM needs to decide and act.
-const AGENT_FIELDS = ["source", "type", "name", "ref", "id", "description", "followUp", "reason", "score"];
+const AGENT_FIELDS = [
+    "source",
+    "type",
+    "name",
+    "ref",
+    "id",
+    "description",
+    "supportRefs",
+    "followUp",
+    "reason",
+    "score",
+];
 function shapeCurateItem(item, detail, shape) {
     if (shape === "agent") {
         return capDescription(pickFields(item, AGENT_FIELDS), NORMAL_DESCRIPTION_LIMIT);