akm-cli 0.7.2 → 0.7.4

package/dist/indexer/manifest.js

@@ -14,7 +14,7 @@ import { resolveStashDir } from "../core/common";
 import { loadConfig } from "../core/config";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
-import { closeDatabase, getAllEntries, getEntryCount, getMeta, openDatabase } from "./db";
+import { closeDatabase, getAllEntries, getEntryCount, getMeta, openExistingDatabase } from "./db";
 import { generateMetadataFlat, loadStashFile } from "./metadata";
 import { resolveSourceEntries } from "./search-source";
 import { walkStashFlat } from "./walker";
@@ -57,13 +57,12 @@ function toManifestEntry(entry, filePath, stashDir, registryId) {
 /**
  * Get the manifest from the database (fast path).
  */
-function getManifestFromDb(stashDir, config, sources, type) {
+function getManifestFromDb(stashDir, _config, sources, type) {
     const dbPath = getDbPath();
     try {
         if (!fs.existsSync(dbPath))
             return null;
-        const embeddingDim = config.embedding?.dimension;
-        const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+        const db = openExistingDatabase(dbPath);
         try {
             const entryCount = getEntryCount(db);
             const storedStashDir = getMeta(db, "stashDir");
@@ -113,29 +112,21 @@ async function getManifestFromWalker(sources, type) {
                 dirGroups.set(ctx.parentDirAbs, [ctx.absPath]);
         }
         for (const [dirPath, files] of dirGroups) {
-            // Try loading existing .stash.json first
-            let stash = loadStashFile(dirPath);
-            if (stash) {
-                const coveredFiles = new Set(stash.entries.map((e) => e.filename).filter((e) => !!e));
-                const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
-                if (uncoveredFiles.length > 0) {
-                    const generated = await generateMetadataFlat(currentStashDir, uncoveredFiles);
-                    if (generated.entries.length > 0) {
-                        stash = { entries: [...stash.entries, ...generated.entries] };
-                    }
-                }
-            }
-            else {
-                const generated = await generateMetadataFlat(currentStashDir, files);
-                if (generated.entries.length === 0)
-                    continue;
-                stash = generated;
-            }
+            const generated = await generateMetadataFlat(currentStashDir, files);
+            const legacyOverrides = loadStashFile(dirPath, { requireFilename: true });
+            const mergedEntries = legacyOverrides
+                ? generated.entries.map((entry) => mergeLegacyEntry(entry, legacyOverrides.entries))
+                : generated.entries;
+            const stash = mergedEntries.length > 0 ? { entries: mergedEntries } : legacyOverrides;
+            if (!stash || stash.entries.length === 0)
+                continue;
             const source = sources.find((s) => dirPath.startsWith(path.resolve(s.path) + path.sep));
             for (const stashEntry of stash.entries) {
                 if (type && type !== "any" && stashEntry.type !== type)
                     continue;
-                const entryPath = stashEntry.filename ? path.join(dirPath, stashEntry.filename) : files[0] || dirPath;
+                if (!stashEntry.filename)
+                    continue;
+                const entryPath = path.join(dirPath, stashEntry.filename);
                 const manifestEntry = toManifestEntry(stashEntry, entryPath, currentStashDir, source?.registryId);
                 if (manifestEntry)
                     entries.push(manifestEntry);
@@ -144,6 +135,10 @@ async function getManifestFromWalker(sources, type) {
     }
     return entries;
 }
+function mergeLegacyEntry(entry, legacyEntries) {
+    const legacy = legacyEntries.find((candidate) => candidate.filename === entry.filename);
+    return legacy ? { ...entry, ...legacy, filename: entry.filename } : entry;
+}
 /**
  * Generate a compact manifest of all assets in the stash.
  *

package/dist/indexer/metadata.js

@@ -49,7 +49,7 @@ export function isProposedQuality(quality) {
 export function stashFilePath(dirPath) {
     return path.join(dirPath, STASH_FILENAME);
 }
-export function loadStashFile(dirPath) {
+export function loadStashFile(dirPath, options) {
     const filePath = stashFilePath(dirPath);
     if (!fs.existsSync(filePath))
         return null;
@@ -61,6 +61,8 @@ export function loadStashFile(dirPath) {
         for (const e of raw.entries) {
             const validated = validateStashEntry(e);
             if (validated) {
+                if (options?.requireFilename && !validated.filename)
+                    continue;
                 entries.push(validated);
             }
             else {
@@ -268,6 +270,69 @@ export function applyScopeFrontmatter(entry, fmData) {
     if (scope)
         entry.scope = scope;
 }
+function normalizeIntent(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const intent = {};
+    const when = toStringOrUndefined(raw.when);
+    const input = toStringOrUndefined(raw.input);
+    const output = toStringOrUndefined(raw.output);
+    if (when)
+        intent.when = when;
+    if (input)
+        intent.input = input;
+    if (output)
+        intent.output = output;
+    return Object.keys(intent).length > 0 ? intent : undefined;
+}
+function normalizeStringListOrUndefined(value) {
+    return normalizeNonEmptyStringList(value);
+}
+export function applyCuratedFrontmatter(entry, fmData) {
+    const description = toStringOrUndefined(fmData.description);
+    if (description) {
+        entry.description = description;
+        entry.source = "frontmatter";
+        entry.confidence = 0.9;
+    }
+    const tags = normalizeStringListOrUndefined(fmData.tags);
+    if (tags)
+        entry.tags = normalizeTerms(tags);
+    const aliases = normalizeStringListOrUndefined(fmData.aliases);
+    if (aliases)
+        entry.aliases = normalizeTerms(aliases);
+    const searchHints = normalizeStringListOrUndefined(fmData.searchHints);
+    if (searchHints)
+        entry.searchHints = searchHints;
+    const usage = normalizeStringListOrUndefined(fmData.usage);
+    if (usage)
+        entry.usage = usage;
+    const examples = normalizeStringListOrUndefined(fmData.examples);
+    if (examples)
+        entry.examples = examples;
+    const run = toStringOrUndefined(fmData.run);
+    if (run)
+        entry.run = run;
+    const setup = toStringOrUndefined(fmData.setup);
+    if (setup)
+        entry.setup = setup;
+    const cwd = toStringOrUndefined(fmData.cwd);
+    if (cwd)
+        entry.cwd = cwd;
+    const quality = toStringOrUndefined(fmData.quality);
+    if (quality)
+        entry.quality = normalizeQuality(quality);
+    const intent = normalizeIntent(fmData.intent);
+    if (intent)
+        entry.intent = intent;
+    if (typeof fmData.scope === "object" && fmData.scope !== null && !Array.isArray(fmData.scope)) {
+        const normalizedScope = normalizeScopeObject(fmData.scope);
+        if (normalizedScope)
+            entry.scope = normalizedScope;
+    }
+    applyScopeFrontmatter(entry, fmData);
+}
 function normalizeNonEmptyStringList(value) {
     if (typeof value === "string") {
         const trimmed = value.trim();
@@ -439,6 +504,183 @@ function mergeParameters(existing, additional) {
     }
     return merged;
 }
+function splitCommentList(raw) {
+    return raw
+        .split(/[;,]/)
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function parseCommentScope(raw) {
+    const pairs = raw
+        .split(/[;,]/)
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    if (pairs.length === 0)
+        return undefined;
+    const scopeRaw = {};
+    for (const pair of pairs) {
+        const [keyPart, ...valueParts] = pair.split("=");
+        const key = keyPart?.trim();
+        const value = valueParts.join("=").trim();
+        if (!key || !value)
+            continue;
+        if (SCOPE_KEYS.includes(key)) {
+            scopeRaw[key] = value;
+        }
+    }
+    return normalizeScopeObject(scopeRaw);
+}
+function parseIntentCommentLine(cleaned, metadata) {
+    const intentMatch = cleaned.match(/^@intent(?:\.(when|input|output))?\s+(.+)$/);
+    if (!intentMatch)
+        return false;
+    metadata.intent ??= {};
+    const value = intentMatch[2].trim();
+    const key = intentMatch[1];
+    if (key === "when")
+        metadata.intent.when = value;
+    else if (key === "input")
+        metadata.intent.input = value;
+    else if (key === "output")
+        metadata.intent.output = value;
+    else
+        metadata.intent.when ??= value;
+    return true;
+}
+export function extractCommentMetadata(filePath, content) {
+    if (content === undefined) {
+        try {
+            content = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const lines = content.split(/\r?\n/).slice(0, 50);
+    const metadata = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!/^(?:\/\/|#|\/?\*|;|--)/.test(trimmed) && !trimmed.startsWith("'"))
+            continue;
+        const cleaned = trimmed
+            .replace(/^(?:\/\/|##?|\/?\*\*?\/?|;|--|'?)\s*/, "")
+            .replace(/\*\/\s*$/, "")
+            .trim();
+        if (!cleaned)
+            continue;
+        if (parseIntentCommentLine(cleaned, metadata))
+            continue;
+        const descMatch = cleaned.match(/^@description\s+(.+)$/);
+        if (descMatch) {
+            metadata.description = descMatch[1].trim();
+            continue;
+        }
+        const tagsMatch = cleaned.match(/^@tags?\s+(.+)$/);
+        if (tagsMatch) {
+            metadata.tags = splitCommentList(tagsMatch[1]);
+            continue;
+        }
+        const aliasesMatch = cleaned.match(/^@aliases?\s+(.+)$/);
+        if (aliasesMatch) {
+            metadata.aliases = splitCommentList(aliasesMatch[1]);
+            continue;
+        }
+        const hintsMatch = cleaned.match(/^@searchHints?\s+(.+)$/);
+        if (hintsMatch) {
+            metadata.searchHints = splitCommentList(hintsMatch[1]);
+            continue;
+        }
+        const usageMatch = cleaned.match(/^@usage\s+(.+)$/);
+        if (usageMatch) {
+            metadata.usage = [...(metadata.usage ?? []), usageMatch[1].trim()];
+            continue;
+        }
+        const examplesMatch = cleaned.match(/^@examples?\s+(.+)$/);
+        if (examplesMatch) {
+            metadata.examples = [...(metadata.examples ?? []), examplesMatch[1].trim()];
+            continue;
+        }
+        const runMatch = cleaned.match(/^@run\s+(.+)$/);
+        if (runMatch) {
+            metadata.run = runMatch[1].trim();
+            continue;
+        }
+        const setupMatch = cleaned.match(/^@setup\s+(.+)$/);
+        if (setupMatch) {
+            metadata.setup = setupMatch[1].trim();
+            continue;
+        }
+        const cwdMatch = cleaned.match(/^@cwd\s+(.+)$/);
+        if (cwdMatch) {
+            metadata.cwd = cwdMatch[1].trim();
+            continue;
+        }
+        const scopeMatch = cleaned.match(/^@scope\s+(.+)$/);
+        if (scopeMatch) {
+            const scope = parseCommentScope(scopeMatch[1]);
+            if (scope)
+                metadata.scope = scope;
+        }
+    }
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+export function applyCommentMetadata(entry, metadata) {
+    if (!metadata)
+        return;
+    let usedCommentMetadata = false;
+    if (metadata.description && !entry.description) {
+        entry.description = metadata.description;
+        usedCommentMetadata = true;
+    }
+    if (metadata.tags?.length && (!entry.tags || entry.tags.length === 0)) {
+        entry.tags = normalizeTerms(metadata.tags);
+        usedCommentMetadata = true;
+    }
+    if (metadata.aliases?.length) {
+        entry.aliases = normalizeTerms(metadata.aliases);
+        usedCommentMetadata = true;
+    }
+    if (metadata.searchHints?.length) {
+        entry.searchHints = metadata.searchHints;
+        usedCommentMetadata = true;
+    }
+    if (metadata.usage?.length) {
+        entry.usage = metadata.usage;
+        usedCommentMetadata = true;
+    }
+    if (metadata.examples?.length) {
+        entry.examples = metadata.examples;
+        usedCommentMetadata = true;
+    }
+    if (metadata.intent && Object.keys(metadata.intent).length > 0) {
+        entry.intent = metadata.intent;
+        usedCommentMetadata = true;
+    }
+    if (metadata.run) {
+        entry.run = metadata.run;
+        usedCommentMetadata = true;
+    }
+    if (metadata.setup) {
+        entry.setup = metadata.setup;
+        usedCommentMetadata = true;
+    }
+    if (metadata.cwd) {
+        entry.cwd = metadata.cwd;
+        usedCommentMetadata = true;
+    }
+    if (metadata.scope) {
+        entry.scope = metadata.scope;
+        usedCommentMetadata = true;
+    }
+    if (usedCommentMetadata && entry.source !== "frontmatter" && entry.source !== "manual") {
+        entry.source = "comments";
+        entry.confidence = Math.max(entry.confidence ?? 0, 0.7);
+    }
+}
+function mergeAliases(existing, generated) {
+    const merged = normalizeTerms([...(existing ?? []), ...generated]);
+    return merged.length > 0 ? merged : undefined;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
 export async function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
@@ -473,20 +715,13 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
         if (ext === ".md") {
             const content = fs.readFileSync(file, "utf8");
             const parsed = parseFrontmatter(content);
-            const fm = toStringOrUndefined(parsed.data.description);
-            if (fm) {
-                entry.description = fm;
-                entry.source = "frontmatter";
-                entry.confidence = 0.9;
-            }
+            applyCuratedFrontmatter(entry, parsed.data);
             // Extract parameters from frontmatter params: key
             const fmParams = extractFrontmatterParameters(parsed.data);
             if (fmParams)
                 entry.parameters = fmParams;
             // Pass wiki-pattern frontmatter through onto the entry
             applyWikiFrontmatter(entry, parsed.data);
-            // Pass canonical scope_* frontmatter through onto the entry
-            applyScopeFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -500,9 +735,11 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
         // and must never be parsed for @param or any other metadata that could
         // embed a value into the entry.
         if (ext !== ".md" && assetType !== "vault") {
-            const scriptParams = extractScriptParameters(file);
+            const content = fs.readFileSync(file, "utf8");
+            const scriptParams = extractScriptParameters(file, content);
             if (scriptParams)
                 entry.parameters = scriptParams;
+            applyCommentMetadata(entry, extractCommentMetadata(file, content));
         }
         // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for scripts)
         const fileCtx = buildFileContext(typeRoot, file);
@@ -530,7 +767,7 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
             entry.tags = extractTagsFromPath(file, dirPath);
         }
         entry.tags = normalizeTerms(entry.tags ?? []);
-        entry.aliases = buildAliases(canonicalName, entry.tags);
+        entry.aliases = mergeAliases(entry.aliases, buildAliases(canonicalName, entry.tags));
         // Search hints are only generated when LLM is configured (via enhanceStashWithLlm)
         // Heuristic search hints are too noisy to be useful for search quality
         entry.filename = path.basename(file);
@@ -591,20 +828,13 @@ export async function generateMetadataFlat(stashRoot, files) {
         if (ext === ".md") {
             const content = ctx.content();
             const parsed = parseFrontmatter(content);
-            const fm = toStringOrUndefined(parsed.data.description);
-            if (fm) {
-                entry.description = fm;
-                entry.source = "frontmatter";
-                entry.confidence = 0.9;
-            }
+            applyCuratedFrontmatter(entry, parsed.data);
             // Extract parameters from frontmatter params: key
             const fmParams = extractFrontmatterParameters(parsed.data);
             if (fmParams)
                 entry.parameters = fmParams;
             // Pass wiki-pattern frontmatter through onto the entry
             applyWikiFrontmatter(entry, parsed.data);
-            // Pass canonical scope_* frontmatter through onto the entry
-            applyScopeFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -618,9 +848,11 @@ export async function generateMetadataFlat(stashRoot, files) {
         // and must never be parsed for @param or any other metadata that could
         // embed a value into the entry.
         if (ext !== ".md" && assetType !== "vault") {
-            const scriptParams = extractScriptParameters(file, ctx.content());
+            const content = ctx.content();
+            const scriptParams = extractScriptParameters(file, content);
             if (scriptParams)
                 entry.parameters = scriptParams;
+            applyCommentMetadata(entry, extractCommentMetadata(file, content));
         }
         // Renderer metadata extraction
         const renderer = await getRenderer(match.renderer);
@@ -644,7 +876,7 @@ export async function generateMetadataFlat(stashRoot, files) {
             entry.tags = extractTagsFromPath(file, dirPath);
         }
         entry.tags = normalizeTerms(entry.tags ?? []);
-        entry.aliases = buildAliases(canonicalName, entry.tags);
+        entry.aliases = mergeAliases(entry.aliases, buildAliases(canonicalName, entry.tags));
         entry.filename = path.basename(file);
         entries.push(entry);
     }

package/dist/indexer/search-source.js

@@ -121,7 +121,8 @@ function resolveEntryContentDir(entry) {
     // that subdirectory. This is a content-layout convention, not a provider
     // capability — keep it here.
     if (GIT_STASH_TYPES.has(entry.type)) {
-        return path.join(dir, "content");
+        const contentDir = path.join(dir, "content");
+        return isValidDirectory(contentDir) ? contentDir : dir;
     }
     return dir;
 }
@@ -222,8 +223,9 @@ function isValidDirectory(dir) {
  * `resolveSourceEntries()` so the content directories pass the
  * `isValidDirectory()` check.
  */
-export async function ensureSourceCaches(config) {
+export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
+    const force = options?.force === true;
     // Use sources[] (current key) with fallback to stashes[] (deprecated, one-release compat).
     const entries = cfg.sources ?? cfg.stashes ?? [];
     for (const entry of entries) {
@@ -232,7 +234,11 @@ export async function ensureSourceCaches(config) {
         try {
             const repo = parseGitRepoUrl(entry.url);
             const cachePaths = getCachePaths(repo.canonicalUrl);
-            await ensureGitMirror(repo, cachePaths, { requireRepoDir: true, writable: entry.writable === true });
+            await ensureGitMirror(repo, cachePaths, {
+                requireRepoDir: true,
+                writable: entry.writable === true,
+                force,
+            });
         }
         catch (err) {
             warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
@@ -242,7 +248,7 @@ export async function ensureSourceCaches(config) {
         if (entry.type !== "website" || !entry.url || entry.enabled === false)
             continue;
         try {
-            await ensureWebsiteMirror(entry, { requireStashDir: true });
+            await ensureWebsiteMirror(entry, { requireStashDir: true, force });
         }
         catch (err) {
             warn(`Warning: failed to refresh website stash for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);

package/dist/output/cli-hints.js

@@ -287,8 +287,9 @@ akm config path --all                         # Show all config paths
 
 \`\`\`sh
 akm init                                      # Initialize working stash
-akm index                                     # Rebuild search index
-akm index --full                              # Full reindex
+akm index                                     # Rebuild search index (no LLM enrichment)
+akm index --full                              # Full reindex (no LLM enrichment)
+akm index --enrich                            # Reindex with LLM inference/enrichment passes
 akm list                                      # List all sources
 akm upgrade                                   # Upgrade akm using its install method
 akm upgrade --check                           # Check for updates

package/dist/output/renderers.js

@@ -13,7 +13,7 @@ import { hasErrnoCode } from "../core/common";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
 import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc, } from "../core/markdown";
 import { registerRenderer } from "../indexer/file-context";
-import { extractDescriptionFromComments, loadStashFile } from "../indexer/metadata";
+import { extractCommentMetadata, extractDescriptionFromComments } from "../indexer/metadata";
 import { buildWorkflowAction, workflowMdRenderer } from "../workflows/renderer";
 // ── Interpreter auto-detection map ───────────────────────────────────────────
 const INTERPRETER_MAP = {
@@ -49,36 +49,12 @@ const SETUP_SIGNALS = {
  * `@run <value>`, `@setup <value>`, or `@cwd <value>`.
  */
 export function extractCommentTags(filePath) {
-    let content;
-    try {
-        content = fs.readFileSync(filePath, "utf8");
-    }
-    catch {
-        return {};
-    }
-    const lines = content.split(/\r?\n/, 50);
-    const hints = {};
-    for (const line of lines) {
-        const trimmed = line.trim();
-        // Match lines starting with comment markers: //, #, /*, *, ;, --
-        if (!/^(?:\/\/|#|\/?\*|;|--)/.test(trimmed) && !trimmed.startsWith("'"))
-            continue;
-        // Strip comment prefix
-        const cleaned = trimmed
-            .replace(/^(?:\/\/|##?|\/?\*\*?\/?|;|--)\s*/, "")
-            .replace(/\*\/\s*$/, "")
-            .trim();
-        const runMatch = cleaned.match(/^@run\s+(.+)/);
-        if (runMatch)
-            hints.run = runMatch[1].trim();
-        const setupMatch = cleaned.match(/^@setup\s+(.+)/);
-        if (setupMatch)
-            hints.setup = setupMatch[1].trim();
-        const cwdMatch = cleaned.match(/^@cwd\s+(.+)/);
-        if (cwdMatch)
-            hints.cwd = cwdMatch[1].trim();
-    }
-    return hints;
+    const metadata = extractCommentMetadata(filePath);
+    return {
+        run: metadata?.run,
+        setup: metadata?.setup,
+        cwd: metadata?.cwd,
+    };
 }
 // ── Auto-detection ───────────────────────────────────────────────────────────
 /**
@@ -118,9 +94,9 @@ export function detectExecHints(filePath) {
  * Resolve execution hints for a script asset.
  *
  * Resolution order (first non-empty value wins for each field):
- * 1. `.stash.json` fields (`run`/`setup`/`cwd`) take priority
- * 2. Script file header comments (`@run`/`@setup`/`@cwd`) second
- * 3. Auto-detection from extension + dependency files last
+ * 1. Indexed entry metadata (`run`/`setup`/`cwd`) when supplied by the caller
+ * 2. Script file header comments (`@run`/`@setup`/`@cwd`)
+ * 3. Auto-detection from extension + dependency files
  */
 export function resolveExecHints(stashEntry, filePath) {
     const stashHints = {
@@ -152,17 +128,6 @@ function deriveName(ctx) {
     return ext ? ctx.relPath.slice(0, -ext.length) : ctx.relPath;
 }
 export { buildWorkflowAction };
-/**
- * Load the matching StashEntry for a file path from the directory's .stash.json.
- */
-function findStashEntryForFile(filePath) {
-    const dir = path.dirname(filePath);
-    const stashFile = loadStashFile(dir);
-    if (!stashFile)
-        return undefined;
-    const fileName = path.basename(filePath);
-    return stashFile.entries.find((e) => e.filename === fileName);
-}
 function extractParameters(template) {
     const parameters = [];
     if (/\$ARGUMENTS\b/i.test(template)) {
@@ -182,18 +147,26 @@ function extractParameters(template) {
     }
     return parameters.length > 0 ? parameters : undefined;
 }
+function readFrontmatterTags(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const tags = value.filter((tag) => typeof tag === "string" && tag.trim().length > 0);
+    return tags.length > 0 ? tags : undefined;
+}
 // ── 1. skill-md ──────────────────────────────────────────────────────────────
 const skillMdRenderer = {
     name: "skill-md",
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
         const parsed = parseFrontmatter(ctx.content());
+        const tags = readFrontmatterTags(parsed.data.tags);
         return {
             type: "skill",
             name,
             path: ctx.absPath,
             action: "Read and follow the instructions below",
             description: toStringOrUndefined(parsed.data.description),
+            ...(tags ? { tags } : {}),
             content: parsed.content,
         };
     },
@@ -205,12 +178,14 @@ const commandMdRenderer = {
         const name = deriveName(ctx);
         const parsedMd = parseFrontmatter(ctx.content());
         const template = parsedMd.content;
+        const tags = readFrontmatterTags(parsedMd.data.tags);
         return {
             type: "command",
             name,
             path: ctx.absPath,
             action: "Fill $ARGUMENTS placeholders in the template, then dispatch",
             description: toStringOrUndefined(parsedMd.data.description),
+            ...(tags ? { tags } : {}),
             template,
             modelHint: typeof parsedMd.data.model === "string" ? parsedMd.data.model : undefined,
             agent: toStringOrUndefined(parsedMd.data.agent),
@@ -527,8 +502,7 @@ const scriptSourceRenderer = {
         const ext = path.extname(ctx.absPath).toLowerCase();
         // For extensions with a known interpreter, show exec hints
         if (INTERPRETER_MAP[ext]) {
-            const stashEntry = findStashEntryForFile(ctx.absPath);
-            const hints = resolveExecHints(stashEntry, ctx.absPath);
+            const hints = resolveExecHints(undefined, ctx.absPath);
             if (hints.run) {
                 return {
                     type: "script",
@@ -555,8 +529,7 @@ const scriptSourceRenderer = {
         if (!INTERPRETER_MAP[ext])
             return;
         try {
-            const stashEntry = findStashEntryForFile(hit.path);
-            const hints = resolveExecHints(stashEntry, hit.path);
+            const hints = resolveExecHints(undefined, hit.path);
             hit.run = hints.run;
         }
         catch (error) {

package/dist/registry/build-index.js

@@ -245,27 +245,22 @@ async function enumerateAssets(stashRoot) {
     }
     const entries = [];
     for (const [dirPath, files] of dirGroups) {
-        let stash = loadStashFile(dirPath);
-        if (stash) {
-            const covered = new Set(stash.entries.map((entry) => entry.filename).filter((value) => !!value));
-            const uncoveredFiles = files.filter((file) => !covered.has(path.basename(file)));
-            if (uncoveredFiles.length > 0) {
-                const generated = await generateMetadataFlat(stashRoot, uncoveredFiles);
-                if (generated.entries.length > 0) {
-                    stash = { entries: [...stash.entries, ...generated.entries] };
-                }
-            }
-        }
-        else {
-            const generated = await generateMetadataFlat(stashRoot, files);
-            if (generated.entries.length === 0)
-                continue;
-            stash = generated;
-        }
-        entries.push(...stash.entries.map((entry) => attachFileSize(dirPath, entry)));
+        const generated = await generateMetadataFlat(stashRoot, files);
+        const legacyOverrides = loadStashFile(dirPath, { requireFilename: true });
+        const mergedEntries = legacyOverrides
+            ? generated.entries.map((entry) => mergeLegacyEntry(entry, legacyOverrides.entries))
+            : generated.entries;
+        const stash = mergedEntries.length > 0 ? { entries: mergedEntries } : legacyOverrides;
+        if (!stash || stash.entries.length === 0)
+            continue;
+        entries.push(...stash.entries.filter((entry) => !!entry.filename).map((entry) => attachFileSize(dirPath, entry)));
     }
     return entries.sort((a, b) => `${a.type}:${a.name}`.localeCompare(`${b.type}:${b.name}`));
 }
+function mergeLegacyEntry(entry, legacyEntries) {
+    const legacy = legacyEntries.find((candidate) => candidate.filename === entry.filename);
+    return legacy ? { ...entry, ...legacy, filename: entry.filename } : entry;
+}
 function attachFileSize(dirPath, entry) {
     if (typeof entry.fileSize === "number" || !entry.filename)
         return entry;