akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/llm/memory-infer-impl.js

@@ -0,0 +1,138 @@
+// 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 helper for the `akm index` memory-inference pass (#201).
+ *
+ * Compresses a single memory body into one higher-signal derived memory. The
+ * pass itself (in `src/indexer/memory-inference.ts`) is responsible for
+ * deciding which memories are pending, persisting the derived memory with the
+ * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and marking
+ * the parent as processed for idempotency.
+ *
+ * This module is intentionally tiny and stateless so tests can stub it via
+ * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
+ *
+ * Locked v1 contract (#208): the LLM connection always comes from the
+ * shared `akm.llm` block — never from a per-pass override. Callers obtain
+ * 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 { parseEmbeddedJsonResponse } from "./client.js";
+import { callStructured } from "./structured-call.js";
+/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
+const MAX_BODY_CHARS = 4000;
+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
+ * silently drops the schema for providers that don't.
+ *
+ * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
+ * the memory-inference path. Mirrors the validation gate below
+ * (title/description/content + non-empty tags/searchHints) so a
+ * schema-compliant response is guaranteed to pass the downstream check
+ * — no more "incomplete derived memory payload from LLM; skipping memory"
+ * for shape-only failures.
+ */
+const DERIVED_MEMORY_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        content: { type: "string", minLength: 1 },
+        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
+        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
+    },
+    required: ["title", "description", "content", "tags", "searchHints"],
+    additionalProperties: false,
+};
+/**
+ * Compress a single memory body into one derived memory via the configured LLM.
+ *
+ * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
+ * Errors are logged via `warn()` but never thrown — a failed split for one memory
+ * must not abort the rest of the index pass.
+ *
+ * Routes through `callStructured({ feature: "memory_inference", ... })` so the
+ * feature gate, error classification, and onFallback hook are honoured uniformly
+ * (Fix C5).
+ */
+export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return undefined;
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    // Memory-inference is ALWAYS gated: no `akmConfig` ⇒ gate closed (no chat,
+    // `disabled` fallback), never the seam's ungated/propagate path (which is for
+    // direct callers like `enhanceMetadata`). This is the gate-closed branch
+    // `tryLlmFeature(_, undefined, _)` took before the migration.
+    if (!akmConfig) {
+        onFallback?.({ feature: "memory_inference", reason: "disabled" });
+        return undefined;
+    }
+    return callStructured({
+        feature: "memory_inference",
+        akmConfig,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
+            onRetryAttempt,
+        },
+        parse: (raw) => {
+            if (!raw)
+                return undefined;
+            const parsed = parseEmbeddedJsonResponse(raw);
+            if (!parsed) {
+                warn("memory inference: invalid JSON response from LLM; skipping memory.");
+                return undefined;
+            }
+            const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
+            const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
+            const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
+            const tags = Array.isArray(parsed.tags)
+                ? parsed.tags
+                    .filter((t) => typeof t === "string")
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                    .slice(0, 8)
+                : [];
+            const searchHints = Array.isArray(parsed.searchHints)
+                ? parsed.searchHints
+                    .filter((h) => typeof h === "string")
+                    .map((h) => h.trim())
+                    .filter(Boolean)
+                    .slice(0, 6)
+                : [];
+            if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
+                warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
+                return undefined;
+            }
+            return { title, description, tags, searchHints, content };
+        },
+        onError: (cls, err) => {
+            if (cls === "html") {
+                if (telemetry)
+                    telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
+                warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
+                return undefined;
+            }
+            warn(`memory inference failed: ${toErrorMessage(err)}`);
+            return undefined;
+        },
+        fallback: undefined,
+        onFallback,
+    });
+}

package/dist/llm/memory-infer.js

@@ -1,130 +1,4 @@
 // 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 helper for the `akm index` memory-inference pass (#201).
- *
- * Compresses a single memory body into one higher-signal derived memory. The
- * pass itself (in `src/indexer/memory-inference.ts`) is responsible for
- * deciding which memories are pending, persisting the derived memory with the
- * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and marking
- * the parent as processed for idempotency.
- *
- * This module is intentionally tiny and stateless so tests can stub it via
- * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
- *
- * Locked v1 contract (#208): the LLM connection always comes from the
- * shared `akm.llm` block — never from a per-pass override. Callers obtain
- * the connection via `resolveIndexPassLLM("memory", config)` and pass it
- * straight through.
- */
-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:
-`;
-/**
- * Strict JSON Schema for the derived-memory payload. Sent to providers that
- * opt in via `LlmConnectionConfig.supportsJsonSchema = true`; the client
- * silently drops the schema for providers that don't.
- *
- * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
- * the memory-inference path. Mirrors the validation gate below
- * (title/description/content + non-empty tags/searchHints) so a
- * schema-compliant response is guaranteed to pass the downstream check
- * — no more "incomplete derived memory payload from LLM; skipping memory"
- * for shape-only failures.
- */
-const DERIVED_MEMORY_JSON_SCHEMA = {
-    type: "object",
-    properties: {
-        title: { type: "string", minLength: 1 },
-        description: { type: "string", minLength: 1 },
-        content: { type: "string", minLength: 1 },
-        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
-        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
-    },
-    required: ["title", "description", "content", "tags", "searchHints"],
-    additionalProperties: false,
-};
-/**
- * Compress a single memory body into one derived memory via the configured LLM.
- *
- * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
- * Errors are logged via `warn()` but never thrown — a failed split for one memory
- * must not abort the rest of the index pass.
- *
- * Routes through `tryLlmFeature("memory_inference", ...)` so the feature gate
- * and onFallback hook are honoured uniformly (Fix C5).
- */
-export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
-    const trimmedBody = body.trim();
-    if (!trimmedBody)
-        return undefined;
-    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
-    return tryLlmFeature("memory_inference", akmConfig, async () => {
-        try {
-            const raw = await chatCompletion(llmConfig, [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
-                signal,
-                responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
-                onRetryAttempt,
-            });
-            if (!raw)
-                return undefined;
-            const parsed = parseEmbeddedJsonResponse(raw);
-            if (!parsed) {
-                warn("memory inference: invalid JSON response from LLM; skipping memory.");
-                return undefined;
-            }
-            const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
-            const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
-            const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
-            const tags = Array.isArray(parsed.tags)
-                ? parsed.tags
-                    .filter((t) => typeof t === "string")
-                    .map((t) => t.trim())
-                    .filter(Boolean)
-                    .slice(0, 8)
-                : [];
-            const searchHints = Array.isArray(parsed.searchHints)
-                ? parsed.searchHints
-                    .filter((h) => typeof h === "string")
-                    .map((h) => h.trim())
-                    .filter(Boolean)
-                    .slice(0, 6)
-                : [];
-            if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
-                warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
-                return undefined;
-            }
-            return { title, description, tags, searchHints, content };
-        }
-        catch (err) {
-            if (err instanceof LlmCallError && err.code === "provider_html_error") {
-                if (telemetry)
-                    telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
-                warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
-                return undefined;
-            }
-            warn(`memory inference failed: ${toErrorMessage(err)}`);
-            return undefined;
-        }
-    }, undefined, {
-        timeoutMs: llmConfig.timeoutMs,
-        onFallback,
-    });
-}
+export { compressMemoryToDerivedMemory, } from "./memory-infer-impl.js";

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/.
-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.`;
+/**
+ * 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 { parseJsonResponse } from "./client.js";
+import { callStructured } from "./structured-call.js";
+const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
  * generate searchHints, and suggest tags.
@@ -33,34 +41,39 @@ Generate improved metadata for this ${entry.type}. Return JSON with these fields
 - "tags": an array of 3-8 relevant keyword tags
 
 Return ONLY the JSON object, no explanation.`;
-    const runLlm = async () => {
-        const raw = await chatCompletion(config, [
+    // `parse` owns the raw response: the `!raw`/unparseable case ⇒ `{}`, plus the
+    // description/searchHints/tags shaping. `enhanceMetadata` never warns and
+    // never bumps telemetry, so `onError` (gated path only) just swallows to `{}`
+    // — identical to the surrounding control flow's pre-migration behaviour. The
+    // ungated path (akmConfig === undefined) propagates errors via callStructured.
+    return callStructured({
+        feature: "metadata_enhance",
+        akmConfig,
+        config,
+        messages: [
             { role: "system", content: SYSTEM_PROMPT },
             { role: "user", content: userPrompt },
-        ], { signal });
-        const parsed = parseJsonResponse(raw);
-        if (!parsed)
-            return {};
-        const result = {};
-        if (typeof parsed.description === "string" && parsed.description) {
-            result.description = parsed.description;
-        }
-        if (Array.isArray(parsed.searchHints)) {
-            result.searchHints = parsed.searchHints
-                .filter((s) => typeof s === "string" && s.trim().length > 0)
-                .slice(0, 8);
-        }
-        if (Array.isArray(parsed.tags)) {
-            result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
-        }
-        return result;
-    };
-    // When no akmConfig is provided, bypass the feature gate entirely: run the
-    // LLM call directly and let errors propagate to the caller (pre-gate
-    // behaviour). When akmConfig is present, honour the feature flag and swallow
-    // errors to {} via tryLlmFeature.
-    if (akmConfig === undefined) {
-        return runLlm();
-    }
-    return tryLlmFeature("metadata_enhance", akmConfig, runLlm, {}, { timeoutMs: config.timeoutMs });
+        ],
+        request: { signal, timeoutMs: config.timeoutMs },
+        parse: (raw) => {
+            const parsed = raw ? parseJsonResponse(raw) : undefined;
+            if (!parsed)
+                return {};
+            const result = {};
+            if (typeof parsed.description === "string" && parsed.description) {
+                result.description = parsed.description;
+            }
+            if (Array.isArray(parsed.searchHints)) {
+                result.searchHints = parsed.searchHints
+                    .filter((s) => typeof s === "string" && s.trim().length > 0)
+                    .slice(0, 8);
+            }
+            if (Array.isArray(parsed.tags)) {
+                result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+            }
+            return result;
+        },
+        onError: () => ({}),
+        fallback: {},
+    });
 }

package/dist/llm/structured-call.js

@@ -0,0 +1,49 @@
+// 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/.
+import { chatCompletion, isContextSizeError, LlmCallError } from "./client.js";
+import { tryLlmFeature } from "./feature-gate.js";
+/**
+ * Classify a thrown LLM error into one of the three buckets. This is the single
+ * home for the `isContextSizeError -> html -> other` ladder that was previously
+ * inlined at every call site.
+ */
+export function classifyLlmError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (isContextSizeError(message))
+        return "context_limit";
+    if (err instanceof LlmCallError && err.code === "provider_html_error")
+        return "html";
+    return "other";
+}
+export async function callStructured(opts) {
+    const { feature, akmConfig, config, messages, request, parse, onError, fallback, onFallback } = opts;
+    const chat = request?.chat ?? chatCompletion;
+    const chatOptions = {
+        temperature: request?.temperature,
+        timeoutMs: request?.timeoutMs,
+        signal: request?.signal,
+        responseSchema: request?.responseSchema,
+        onRetryAttempt: request?.onRetryAttempt,
+    };
+    // UNGATED: run the chat+parse directly. Errors propagate — no `onError`
+    // funnel — matching the pre-gate behaviour of direct callers.
+    if (akmConfig === undefined) {
+        const raw = await chat(config, messages, chatOptions);
+        return parse(raw);
+    }
+    // GATED: run through `tryLlmFeature`. A throw inside is classified ONCE and
+    // routed to `onError`; `tryLlmFeature` returns `fallback` on disablement/timeout.
+    return tryLlmFeature(feature, akmConfig, async () => {
+        try {
+            const raw = await chat(config, messages, chatOptions);
+            return parse(raw);
+        }
+        catch (err) {
+            return onError(classifyLlmError(err), err);
+        }
+    }, fallback, {
+        timeoutMs: request?.timeoutMs,
+        onFallback,
+    });
+}

package/dist/migrate-storage-node.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// 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/.
+
+const { main } = await import("./scripts/migrate-storage.js");
+
+await main();

package/dist/output/context.js

@@ -12,10 +12,10 @@
  * Initialized from `cli.ts` before `runMain`.
  */
 import { UsageError } from "../core/errors.js";
-export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
-export const DETAIL_LEVELS = ["brief", "normal", "full"];
-export const SHAPE_MODES = ["human", "agent", "summary"];
-export function parseOutputFormat(value) {
+const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
+const DETAIL_LEVELS = ["brief", "normal", "full"];
+const SHAPE_MODES = ["human", "agent", "summary"];
+function parseOutputFormat(value) {
     if (!value)
         return undefined;
     if (OUTPUT_FORMATS.includes(value))
@@ -29,7 +29,7 @@ export function parseDetailLevel(value) {
         return value;
     throw new UsageError(`Invalid value for --detail: ${value}. Expected one of: ${DETAIL_LEVELS.join("|")}`, "INVALID_DETAIL_VALUE");
 }
-export function parseShapeMode(value) {
+function parseShapeMode(value) {
     if (!value)
         return undefined;
     if (SHAPE_MODES.includes(value))

package/dist/output/renderers.js

@@ -210,6 +210,10 @@ const agentMdRenderer = {
             action: "Dispatch using the prompt below verbatim. Use modelHint and toolPolicy if present.",
             description: asNonEmptyString(parsedMd.data.description),
             prompt: parsedMd.content,
+            // `tools` is self-declared frontmatter. The provenance CEILING that decides
+            // whether this self-declared policy is honoured is applied at the show
+            // layer (`akmShowUnified`), which knows whether the source is the operator's
+            // own writable stash vs a read-only third-party source (07 P1-D).
             toolPolicy: parsedMd.data.tools,
             modelHint: typeof parsedMd.data.model === "string" ? parsedMd.data.model : undefined,
         };
@@ -364,23 +368,21 @@ const scriptSourceRenderer = {
 };
 // ── 8. env-file ───────────────────────────────────────────────────────────────
 /**
- * Env renderer. Returns ONLY key names and start-of-line comments — never
- * values. Deliberately omits content/template/prompt so env values cannot leak
- * through `akm show`.
+ * Env renderer. Returns ONLY key names — never values, and never comment
+ * text (comments routinely contain commented-out credentials). Deliberately
+ * omits content/template/prompt so env values cannot leak through `akm show`.
  */
 const envFileRenderer = {
     name: "env-file",
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
-        const { keys, comments } = listVaultKeys(ctx.absPath);
+        const { keys } = listVaultKeys(ctx.absPath);
         return {
             type: "env",
             name,
             path: ctx.absPath,
-            action: "Environment — keys + comments only. Use `akm env run <ref> -- <command>` to run with the whole .env injected (the safe path — values never reach stdout). `akm env export <ref> --out <file>` writes a sourceable script to a file. Never `source` the raw file. Values stay on disk and are never written to akm's stdout.",
-            description: comments.length > 0 ? comments.join("\n") : undefined,
+            action: "Environment — key names only. Use `akm env run <ref> -- <command>` to run with the whole .env injected; prefer `--clean` to minimize inherited parent env. AKM itself does not print values, but child stdout/stderr is not redacted. `akm env export <ref> --out <file>` writes a sourceable script to a file. Never `source` the raw file. Values stay on disk and are never written to akm's stdout.",
             keys,
-            comments,
         };
     },
     enrichSearchHit(hit, _stashDir) {
@@ -468,6 +470,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 +541,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
@@ -581,12 +649,9 @@ function applyScriptMetadata(entry, ctx) {
     }
 }
 function applyEnvMetadata(entry, ctx) {
-    const { keys, comments } = listVaultKeys(ctx.absPath);
-    if (comments.length > 0 && !entry.description) {
-        entry.description = comments.join(" ").slice(0, 500);
-        entry.source = "comments";
-        entry.confidence = 0.7;
-    }
+    // Key names only — comment text must never reach description/search_text
+    // (comments routinely contain commented-out credentials).
+    const { keys } = listVaultKeys(ctx.absPath);
     if (keys.length > 0) {
         entry.searchHints = keys;
     }
@@ -660,6 +725,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 +746,7 @@ const builtinRenderers = [
     secretFileRenderer,
     taskMdRenderer,
     sessionMdRenderer,
+    factMdRenderer,
 ];
 /**
  * Register all built-in renderers with the file-context registry.
@@ -687,4 +758,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);

package/dist/output/shapes/helpers.js

@@ -369,7 +369,6 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "workflowParameters",
             "steps",
             "keys",
-            "comments",
             "related",
         ]);
     }
@@ -385,7 +384,6 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "run",
             "origin",
             "keys",
-            "comments",
             "related",
         ]);
     }
@@ -411,7 +409,6 @@ export function shapeShowOutput(result, detail, shape = "human") {
         "cwd",
         "activeRun",
         "keys",
-        "comments",
         "related",
         // path and editable are always projected so JSON consumers can locate and
         // edit the asset without needing --detail full (QA #7).