akm-cli 0.7.1 → 0.7.3

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/memory-inference.js

@@ -1,9 +1,10 @@
 /**
  * Memory inference pass for `akm index` (#201).
  *
- * Detects memories pending inference, asks the configured LLM to split each
- * into atomic facts, and writes the results back as new memory files with
- * frontmatter `inferred: true` + a `source:` backref to the parent memory.
+ * Detects memories pending inference, asks the configured LLM to compress each
+ * into one higher-signal derived memory, and writes the result back as a new
+ * memory file with frontmatter `inferred: true` + a `source:` backref to the
+ * parent memory.
  *
  * Pending predicate (see {@link isPendingMemory}):
  *   - File lives under `<stashRoot>/memories/` and ends in `.md`.
@@ -36,7 +37,7 @@ import { parseFrontmatter, parseFrontmatterBlock } from "../core/frontmatter";
 import { warn } from "../core/warn";
 import { writeAssetToSource } from "../core/write-source";
 import { resolveIndexPassLLM } from "../llm/index-passes";
-import { splitMemoryIntoAtomicFacts } from "../llm/memory-infer";
+import { compressMemoryToDerivedMemory } from "../llm/memory-infer";
 /**
  * Frontmatter keys this pass cares about. Constants so a future rename only
  * needs to touch one site.
@@ -59,8 +60,8 @@ const FM_SOURCE = "source";
  * Both must allow the call for the pass to run. Either set to `false`
  * short-circuits to a no-op result.
  */
-export async function runMemoryInferencePass(config, sources) {
-    const empty = {
+export async function runMemoryInferencePass(config, sources, signal) {
+    const result = {
         considered: 0,
         splitParents: 0,
         writtenFacts: 0,
@@ -69,38 +70,40 @@ export async function runMemoryInferencePass(config, sources) {
     // Gate 1 — locked feature flag (§14). Defaults to enabled; only an
     // explicit `false` disables the pass entirely.
     if (config.llm?.features?.memory_inference === false)
-        return empty;
+        return result;
     // Gate 2 — per-pass opt-out (#208). Returns the resolved llm config or
     // `undefined` when the pass should not run.
     const llmConfig = resolveIndexPassLLM("memory", config);
     if (!llmConfig)
-        return empty;
+        return result;
     // The pass only writes to the primary (working) stash. Read-only caches
     // (git, npm, website) are deliberately untouched — writing inferred
     // children there would be clobbered by the next sync().
     const primary = sources[0];
     if (!primary)
-        return empty;
+        return result;
     const pending = collectPendingMemories(primary.path);
-    empty.considered = pending.length;
+    result.considered = pending.length;
     if (pending.length === 0)
-        return empty;
+        return result;
     for (const record of pending) {
-        const facts = await splitMemoryIntoAtomicFacts(llmConfig, record.body);
-        if (facts.length === 0) {
-            empty.skippedNoFacts += 1;
+        if (signal?.aborted)
+            return result;
+        const derived = await compressMemoryToDerivedMemory(llmConfig, record.body, signal);
+        if (!derived) {
+            result.skippedNoFacts += 1;
             // Intentionally NOT marked processed — a transient LLM failure should
             // be retried on the next index run.
             continue;
         }
-        const written = await writeAtomicChildren(record, facts);
+        const written = await writeDerivedMemory(record, derived);
         if (written > 0) {
             markParentProcessed(record);
-            empty.splitParents += 1;
-            empty.writtenFacts += written;
+            result.splitParents += 1;
+            result.writtenFacts += written;
         }
     }
-    return empty;
+    return result;
 }
 // ── Pending detection ───────────────────────────────────────────────────────
 /**
@@ -133,6 +136,7 @@ export function collectPendingMemories(stashRoot) {
             ref: `memory:${relName}`,
             data: parsed.data,
             body: parsed.content,
+            name: relName,
         });
     }
     return out;
@@ -177,19 +181,8 @@ function toMemoryName(memoriesDir, filePath) {
     // user has organised under memories/.
     return rel.replace(/\\/g, "/").replace(/\.md$/i, "");
 }
-// ── Writing children + marking parent ───────────────────────────────────────
-async function writeAtomicChildren(parent, facts) {
-    const memoriesDir = path.join(parent.stashRoot, "memories");
-    // Sibling directory layout: <parentDir>/<parentBase>.facts/fact-N.md
-    // Keeps facts grouped near the parent without polluting the top level.
-    const parentRel = path.relative(memoriesDir, parent.filePath).replace(/\\/g, "/");
-    const parentBase = parentRel.replace(/\.md$/i, "");
-    const factsDirRel = `${parentBase}.facts`;
-    // Children are routed through writeAssetToSource — the single dispatch
-    // point for kind-branching writes (CLAUDE.md / spec §10 step 5). Memory
-    // assets resolve to `<source.path>/memories/<name>.md`, so a child name
-    // of `<parentBase>.facts/fact-N` lands at exactly the documented child
-    // path scheme.
+// ── Writing derived memories + marking parent ───────────────────────────────
+async function writeDerivedMemory(parent, derived) {
     const writeTarget = {
         kind: "filesystem",
         name: "stash",
@@ -201,39 +194,35 @@ async function writeAtomicChildren(parent, facts) {
         path: parent.stashRoot,
         writable: true,
     };
-    let written = 0;
-    for (let i = 0; i < facts.length; i++) {
-        const fact = facts[i];
-        const childName = `${factsDirRel}/fact-${i + 1}`;
-        const childRefStr = `memory:${childName}`;
-        const childPath = path.join(memoriesDir, `${childName}.md`);
-        // Idempotent re-writes: if a child already exists at this slot we skip
-        // it. The parent's `inferenceProcessed` marker is the primary idempotency
-        // guard (we never re-enter the splitter for a processed parent), but a
-        // partial previous run that crashed before the marker landed should not
-        // duplicate facts.
-        if (fs.existsSync(childPath)) {
-            continue;
-        }
-        try {
-            const content = renderChildMemory(fact, parent.ref);
-            const childRef = parseAssetRef(childRefStr);
-            await writeAssetToSource(writeTarget, writeConfig, childRef, content);
-            written += 1;
-        }
-        catch (err) {
-            warn(`memory inference: failed to write atomic child ${childName}: ${err instanceof Error ? err.message : String(err)}`);
-        }
+    const childName = `${parent.name}.derived`;
+    const childRefStr = `memory:${childName}`;
+    const childPath = path.join(parent.stashRoot, "memories", `${childName}.md`);
+    if (fs.existsSync(childPath)) {
+        return 0;
+    }
+    try {
+        const content = renderDerivedMemory(parent, derived);
+        const childRef = parseAssetRef(childRefStr);
+        await writeAssetToSource(writeTarget, writeConfig, childRef, content);
+        return 1;
+    }
+    catch (err) {
+        warn(`memory inference: failed to write derived memory ${childName}: ${err instanceof Error ? err.message : String(err)}`);
+        return 0;
     }
-    return written;
 }
-function renderChildMemory(fact, parentRef) {
+function renderDerivedMemory(parent, derived) {
     const fm = {
         [FM_INFERRED]: true,
-        [FM_SOURCE]: parentRef,
+        [FM_SOURCE]: parent.ref,
+        description: derived.description,
+        tags: derived.tags,
+        searchHints: derived.searchHints,
+        title: derived.title,
+        derivedFrom: parent.name,
     };
     const yaml = yamlStringify(fm).trimEnd();
-    return `---\n${yaml}\n---\n\n${fact.trim()}\n`;
+    return `---\n${yaml}\n---\n\n# ${derived.title.trim()}\n\n${derived.content.trim()}\n`;
 }
 function markParentProcessed(parent) {
     // Frontmatter-only rewrite of an existing asset: not a new asset write,

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

@@ -8,7 +8,7 @@ import { resolveSourceProviderFactory } from "../sources/provider-factory";
 import "../sources/providers/index";
 import { warn } from "../core/warn";
 import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "../sources/providers/git";
-import { ensureWebsiteMirror } from "../sources/providers/website";
+import { ensureWebsiteMirror } from "../sources/website-ingest";
 // Legacy "context-hub" / "github" type aliases are normalized to "git" at
 // config-load time (see src/config.ts), so this set only contains the canonical
 // type.
@@ -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)}`);