akm-cli 0.5.0 → 0.6.0-rc2

package/dist/commands/remember.js

@@ -0,0 +1,178 @@
+/**
+ * Memory-specific helpers for `akm remember`.
+ *
+ * Extracted from `src/cli.ts` so the domain logic (frontmatter assembly,
+ * heuristic derivation, LLM enrichment) is testable in isolation and the
+ * CLI entry point stays focused on argument parsing + output routing.
+ */
+import { stringify as yamlStringify } from "yaml";
+import { toErrorMessage, tryReadStdinText } from "../core/common";
+import { loadConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { warn } from "../core/warn";
+/**
+ * Parse a shorthand duration string to a number of milliseconds.
+ * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
+ */
+export function parseDuration(s) {
+    const match = s.trim().match(/^(\d+)([dhm])$/i);
+    if (!match)
+        throw new UsageError(`Invalid --expires format "${s}". Use shorthand like 30d, 12h, or 6m.`, "INVALID_FLAG_VALUE");
+    const n = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    if (unit === "d")
+        return n * 24 * 60 * 60 * 1000;
+    if (unit === "h")
+        return n * 60 * 60 * 1000;
+    // 'm' = months, approximated as 30 days
+    return n * 30 * 24 * 60 * 60 * 1000;
+}
+/**
+ * Build a YAML frontmatter block from memory metadata.
+ *
+ * Uses `yaml.stringify` so values containing newlines, colons, or other
+ * YAML metacharacters are safely quoted. The previous implementation
+ * interpolated user input directly into `key: value` lines, which let a
+ * `description` containing `\n` + `tags: [x]` inject additional keys into
+ * the frontmatter — that is no longer possible here.
+ *
+ * Only includes fields that are present (non-empty).
+ */
+export function buildMemoryFrontmatter(fields) {
+    const obj = {};
+    if (fields.description?.trim())
+        obj.description = fields.description;
+    if (fields.tags && fields.tags.length > 0)
+        obj.tags = fields.tags;
+    if (fields.source?.trim())
+        obj.source = fields.source;
+    if (fields.observed_at?.trim())
+        obj.observed_at = fields.observed_at;
+    if (fields.expires?.trim())
+        obj.expires = fields.expires;
+    if (fields.subjective)
+        obj.subjective = true;
+    // No fields populated → emit a bare delimiter pair so callers don't
+    // produce `---\n{}\n---` (the YAML serializer's empty-object form).
+    if (Object.keys(obj).length === 0)
+        return "---\n---";
+    const serialized = yamlStringify(obj).trimEnd();
+    return `---\n${serialized}\n---`;
+}
+/**
+ * Read memory content from the positional arg or stdin.
+ * Throws {@link UsageError} if neither is populated.
+ */
+export function readMemoryContent(contentArg) {
+    const content = contentArg ?? tryReadStdinText();
+    if (!content?.trim()) {
+        throw new UsageError("Memory content is required. Pass quoted text or pipe markdown into stdin.");
+    }
+    return content;
+}
+/**
+ * Run heuristic analysis on memory body text. Returns derived metadata
+ * fields without modifying any files. Pure TS, zero network, zero latency.
+ */
+export function runAutoHeuristics(body) {
+    const tags = [];
+    // Fenced code block present → tag "code"
+    if (/^```/m.test(body)) {
+        tags.push("code");
+    }
+    // First-person pronoun → subjective
+    const subjective = /\b(I|we|my|our)\b/.test(body) ? true : undefined;
+    // First URL-shaped token → source
+    const urlMatch = body.match(/https?:\/\/[^\s)>'"]+/);
+    const source = urlMatch ? urlMatch[0] : undefined;
+    // ISO date token or obvious relative date phrase → observed_at
+    const observed_at = detectObservedAt(body);
+    return { tags, source, observed_at, subjective };
+}
+const RELATIVE_DATE_OFFSETS = {
+    today: () => { },
+    yesterday: (d) => d.setDate(d.getDate() - 1),
+    "last week": (d) => d.setDate(d.getDate() - 7),
+    "last month": (d) => d.setMonth(d.getMonth() - 1),
+};
+function detectObservedAt(body) {
+    const isoMatch = body.match(/\b(\d{4}-\d{2}-\d{2})\b/);
+    if (isoMatch)
+        return isoMatch[1];
+    const relMatch = body.match(/\b(today|yesterday|last\s+week|last\s+month)\b/i);
+    if (!relMatch)
+        return undefined;
+    // Normalise the matched phrase: lowercase, collapse internal whitespace,
+    // so "last  week" matches the lookup table key.
+    const phrase = relMatch[1].toLowerCase().replace(/\s+/g, " ");
+    const offset = RELATIVE_DATE_OFFSETS[phrase];
+    if (!offset)
+        return undefined;
+    const d = new Date();
+    offset(d);
+    return d.toISOString().slice(0, 10);
+}
+/** Hard timeout for the `--enrich` LLM call. Write-path must not block on a misbehaving endpoint. */
+const LLM_ENRICH_TIMEOUT_MS = 10_000;
+/**
+ * Attempt LLM enrichment of memory metadata. Returns merged metadata
+ * fields on success. On timeout, unreachable, or invalid JSON — returns
+ * empty result and emits a warning. Never throws; always resolves.
+ */
+export async function runLlmEnrich(body) {
+    const config = loadConfig();
+    if (!config.llm) {
+        warn("Warning: --enrich requires an LLM to be configured. Run `akm config set llm` to configure one.");
+        return { tags: [] };
+    }
+    const llmConfig = config.llm;
+    const { chatCompletion, parseJsonResponse } = await import("../llm/client");
+    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
+- "description": one-sentence summary (optional)
+- "observed_at": ISO date (YYYY-MM-DD) if the text references a specific date (optional)
+
+Memory text:
+${body.slice(0, 2000)}
+
+Return ONLY the JSON object, no prose, no markdown fences.`;
+    try {
+        let timeoutHandle;
+        const result = await (async () => {
+            try {
+                return await Promise.race([
+                    chatCompletion(llmConfig, [
+                        { role: "system", content: "Return only valid JSON. No prose." },
+                        { role: "user", content: prompt },
+                    ], { maxTokens: 256, temperature: 0.1 }),
+                    new Promise((_, reject) => {
+                        timeoutHandle = setTimeout(() => reject(new Error("LLM enrichment timed out")), LLM_ENRICH_TIMEOUT_MS);
+                    }),
+                ]);
+            }
+            finally {
+                if (timeoutHandle !== undefined) {
+                    clearTimeout(timeoutHandle);
+                }
+            }
+        })();
+        const parsed = parseJsonResponse(result);
+        if (!parsed) {
+            warn("Warning: --enrich received invalid JSON from the LLM. Writing memory without enrichment.");
+            return { tags: [] };
+        }
+        const tags = Array.isArray(parsed.tags)
+            ? parsed.tags.filter((t) => typeof t === "string" && t.trim().length > 0)
+            : [];
+        const description = typeof parsed.description === "string" && parsed.description.trim() ? parsed.description.trim() : undefined;
+        const observed_at = typeof parsed.observed_at === "string" && /^\d{4}-\d{2}-\d{2}$/.test(parsed.observed_at.trim())
+            ? parsed.observed_at.trim()
+            : undefined;
+        return { tags, description, observed_at };
+    }
+    catch (err) {
+        warn(`Warning: --enrich failed (${toErrorMessage(err)}). Writing memory without enrichment.`);
+        return { tags: [] };
+    }
+}

package/dist/{stash-search.js → commands/search.js}

@@ -1,13 +1,23 @@
-import { loadConfig } from "./config";
-import { closeDatabase, openDatabase } from "./db";
-import { searchLocal } from "./local-search";
-import { resolveStashProviders } from "./stash-provider-factory";
-// Eagerly import stash providers to trigger self-registration
-import "./stash-providers/index";
-import { UsageError } from "./errors";
+/**
+ * `akm search` — entry point.
+ *
+ * Spec §6.1: search consults the local FTS5 index. There is one query path
+ * because there is one data store. Provider fan-out is gone.
+ *
+ * The orchestration here is thin: build the FTS query, optionally interleave
+ * a registry search behind `--source registry|both`, and log a usage event.
+ * Provider `search()` methods do not exist.
+ */
+import { loadConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { closeDatabase, openDatabase } from "../indexer/db";
+import { searchLocal } from "../indexer/db-search";
+import { resolveSourceEntries } from "../indexer/search-source";
+// Eagerly import source providers to trigger self-registration before the
+// indexer or path-resolution code runs.
+import "../sources/providers/index";
+import { insertUsageEvent } from "../indexer/usage-events";
 import { searchRegistry } from "./registry-search";
-import { resolveStashSources } from "./search-source";
-import { insertUsageEvent } from "./usage-events";
 const DEFAULT_LIMIT = 20;
 export async function akmSearch(input) {
     const t0 = Date.now();
@@ -17,7 +27,7 @@ export async function akmSearch(input) {
     const limit = normalizeLimit(input.limit);
     const source = parseSearchSource(input.source ?? "stash");
     const config = loadConfig();
-    const sources = resolveStashSources(undefined, config);
+    const sources = resolveSourceEntries(undefined, config);
     if (sources.length === 0) {
         // stashDir: "" is a safe sentinel here — the response carries zero hits
         // and a warning, so no downstream code will try to use the empty path.
@@ -35,10 +45,6 @@ export async function akmSearch(input) {
     // Primary stash directory — used for DB path lookups and as the default
     // stash root. Safe because the empty-sources case is handled above.
     const stashDir = sources[0].path;
-    // Resolve additional stash providers (e.g. OpenViking) from config.
-    // Exclude filesystem (handled by resolveStashSources) and context-hub/github
-    // (content now indexed through the unified FTS5 pipeline).
-    const additionalStashProviders = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && p.type !== "context-hub" && p.type !== "git");
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({
@@ -49,35 +55,17 @@ export async function akmSearch(input) {
             sources,
             config,
         });
-    // Pass original case to providers — FTS5 requires lowercase but remote providers handle case themselves
-    const additionalStashResults = source === "registry" || additionalStashProviders.length === 0
-        ? []
-        : await Promise.all(additionalStashProviders.map(async (provider) => {
-            try {
-                return await provider.search({ query, type: searchType === "any" ? undefined : searchType, limit });
-            }
-            catch (err) {
-                return {
-                    hits: [],
-                    warnings: [`Stash ${provider.name}: ${err instanceof Error ? err.message : String(err)}`],
-                };
-            }
-        }));
-    // Merge stash hits from all providers
-    const additionalHits = additionalStashResults.flatMap((r) => r.hits);
-    const additionalWarnings = additionalStashResults.flatMap((r) => r.warnings ?? []);
     const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
     if (source === "stash") {
-        const allStashHits = mergeStashHits(localResult?.hits ?? [], additionalHits, limit);
-        const localWarnings = [...(localResult?.warnings ?? []), ...additionalWarnings];
-        const hasResults = allStashHits.length > 0;
+        const localHits = localResult?.hits ?? [];
+        const hasResults = localHits.length > 0;
         const response = {
             schemaVersion: 1,
             stashDir,
             source,
-            hits: allStashHits,
+            hits: localHits,
             tip: hasResults ? undefined : localResult?.tip,
-            warnings: localWarnings.length > 0 ? localWarnings : undefined,
+            warnings: localResult?.warnings?.length ? localResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
         logSearchEvent(query, response);
@@ -116,14 +104,14 @@ export async function akmSearch(input) {
         return response;
     }
     // source === "both"
-    const allStashHits = mergeStashHits(localResult?.hits ?? [], additionalHits, limit * 2);
-    const warnings = [...(localResult?.warnings ?? []), ...additionalWarnings, ...(registryResult?.warnings ?? [])];
+    const allStashHits = (localResult?.hits ?? []).slice(0, limit);
+    const warnings = [...(localResult?.warnings ?? []), ...(registryResult?.warnings ?? [])];
     const hasResults = allStashHits.length > 0 || registryHits.length > 0;
     const response = {
         schemaVersion: 1,
         stashDir,
         source,
-        hits: allStashHits.slice(0, limit),
+        hits: allStashHits,
         registryHits,
         tip: hasResults ? undefined : "No matching stash assets or registry entries were found.",
         warnings: warnings.length ? warnings : undefined,
@@ -184,35 +172,6 @@ function logSearchEvent(query, response, existingDb) {
     }
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
-/**
- * Merge local and additional stash hits into a single ranked list.
- *
- * Provider hits (e.g. OpenViking) keep their original scores and compete
- * fairly alongside local hits. Duplicates are resolved in favour of the
- * local version.
- *
- * 1. Build set of local hit keys for dedup.
- * 2. Filter provider hits that aren't duplicates.
- * 3. Combine local + non-duplicate provider hits.
- * 4. Sort by score descending.
- * 5. Slice to limit.
- */
-export function mergeStashHits(localHits, additionalHits, limit) {
-    if (additionalHits.length === 0)
-        return localHits.slice(0, limit);
-    // Track local hits by a dedup key (path > ref > name)
-    const localKeys = new Set();
-    for (const h of localHits) {
-        localKeys.add(h.path ?? h.ref ?? h.name);
-    }
-    // Keep non-duplicate provider hits with their original scores
-    const providerOnly = additionalHits.filter((h) => {
-        const key = h.path ?? h.ref ?? h.name;
-        return !localKeys.has(key);
-    });
-    // Combine and sort by score descending
-    return [...localHits, ...providerOnly].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, limit);
-}
 function normalizeLimit(limit) {
     if (typeof limit !== "number" || Number.isNaN(limit) || limit <= 0) {
         return DEFAULT_LIMIT;
@@ -227,7 +186,7 @@ export function parseSearchSource(source) {
         return "stash";
     if (typeof source === "undefined")
         return "stash";
-    throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`);
+    throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`, "INVALID_SOURCE_VALUE");
 }
 /**
  * Merge stash hits and registry hits via simple concatenation.

package/dist/{self-update.js → commands/self-update.js}

@@ -2,8 +2,8 @@ import * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, IS_WINDOWS } from "./common";
-import { githubHeaders } from "./github";
+import { fetchWithRetry, IS_WINDOWS } from "../core/common";
+import { githubHeaders } from "../integrations/github";
 const REPO = "itlackey/akm";
 const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
@@ -303,7 +303,7 @@ function normalizePathSeparators(value) {
 }
 function getInstalledPackageName() {
     try {
-        const pkgPath = path.resolve(import.meta.dir ?? __dirname, "../package.json");
+        const pkgPath = path.resolve(import.meta.dir ?? __dirname, "../../package.json");
         if (fs.existsSync(pkgPath)) {
             const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
             if (typeof pkg.name === "string" && pkg.name.trim()) {

package/dist/{stash-show.js → commands/show.js}

@@ -1,31 +1,47 @@
+/**
+ * `akm show` — entry point.
+ *
+ * Spec §6.2:
+ *
+ *   show(ref) → indexer.lookup(ref) → readFile(entry.filePath)
+ *
+ * The richer presentation logic (matchers, renderers, wiki-root handling,
+ * edit-hints, summary-detail truncation) lives below in this file. The flow:
+ *
+ *   1. Special-case wiki-root refs (`wiki:<name>` with no page path).
+ *   2. Ask `indexer.lookup(ref)` for the row in the FTS index.
+ *   3. Fall back to the on-disk type-dir resolver only when the index has
+ *      no matching row — covers the "indexed yet?" gap when the user has
+ *      just added a file and not run `akm index`.
+ *   4. Render the file via the matcher/renderer pipeline.
+ *
+ * Step (2) is the v1 spec change: reading is the indexer's job. Step (3) is a
+ * pragmatic safety net (NOT remote provider fallback, which the spec
+ * forbids — "Show: Local FTS5 index only. No remote provider fallback.").
+ */
 import fs from "node:fs";
 import path from "node:path";
-import { loadConfig } from "./config";
-import { closeDatabase, openDatabase } from "./db";
-import { NotFoundError, UsageError } from "./errors";
-import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-import { loadStashFile } from "./metadata";
-import { resolveSourcesForOrigin } from "./origin-resolve";
-import { buildEditHint, findSourceForPath, isEditable, resolveStashSources } from "./search-source";
-import { resolveStashProviders } from "./stash-provider-factory";
-import { parseAssetRef } from "./stash-ref";
-import { resolveAssetPath } from "./stash-resolve";
-import { insertUsageEvent } from "./usage-events";
-// Eagerly import stash providers to trigger self-registration
-import "./stash-providers/index";
+import { parseAssetRef } from "../core/asset-ref";
+import { loadConfig } from "../core/config";
+import { NotFoundError, UsageError } from "../core/errors";
+import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
+import { closeDatabase, openDatabase } from "../indexer/db";
+import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
+import { lookup } from "../indexer/indexer";
+import { loadStashFile } from "../indexer/metadata";
+import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve";
+// Eagerly import source providers to trigger self-registration.
+import "../sources/providers/index";
+import { insertUsageEvent } from "../indexer/usage-events";
+import { resolveAssetPath } from "../sources/resolve";
 /**
  * Show a wiki root (no page path) — returns the same payload as
  * `akm wiki show <name>`.
- *
- * Called when `parseAssetRef` yields `type === "wiki"` and the name has no
- * `/`, e.g. `wiki:research`.
  */
 async function showWikiRoot(stashDir, wikiName) {
-    const { showWiki } = await import("./wiki.js");
+    const { showWiki } = await import("../wiki/wiki.js");
     const result = showWiki(stashDir, wikiName);
-    // Shape the WikiShowResult into a ShowResponse-compatible object.
-    // The payload mirrors what `akm wiki show <name>` returns.
     return {
         type: "wiki",
         name: result.ref,
@@ -40,7 +56,7 @@ async function showWikiRoot(stashDir, wikiName) {
     };
 }
 async function showWikiRootForSource(stashDir, source, wikiName) {
-    const { showWikiAtPath } = await import("./wiki.js");
+    const { showWikiAtPath } = await import("../wiki/wiki.js");
     if (source.wikiName === wikiName) {
         const result = showWikiAtPath(wikiName, source.path);
         return {
@@ -66,19 +82,21 @@ function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
     const candidate = path.resolve(wikiRoot, `${pageName}.md`);
     const resolvedRoot = fs.realpathSync(wikiRoot);
     if (!candidate.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
         throw new NotFoundError(`Stash asset not found for ref: wiki:${assetName}`);
     }
     const realTarget = fs.realpathSync(candidate);
     if (!realTarget.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     return realTarget;
 }
 /**
- * Unified show: tries local FTS5 index first, then remote providers.
+ * Unified show: queries the local FTS5 index, then falls back to on-disk
+ * type-dir resolution if the index has no row. Spec §6.2; no remote provider
+ * fallback.
  *
  * When `detail` is `"summary"`, the response omits content/template/prompt and
  * returns only compact metadata (name, type, description, tags, parameters).
@@ -92,7 +110,7 @@ export async function akmShowUnified(input) {
     {
         const parsed = parseAssetRef(ref);
         if (parsed.type === "wiki" && !parsed.name.includes("/")) {
-            const allSources = resolveStashSources();
+            const allSources = resolveSourceEntries();
             const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
             let lastError;
             for (const source of searchSources) {
@@ -109,43 +127,11 @@ export async function akmShowUnified(input) {
                 new NotFoundError(`Wiki not found: ${parsed.name}. Run \`akm wiki create ${parsed.name}\` to create it.`));
         }
     }
-    // 1. Try local filesystem first (FTS5 index lookup)
-    let localError;
-    try {
-        const result = await showLocal(input);
-        logShowEvent(ref);
-        return result;
-    }
-    catch (err) {
-        // Only fall through to remote providers on NotFoundError
-        if (!(err instanceof NotFoundError))
-            throw err;
-        localError = err;
-    }
-    // 2. Try remote providers (e.g. OpenViking)
-    const config = loadConfig();
-    const providers = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && p.canShow(ref));
-    for (const provider of providers) {
-        try {
-            const response = await provider.show(ref, input.view);
-            logShowEvent(ref);
-            if (input.detail === "summary") {
-                return buildSummaryResponse(response);
-            }
-            return response;
-        }
-        catch (err) {
-            if (!(err instanceof NotFoundError))
-                throw err;
-        }
-    }
-    // Nothing found anywhere — rethrow the original local error with its specific message
-    throw localError;
+    // Try local filesystem (FTS5 index lookup, then on-disk fallback)
+    const result = await showLocal(input);
+    logShowEvent(ref);
+    return result;
 }
-/**
- * Fire-and-forget: log a show event to the usage_events table.
- * Never blocks the caller; errors are silently ignored.
- */
 function logShowEvent(ref, existingDb) {
     try {
         const db = existingDb ?? openDatabase();
@@ -170,14 +156,48 @@ function logShowEvent(ref, existingDb) {
         /* fire-and-forget */
     }
 }
+/**
+ * Resolve an asset path to a file via:
+ *   1. `indexer.lookup(ref)` — the spec's primary path (§6.2).
+ *   2. On-disk type-dir traversal — fallback for files not yet indexed.
+ *
+ * Returns `undefined` if neither path finds a match.
+ */
+async function resolvePathViaIndexThenDisk(parsed, searchSourceDirs) {
+    // Step 1: indexer
+    try {
+        const entry = await lookup(parsed);
+        if (entry) {
+            return { assetPath: entry.filePath };
+        }
+    }
+    catch (err) {
+        // Index unavailable (e.g. DB doesn't exist yet) — fall back to disk walk.
+        if (!(err instanceof NotFoundError)) {
+            // continue to disk fallback
+        }
+    }
+    // Step 2: on-disk type-dir traversal
+    let lastError;
+    for (const dir of searchSourceDirs) {
+        try {
+            const assetPath = await resolveAssetPath(dir, parsed.type, parsed.name);
+            return { assetPath, lastError };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    return lastError ? { assetPath: "", lastError } : undefined;
+}
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
     const parsed = parseAssetRef(input.ref);
     const displayType = parsed.type;
     const config = loadConfig();
-    const allSources = resolveStashSources(input.stashDir);
+    const allSources = resolveSourceEntries(input.stashDir);
     const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    const allStashDirs = searchSources.map((s) => s.path);
+    const allSourceDirs = searchSources.map((s) => s.path);
     let assetPath;
     const matchedSource = parsed.type === "wiki" ? searchSources.find((source) => parsed.name.startsWith(`${source.wikiName}/`)) : undefined;
     let lastError;
@@ -189,21 +209,19 @@ export async function showLocal(input) {
             lastError = err instanceof Error ? err : new Error(String(err));
         }
     }
-    for (const dir of allStashDirs) {
-        if (assetPath)
-            break;
-        try {
-            assetPath = await resolveAssetPath(dir, parsed.type, parsed.name);
-            break;
+    if (!assetPath) {
+        const resolved = await resolvePathViaIndexThenDisk(parsed, allSourceDirs);
+        if (resolved?.assetPath) {
+            assetPath = resolved.assetPath;
         }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
+        else if (resolved?.lastError) {
+            lastError = resolved.lastError;
         }
     }
     if (!assetPath && parsed.origin && searchSources.length === 0) {
         const installCmd = `akm add ${parsed.origin}`;
         throw new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
-            `Kit "${parsed.origin}" is not installed. Run: ${installCmd}`);
+            `Stash "${parsed.origin}" is not installed. Run: ${installCmd}`);
     }
     if (!assetPath) {
         throw (lastError ??
@@ -211,7 +229,7 @@ export async function showLocal(input) {
                 "Check the name with `akm search` or verify the asset exists in your stash."));
     }
     const source = matchedSource ?? findSourceForPath(assetPath, allSources);
-    const sourceStashDir = source?.path ?? allStashDirs[0];
+    const sourceStashDir = source?.path ?? allSourceDirs[0];
     if (!sourceStashDir) {
         throw new UsageError(`Could not determine stash root for asset: ${displayType}:${parsed.name}. ` +
             "Run `akm init` to create the stash directory, or check `akm stash list` for configured paths.");
@@ -229,7 +247,7 @@ export async function showLocal(input) {
     if (!renderer) {
         throw new UsageError(`Renderer "${match.renderer}" not found for asset: ${displayType}:${parsed.name}`);
     }
-    const renderCtx = buildRenderContext(fileCtx, match, allStashDirs, source?.registryId);
+    const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, source?.registryId);
     const response = renderer.buildShowResponse(renderCtx);
     const editable = isEditable(assetPath, config);
     const fullResponse = {
@@ -243,6 +261,20 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/**
+ * Minimal `show`: ref → indexer lookup → file contents. Used by callers that
+ * just need the raw file (e.g. clone, write-source) and don't want the full
+ * renderer graph. Spec §6.2's literal flow.
+ */
+export async function showByRef(ref) {
+    const parsed = parseAssetRef(ref);
+    const entry = await lookup(parsed);
+    if (!entry) {
+        throw new NotFoundError(`Asset not found for ref: ${parsed.type}:${parsed.name}`);
+    }
+    const body = await fs.promises.readFile(entry.filePath, "utf8");
+    return { filePath: entry.filePath, body };
+}
 /**
  * Build a compact summary response from a full ShowResponse.
  *
@@ -250,24 +282,17 @@ export async function showLocal(input) {
  * type, name, path, description, tags, parameters, action.
  * Enriches description and tags from frontmatter or .stash.json when available.
  *
- * Enrichment via frontmatter and .stash.json is only performed when `assetPath`
- * is supplied (local assets). Remote provider responses (e.g. OpenViking) rely
- * on the provider having already populated description and tags.
- *
  * The resulting JSON should be under 200 tokens.
  */
 function buildSummaryResponse(full, assetPath) {
-    // Try to enrich metadata from .stash.json if description or tags are missing
     let description = full.description;
     let tags = full.tags;
     if (assetPath) {
-        // Try frontmatter extraction from content fields
         const textContent = full.content ?? full.template ?? full.prompt;
         if (textContent && !description) {
             const parsed = parseFrontmatter(textContent);
             description = toStringOrUndefined(parsed.data.description);
         }
-        // Try .stash.json for richer metadata (tags especially)
         const dir = path.dirname(assetPath);
         const stashFile = loadStashFile(dir);
         if (stashFile) {