akm-cli 0.6.0-rc1 → 0.6.0-rc2

package/dist/{remember.js → commands/remember.js}

@@ -6,10 +6,10 @@
  * CLI entry point stays focused on argument parsing + output routing.
  */
 import { stringify as yamlStringify } from "yaml";
-import { tryReadStdinText } from "./common";
-import { loadConfig } from "./config";
-import { UsageError } from "./errors";
-import { warn } from "./warn";
+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).
@@ -17,7 +17,7 @@ import { warn } from "./warn";
 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.`);
+        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")
@@ -40,15 +40,15 @@ export function parseDuration(s) {
  */
 export function buildMemoryFrontmatter(fields) {
     const obj = {};
-    if (fields.description && fields.description.trim())
+    if (fields.description?.trim())
         obj.description = fields.description;
     if (fields.tags && fields.tags.length > 0)
         obj.tags = fields.tags;
-    if (fields.source && fields.source.trim())
+    if (fields.source?.trim())
         obj.source = fields.source;
-    if (fields.observed_at && fields.observed_at.trim())
+    if (fields.observed_at?.trim())
         obj.observed_at = fields.observed_at;
-    if (fields.expires && fields.expires.trim())
+    if (fields.expires?.trim())
         obj.expires = fields.expires;
     if (fields.subjective)
         obj.subjective = true;
@@ -86,38 +86,32 @@ export function runAutoHeuristics(body) {
     const urlMatch = body.match(/https?:\/\/[^\s)>'"]+/);
     const source = urlMatch ? urlMatch[0] : undefined;
     // ISO date token or obvious relative date phrase → observed_at
-    let observed_at;
-    const isoMatch = body.match(/\b(\d{4}-\d{2}-\d{2})\b/);
-    if (isoMatch) {
-        observed_at = isoMatch[1];
-    }
-    else {
-        const relMatch = body.match(/\b(today|yesterday|last\s+week|last\s+month)\b/i);
-        if (relMatch) {
-            const phrase = relMatch[1].toLowerCase();
-            const now = new Date();
-            if (phrase === "today") {
-                observed_at = now.toISOString().slice(0, 10);
-            }
-            else if (phrase === "yesterday") {
-                const d = new Date(now);
-                d.setDate(d.getDate() - 1);
-                observed_at = d.toISOString().slice(0, 10);
-            }
-            else if (phrase.startsWith("last week")) {
-                const d = new Date(now);
-                d.setDate(d.getDate() - 7);
-                observed_at = d.toISOString().slice(0, 10);
-            }
-            else if (phrase.startsWith("last month")) {
-                const d = new Date(now);
-                d.setMonth(d.getMonth() - 1);
-                observed_at = d.toISOString().slice(0, 10);
-            }
-        }
-    }
+    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;
 /**
@@ -131,7 +125,8 @@ export async function runLlmEnrich(body) {
         warn("Warning: --enrich requires an LLM to be configured. Run `akm config set llm` to configure one.");
         return { tags: [] };
     }
-    const { chatCompletion, parseJsonResponse } = await import("./llm.js");
+    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
@@ -143,13 +138,25 @@ ${body.slice(0, 2000)}
 
 Return ONLY the JSON object, no prose, no markdown fences.`;
     try {
-        const result = await Promise.race([
-            chatCompletion(config.llm, [
-                { role: "system", content: "Return only valid JSON. No prose." },
-                { role: "user", content: prompt },
-            ], { maxTokens: 256, temperature: 0.1 }),
-            new Promise((_, reject) => setTimeout(() => reject(new Error("LLM enrichment timed out")), LLM_ENRICH_TIMEOUT_MS)),
-        ]);
+        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.");
@@ -165,8 +172,7 @@ Return ONLY the JSON object, no prose, no markdown fences.`;
         return { tags, description, observed_at };
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        warn(`Warning: --enrich failed (${msg}). Writing memory without enrichment.`);
+        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 "./db-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 git (content
-    // now indexed through the unified FTS5 pipeline).
-    const additionalStashProviders = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && 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 {
@@ -78,7 +94,9 @@ function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
     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,15 +209,13 @@ 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) {
@@ -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) {