akm-cli 0.9.0-beta.2 → 0.9.0-beta.26

package/dist/commands/read/curate.js

@@ -8,11 +8,12 @@
  * high-signal set of stash + registry hits and enrich each with the data
  * needed to act (ref, run, parameters, follow-up command).
  *
- * The exported `akmCurate()` API is the single entry point. Internal
- * helpers stay private. Tests can drive the public API or call the smaller
- * pure helpers (`curateSearchResults`, `orderCuratedTypes`,
- * `deriveCurateFallbackQueries`) by importing them directly.
+ * The exported `akmCurate()` API is the single entry point. Internal helpers
+ * stay private. Tests can drive the public API or call the smaller pure
+ * helpers (`curateSearchResults`, `deriveCurateFallbackQueries`,
+ * `mergeCurateSearchResponses`) by importing them directly.
  */
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
@@ -34,13 +35,19 @@ const CURATE_FALLBACK_FILTER_WORDS = new Set([
     "to",
     "with",
 ]);
-const CURATED_TYPE_FALLBACK_ORDER = ["skill", "command", "script", "knowledge", "agent", "memory"];
-const CURATED_TYPE_FALLBACK_INDEX = new Map(CURATED_TYPE_FALLBACK_ORDER.map((type, index) => [type, index]));
+const CURATE_SHORT_FALLBACK_TOKENS = new Set(["ai", "ci", "cd", "go", "js", "ts"]);
 const MIN_CURATE_FALLBACK_TOKEN_LENGTH = 3;
 const MAX_CURATE_FALLBACK_KEYWORDS = 6;
 export const CURATE_SEARCH_LIMIT_MULTIPLIER = 4;
 export const MIN_CURATE_SEARCH_LIMIT = 12;
 const DEFAULT_CURATE_LIMIT = 4;
+const CURATE_CLOSE_SCORE_BAND = 0.12;
+const CURATE_TAIL_SCORE_FLOOR = 0.35;
+const CURATE_RELATIVE_SCORE_FLOOR = 0.7;
+const CURATE_FALLBACK_TOP_SCORE_THRESHOLD = 0.8;
+const CURATE_FALLBACK_STRONG_SCORE_FLOOR = 0.35;
+const MAX_CURATE_SUPPORT_REFS = 2;
+const CURATE_REFERENCE_QUERY_RE = /\b(?:reference|docs?|guide|how|explain|learn|readme|why)\b/;
 /**
  * Fire-and-forget: log a curate event to the usage_events table and events.jsonl.
  * Never blocks the caller; errors are silently ignored.
@@ -63,6 +70,16 @@ function logCurateEvent(query, result) {
                 }),
                 source: "user",
             });
+            for (const item of result.items) {
+                if (!("ref" in item) || typeof item.ref !== "string")
+                    continue;
+                insertUsageEvent(db, {
+                    event_type: "curate",
+                    query,
+                    entry_ref: item.ref,
+                    source: "user",
+                });
+            }
         }
         finally {
             closeDatabase(db);
@@ -70,13 +87,8 @@ function logCurateEvent(query, result) {
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
-        /* ignore logging failures */
     }
 }
-/**
- * Public curate entry point. Performs the search itself when
- * `options.searchResponse` is not supplied.
- */
 export async function akmCurate(options) {
     const trimmedQuery = options.query.trim();
     if (!trimmedQuery) {
@@ -88,8 +100,6 @@ export async function akmCurate(options) {
         (await searchForCuration({
             query: options.query,
             type: options.type,
-            // Search deeper than the final curated count so we can pick one strong
-            // match per type and still have room for fallback retries.
             limit: Math.max(limit * CURATE_SEARCH_LIMIT_MULTIPLIER, MIN_CURATE_SEARCH_LIMIT),
             source,
         }));
@@ -101,23 +111,22 @@ export async function curateSearchResults(query, result, limit, selectedType) {
     const stashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];
     let selectedStashHits;
+    let supportRefsByRef = new Map();
     if (selectedType && selectedType !== "any") {
         selectedStashHits = stashHits.slice(0, limit);
     }
     else {
-        const bestByType = new Map();
-        for (const hit of stashHits) {
-            if (!bestByType.has(hit.type))
-                bestByType.set(hit.type, hit);
-        }
-        const orderedTypes = orderCuratedTypes(query, Array.from(bestByType.keys()));
-        selectedStashHits = orderedTypes
-            .map((type) => bestByType.get(type))
-            .filter((hit) => Boolean(hit));
+        const selected = selectCuratedStashHits(query, stashHits, limit);
+        const preferred = preferBroadRootRepresentative(query, selected.selected, stashHits, selected.supportRefsByRef);
+        selectedStashHits = preferred.selected;
+        supportRefsByRef = preferred.supportRefsByRef;
     }
     const selectedRegistryHits = selectedStashHits.length >= limit ? [] : registryHits.slice(0, Math.min(2, limit - selectedStashHits.length));
+    const selectedRefs = new Set(selectedStashHits.map((hit) => hit.ref));
     const items = [
-        ...(await Promise.all(selectedStashHits.slice(0, limit).map((hit) => enrichCuratedStashHit(query, hit)))),
+        ...(await Promise.all(selectedStashHits
+            .slice(0, limit)
+            .map((hit) => enrichCuratedStashHit(query, hit, supportRefsByRef.get(hit.ref) ?? [], selectedRefs)))),
         ...selectedRegistryHits.map((hit) => buildCuratedRegistryItem(query, hit)),
     ].slice(0, limit);
     return {
@@ -128,37 +137,7 @@ export async function curateSearchResults(query, result, limit, selectedType) {
         ...(result.tip ? { tip: result.tip } : {}),
     };
 }
-export function orderCuratedTypes(query, types) {
-    const lower = query.toLowerCase();
-    const boosts = new Map();
-    const addBoost = (type, amount) => boosts.set(type, (boosts.get(type) ?? 0) + amount);
-    if (/(run|script|bash|shell|cli|execute|automation|deploy|build|test|lint)/.test(lower)) {
-        addBoost("script", 6);
-        addBoost("command", 4);
-    }
-    if (/(guide|docs?|readme|reference|how|explain|learn|why)/.test(lower)) {
-        addBoost("knowledge", 6);
-        addBoost("skill", 4);
-    }
-    if (/(agent|assistant|planner|review|analy[sz]e|architect|prompt)/.test(lower)) {
-        addBoost("agent", 6);
-        addBoost("skill", 3);
-    }
-    if (/(config|template|release|generate|command)/.test(lower)) {
-        addBoost("command", 5);
-    }
-    if (/(memory|context|recall|remember)/.test(lower)) {
-        addBoost("memory", 6);
-    }
-    return [...types].sort((a, b) => {
-        const boostDiff = (boosts.get(b) ?? 0) - (boosts.get(a) ?? 0);
-        if (boostDiff !== 0)
-            return boostDiff;
-        return ((CURATED_TYPE_FALLBACK_INDEX.get(a) ?? Number.MAX_SAFE_INTEGER) -
-            (CURATED_TYPE_FALLBACK_INDEX.get(b) ?? Number.MAX_SAFE_INTEGER));
-    });
-}
-async function enrichCuratedStashHit(query, hit) {
+async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
     let shown;
     try {
         shown = await akmShowUnified({ ref: hit.ref });
@@ -168,6 +147,7 @@ async function enrichCuratedStashHit(query, hit) {
     }
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
+    const mergedSupportRefs = mergeCurateSupportRefs(supportRefs, shown?.related?.hits, selectedRefs, hit.ref);
     return {
         source: "stash",
         type: shown?.type ?? hit.type,
@@ -178,6 +158,7 @@ async function enrichCuratedStashHit(query, hit) {
         ...(shown?.keys?.length ? { keys: shown.keys } : {}),
         ...(shown?.parameters?.length ? { parameters: shown.parameters } : {}),
         ...(shown?.run ? { run: shown.run } : {}),
+        ...(mergedSupportRefs.length > 0 ? { supportRefs: mergedSupportRefs } : {}),
         followUp: `akm show ${hit.ref}`,
         reason: buildCuratedReason(query, shown?.type ?? hit.type),
         ...(hit.score !== undefined ? { score: hit.score } : {}),
@@ -209,19 +190,19 @@ function buildCuratedPreview(shown, hit) {
 function buildCuratedReason(query, type) {
     switch (type) {
         case "script":
-            return `Best runnable script match for "${query}".`;
+            return `Strong runnable script match for "${query}".`;
         case "command":
-            return `Best reusable command/template match for "${query}".`;
+            return `Strong reusable command/template match for "${query}".`;
         case "knowledge":
-            return `Best reference document match for "${query}".`;
+            return `Strong reference document match for "${query}".`;
         case "skill":
-            return `Best instructions/workflow match for "${query}".`;
+            return `Strong instructions/workflow match for "${query}".`;
         case "agent":
-            return `Best specialized agent prompt match for "${query}".`;
+            return `Strong specialized agent prompt match for "${query}".`;
         case "memory":
-            return `Best saved context match for "${query}".`;
+            return `Strong saved context match for "${query}".`;
         default:
-            return `Best ${type} match for "${query}".`;
+            return `Strong ${type} match for "${query}".`;
     }
 }
 function buildCurateSummary(query, items) {
@@ -229,27 +210,23 @@ function buildCurateSummary(query, items) {
         return `No curated assets were selected for "${query}".`;
     }
     const labels = items.map((item) => `${item.type}:${item.name}`);
-    return `Selected ${items.length} high-signal result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
+    return `Selected ${items.length} curated result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
 }
-function hasSearchResults(result) {
-    return result.hits.length > 0 || (result.registryHits?.length ?? 0) > 0;
-}
-/**
- * Extract a small set of fallback keywords when a prompt-style curate query
- * returns no hits as a whole phrase.
- *
- * We keep up to MAX_CURATE_FALLBACK_KEYWORDS distinct keywords and drop short
- * or common filler words so follow-up searches stay inexpensive while focusing
- * on higher-signal terms.
- */
 export function deriveCurateFallbackQueries(query) {
-    return Array.from(new Set(query
+    const normalizedWhole = query
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+    const tokens = Array.from(new Set(query
         .toLowerCase()
         .split(/[^a-z0-9]+/)
         .map((token) => token.trim())
-        // Keep longer tokens so fallback stays focused on higher-signal terms
-        // and avoids broad one- and two-letter matches that overwhelm curation.
-        .filter((token) => token.length >= MIN_CURATE_FALLBACK_TOKEN_LENGTH && !CURATE_FALLBACK_FILTER_WORDS.has(token)))).slice(0, MAX_CURATE_FALLBACK_KEYWORDS);
+        .filter((token) => token.length > 0 &&
+        !CURATE_FALLBACK_FILTER_WORDS.has(token) &&
+        (token.length >= MIN_CURATE_FALLBACK_TOKEN_LENGTH || CURATE_SHORT_FALLBACK_TOKENS.has(token))))).slice(0, MAX_CURATE_FALLBACK_KEYWORDS);
+    if (tokens.length === 1 && tokens[0] === normalizedWhole)
+        return [];
+    return tokens;
 }
 export function mergeCurateSearchResponses(base, extras) {
     const hitsByRef = new Map();
@@ -289,10 +266,10 @@ export function mergeCurateSearchResponses(base, extras) {
 }
 export async function searchForCuration(input) {
     const initial = await akmSearch({ ...input, skipLogging: true });
-    if (hasSearchResults(initial))
+    if (!shouldRunCurateFallback(initial, input.limit))
         return initial;
     const fallbackQueries = deriveCurateFallbackQueries(input.query);
-    if (fallbackQueries.length <= 1)
+    if (fallbackQueries.length === 0)
         return initial;
     const fallbackResults = await Promise.all(fallbackQueries.map((token) => akmSearch({
         query: token,
@@ -303,3 +280,241 @@ export async function searchForCuration(input) {
     })));
     return mergeCurateSearchResponses(initial, fallbackResults);
 }
+function parseCurateIntent(query) {
+    const lower = query.toLowerCase();
+    return {
+        executionHeavy: /(run|script|bash|shell|cli|execute|automation|deploy|build|test|lint)/.test(lower),
+        multiStep: /(plan|workflow|steps?|procedure|rollout|review|migration|release|checklist)/.test(lower),
+        delegation: /(agent|assistant|planner|reviewer|architect|prompt)/.test(lower),
+        recall: /(memory|context|recall|remember)/.test(lower),
+        reference: CURATE_REFERENCE_QUERY_RE.test(lower),
+    };
+}
+function computeCurateTypeNudge(type, intent) {
+    let nudge = 0;
+    if (intent.executionHeavy) {
+        if (type === "script")
+            nudge += 0.06;
+        else if (type === "command")
+            nudge += 0.04;
+        else if (type === "memory")
+            nudge -= 0.04;
+    }
+    if (intent.multiStep) {
+        if (type === "workflow")
+            nudge += 0.06;
+        else if (type === "skill")
+            nudge += 0.04;
+        else if (type === "knowledge")
+            nudge -= 0.02;
+    }
+    if (intent.delegation && type === "agent")
+        nudge += 0.06;
+    if (intent.recall && type === "memory")
+        nudge += 0.08;
+    if (intent.reference) {
+        if (type === "knowledge")
+            nudge += 0.05;
+        else if (type === "skill")
+            nudge += 0.02;
+    }
+    return nudge;
+}
+function getCurateFamily(ref) {
+    try {
+        const parsed = parseAssetRef(ref);
+        if (parsed.type === "skill") {
+            return { key: parsed.name, role: "root" };
+        }
+        if (parsed.type !== "knowledge")
+            return undefined;
+        const match = /^skills\/(.+?)\/references\/(.+)$/.exec(parsed.name);
+        if (!match)
+            return undefined;
+        return {
+            key: match[1],
+            role: "reference",
+            topicTokens: match[2]
+                .split(/[^a-z0-9]+/i)
+                .map((token) => token.trim().toLowerCase())
+                .filter(Boolean),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function annotateCurateHit(query, hit, index, intent) {
+    const rawScore = hit.score ?? 0;
+    const family = getCurateFamily(hit.ref);
+    let adjustedScore = rawScore + computeCurateTypeNudge(hit.type, intent);
+    if (family?.role === "root" && !isNarrowReferenceFamilyQuery(query, family))
+        adjustedScore += 0.07;
+    if (family?.role === "reference" && isNarrowReferenceFamilyQuery(query, family))
+        adjustedScore += 0.07;
+    return {
+        hit,
+        rawScore,
+        adjustedScore,
+        originalIndex: index,
+        family,
+    };
+}
+function compareCurateHits(a, b) {
+    const rawDiff = b.rawScore - a.rawScore;
+    if (Math.abs(rawDiff) > CURATE_CLOSE_SCORE_BAND)
+        return rawDiff;
+    const adjustedDiff = b.adjustedScore - a.adjustedScore;
+    if (adjustedDiff !== 0)
+        return adjustedDiff;
+    if (rawDiff !== 0)
+        return rawDiff;
+    return a.originalIndex - b.originalIndex;
+}
+function passesCurateScoreFloor(hit, leaderScore) {
+    if (leaderScore === undefined)
+        return true;
+    return hit.rawScore >= Math.max(CURATE_TAIL_SCORE_FLOOR, leaderScore * CURATE_RELATIVE_SCORE_FLOOR);
+}
+function isNarrowReferenceFamilyQuery(query, family) {
+    if (!family || family.role !== "reference")
+        return false;
+    const lower = query.toLowerCase();
+    if (CURATE_REFERENCE_QUERY_RE.test(lower))
+        return true;
+    return family.topicTokens.some((token) => token.length >= 3 && lower.includes(token));
+}
+function appendCurateSupportRef(supportRefsByRef, ownerRef, supportRef) {
+    const existing = supportRefsByRef.get(ownerRef) ?? [];
+    if (existing.some((entry) => entry.ref === supportRef.ref))
+        return;
+    supportRefsByRef.set(ownerRef, [...existing, supportRef]);
+}
+function selectCuratedStashHits(query, hits, limit) {
+    const intent = parseCurateIntent(query);
+    const collapsed = collapseCurateFamilies(query, hits);
+    const ranked = collapsed.hits
+        .map(({ hit, originalIndex }) => annotateCurateHit(query, hit, originalIndex, intent))
+        .sort(compareCurateHits);
+    const selected = [];
+    const supportRefsByRef = collapsed.supportRefsByRef;
+    let leaderScore;
+    for (const candidate of ranked) {
+        if (!passesCurateScoreFloor(candidate, leaderScore))
+            continue;
+        selected.push(candidate);
+        if (leaderScore === undefined)
+            leaderScore = candidate.rawScore;
+        if (selected.length >= limit)
+            break;
+    }
+    return { selected: selected.map((entry) => entry.hit), supportRefsByRef };
+}
+function collapseCurateFamilies(query, hits) {
+    const passthrough = [];
+    const supportRefsByRef = new Map();
+    const groups = new Map();
+    for (const [index, hit] of hits.entries()) {
+        const family = getCurateFamily(hit.ref);
+        if (!family) {
+            passthrough.push({ hit, originalIndex: index });
+            continue;
+        }
+        const group = groups.get(family.key) ?? { references: [] };
+        if (family.role === "root") {
+            if (!group.root)
+                group.root = { hit, originalIndex: index };
+        }
+        else {
+            group.references.push({ hit, originalIndex: index });
+        }
+        groups.set(family.key, group);
+    }
+    const collapsedFamilies = [];
+    for (const group of groups.values()) {
+        const bestReference = group.references[0];
+        const representative = group.root && !isNarrowReferenceFamilyQuery(query, getCurateFamily(bestReference?.hit.ref ?? group.root.hit.ref))
+            ? group.root
+            : (bestReference ?? group.root);
+        if (!representative)
+            continue;
+        collapsedFamilies.push(representative);
+        const supportCandidates = [group.root, ...group.references].filter((entry) => {
+            return entry !== undefined && entry.hit.ref !== representative.hit.ref;
+        });
+        for (const support of supportCandidates) {
+            appendCurateSupportRef(supportRefsByRef, representative.hit.ref, {
+                ref: support.hit.ref,
+                type: support.hit.type,
+                reason: "Related family asset to inspect next.",
+            });
+        }
+    }
+    return {
+        hits: [...passthrough, ...collapsedFamilies].sort((a, b) => a.originalIndex - b.originalIndex),
+        supportRefsByRef,
+    };
+}
+function preferBroadRootRepresentative(query, selected, allHits, supportRefsByRef) {
+    const first = selected[0];
+    if (!first)
+        return { selected, supportRefsByRef };
+    const match = /^knowledge:skills\/(.+?)\/references\/(.+)$/.exec(first.ref);
+    if (!match)
+        return { selected, supportRefsByRef };
+    const lower = query.toLowerCase();
+    const topicTokens = match[2].split(/[^a-z0-9]+/i).filter(Boolean);
+    const wantsReference = CURATE_REFERENCE_QUERY_RE.test(lower) ||
+        topicTokens.some((token) => token.length >= 3 && lower.includes(token.toLowerCase()));
+    if (wantsReference)
+        return { selected, supportRefsByRef };
+    const rootRef = `skill:${match[1]}`;
+    const rootHit = allHits.find((hit) => hit.ref === rootRef);
+    if (!rootHit)
+        return { selected, supportRefsByRef };
+    const next = [rootHit, ...selected.filter((hit) => hit.ref !== first.ref && hit.ref !== rootRef)];
+    const merged = new Map(supportRefsByRef);
+    const priorSupport = merged.get(first.ref) ?? [];
+    for (const entry of priorSupport)
+        appendCurateSupportRef(merged, rootRef, entry);
+    appendCurateSupportRef(merged, rootRef, {
+        ref: first.ref,
+        type: first.type,
+        reason: "Related family asset to inspect next.",
+    });
+    merged.delete(first.ref);
+    return { selected: next, supportRefsByRef: merged };
+}
+function mergeCurateSupportRefs(seeded, relatedHits, selectedRefs, ownerRef) {
+    const merged = [];
+    for (const entry of seeded) {
+        if (entry.ref === ownerRef || selectedRefs.has(entry.ref))
+            continue;
+        if (merged.some((existing) => existing.ref === entry.ref))
+            continue;
+        merged.push(entry);
+        if (merged.length >= MAX_CURATE_SUPPORT_REFS)
+            return merged;
+    }
+    if (!Array.isArray(relatedHits))
+        return merged;
+    for (const hit of relatedHits) {
+        if (!hit.ref || hit.ref === ownerRef || selectedRefs.has(hit.ref))
+            continue;
+        if (merged.some((existing) => existing.ref === hit.ref))
+            continue;
+        merged.push({ ref: hit.ref, type: hit.type, reason: "Related asset via shared entities." });
+        if (merged.length >= MAX_CURATE_SUPPORT_REFS)
+            break;
+    }
+    return merged;
+}
+function shouldRunCurateFallback(initial, desiredCount) {
+    const stashHits = initial.hits.filter((hit) => hit.type !== "registry");
+    if (stashHits.length === 0)
+        return true;
+    const topScore = stashHits[0]?.score ?? 0;
+    const strongFloor = Math.max(CURATE_FALLBACK_STRONG_SCORE_FLOOR, topScore * CURATE_RELATIVE_SCORE_FLOOR);
+    const strongCount = stashHits.filter((hit) => (hit.score ?? 0) >= strongFloor).length;
+    return !(topScore >= CURATE_FALLBACK_TOP_SCORE_THRESHOLD && strongCount >= Math.min(2, desiredCount));
+}

package/dist/commands/read/search-cli.js

@@ -63,6 +63,11 @@ export const searchCommand = defineJsonCommand({
             description: "Disable the automatic project-context ranking boost (also disabled by AKM_DISABLE_PROJECT_CONTEXT=1).",
             default: false,
         },
+        "include-sessions": {
+            type: "boolean",
+            description: "Include session assets (excluded from default search results via config.search.defaultExcludeTypes).",
+            default: false,
+        },
     },
     async run({ args }) {
         const query = (args.query ?? "").trim();
@@ -79,6 +84,7 @@ export const searchCommand = defineJsonCommand({
         const includeProposed = args["include-proposed"] === true;
         const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
         const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
+        const includeSessions = getHyphenatedBoolean(args, "include-sessions");
         // --no-project-context sets env so searchDatabase picks it up without
         // threading the flag through the entire call stack.
         if (noProjectContext)
@@ -91,6 +97,7 @@ export const searchCommand = defineJsonCommand({
             filters,
             includeProposed,
             belief,
+            includeSessions,
             eventSource: resolveEventSource(),
         });
         output("search", result);

package/dist/commands/read/search.js

@@ -108,6 +108,7 @@ export async function akmSearch(input) {
             // Without this, the index (which spans every configured source)
             // would leak hits from sources the caller did not request.
             restrictToSources: namedSourceName !== undefined,
+            includeExcludedTypes: input.includeSessions === true,
         });
     const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
     if (source === "stash") {

package/dist/commands/remember.js

@@ -149,6 +149,10 @@ export async function runLlmEnrich(body) {
         return { tags: [] };
     }
     const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client.js");
+    // #576: attribute this entry point's LLM call to the `remember` stage. The
+    // wrapper is ambient — if a usage sink is active it tags the record; if not,
+    // it is a no-op.
+    const { withLlmStage } = await import("../llm/usage-telemetry.js");
     const prompt = `You are a memory tagger for a developer knowledge base.
 Given the memory text below, return ONLY a JSON object with these fields:
 - "tags": array of 1-5 short lowercase keyword tags
@@ -164,10 +168,10 @@ Return ONLY the JSON object, no prose, no markdown fences.`;
         const result = await (async () => {
             try {
                 return await Promise.race([
-                    chatCompletion(llmConfig, [
+                    withLlmStage("remember", () => chatCompletion(llmConfig, [
                         { role: "system", content: "Return only valid JSON. No prose." },
                         { role: "user", content: prompt },
-                    ], { maxTokens: 256, temperature: 0.1 }),
+                    ], { maxTokens: 256, temperature: 0.1 })),
                     new Promise((_, reject) => {
                         timeoutHandle = setTimeout(() => reject(new Error("LLM enrichment timed out")), LLM_ENRICH_TIMEOUT_MS);
                     }),

package/dist/commands/sources/installed-stashes.js

@@ -205,7 +205,11 @@ async function updateRegistryEntry(entry, force) {
     const synced = await syncFromRef(entry.ref, { force });
     const installedEntry = {
         id: synced.id,
-        source: synced.source,
+        // Preserve the original source classification. syncFromRef() re-derives the
+        // source type from the ref scheme (e.g. "github:" → source: "github"), but
+        // an update should not reclassify an existing entry. A writable entry stored
+        // as source: "git" would fail config validation if rewritten to "github".
+        source: entry.source,
         ref: synced.ref,
         artifactUrl: synced.artifactUrl,
         resolvedVersion: synced.resolvedVersion,

package/dist/commands/sources/stash-cli.js

@@ -71,6 +71,11 @@ export const indexCommand = defineCommand({
             description: "When combined with --clean, report stale entries without deleting them.",
             default: false,
         },
+        background: {
+            type: "boolean",
+            description: "Run as a background process (suppresses interactive output, manages PID file).",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -80,6 +85,7 @@ export const indexCommand = defineCommand({
             if (getHyphenatedBoolean(args, "re-enrich") || parseFlagValue(process.argv, "--re-enrich") !== undefined) {
                 throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
             }
+            const isBackground = args.background === true;
             const outputMode = getOutputMode();
             const controller = new AbortController();
             const abort = () => controller.abort(new Error("index interrupted"));
@@ -88,7 +94,7 @@ export const indexCommand = defineCommand({
             const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
             setLogFile(indexLogFile);
             const verbose = isVerbose();
-            const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
+            const spin = !verbose && !isBackground && outputMode.format === "text" ? p.spinner() : null;
             if (spin) {
                 spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
             }
@@ -114,7 +120,9 @@ export const indexCommand = defineCommand({
                 if (spin) {
                     spin.stop(`Indexed ${result.totalEntries} assets.`);
                 }
-                output("index", result);
+                if (!isBackground) {
+                    output("index", result);
+                }
             }
             catch (error) {
                 if (spin) {