akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{indexer.js → indexer/indexer.js}

@@ -1,27 +1,28 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isHttpUrl, resolveStashDir } from "./common";
+import { isHttpUrl, resolveStashDir, toErrorMessage } from "../core/common";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
+import { takeWorkflowDocument } from "../workflows/document-cache";
 import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
 import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
-import { getDbPath } from "./paths";
 import { buildSearchText } from "./search-fields";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./semantic-status";
 import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage-events";
 import { walkStashFlat } from "./walker";
-import { warn } from "./warn";
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function akmIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
     const onProgress = options?.onProgress ?? (() => { });
     // Load config and resolve all stash sources
-    const { loadConfig } = await import("./config.js");
+    const { loadConfig } = await import("../core/config.js");
     const config = loadConfig();
     // Ensure git stash caches are extracted before resolving stash dirs,
     // so their content directories exist on disk for the walker to discover.
-    const { ensureStashCaches, resolveStashSources } = await import("./search-source.js");
-    await ensureStashCaches(config);
-    const allStashSources = resolveStashSources(stashDir, config);
-    const allStashDirs = allStashSources.map((s) => s.path);
+    const { ensureSourceCaches, resolveSourceEntries } = await import("./search-source.js");
+    await ensureSourceCaches(config);
+    const allSourceEntries = resolveSourceEntries(stashDir, config);
+    const allSourceDirs = allSourceEntries.map((s) => s.path);
     const t0 = Date.now();
     // Open database — pass embedding dimension from config if available
     const dbPath = getDbPath();
@@ -37,7 +38,7 @@ export async function akmIndex(options) {
             phase: "summary",
             message: buildIndexSummaryMessage({
                 mode: isIncremental ? "incremental" : "full",
-                stashSources: allStashDirs.length,
+                sourcesCount: allSourceDirs.length,
                 semanticSearchMode: config.semanticSearchMode,
                 embeddingProvider: getEmbeddingProvider(config.embedding),
                 llmEnabled: !!config.llm,
@@ -67,7 +68,7 @@ export async function akmIndex(options) {
                 catch {
                     warn("index_meta stashDirs value is corrupt JSON — treating as empty");
                 }
-                const currentSet = new Set(allStashDirs);
+                const currentSet = new Set(allSourceDirs);
                 for (const dir of prevStashDirs) {
                     if (!currentSet.has(dir)) {
                         deleteEntriesByStashDir(db, dir);
@@ -80,7 +81,7 @@ export async function akmIndex(options) {
         // doFullDelete=true merges the wipe into the same transaction as the
         // inserts so readers never see an empty database mid-rebuild.
         const doFullDelete = options?.full || !isIncremental;
-        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete);
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFullDelete);
         onProgress({
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -95,9 +96,15 @@ export async function akmIndex(options) {
                 : "LLM enhancement disabled.",
         });
         const tLlmEnd = Date.now();
-        // Rebuild FTS after all inserts
-        rebuildFts(db);
-        onProgress({ phase: "fts", message: "Rebuilt full-text search index." });
+        // Rebuild FTS after all inserts. Use incremental mode when this whole
+        // index run is incremental — only entries touched by `upsertEntry`
+        // since the last rebuild are re-indexed, instead of re-scanning every
+        // row on every `akm index` invocation.
+        rebuildFts(db, { incremental: isIncremental });
+        onProgress({
+            phase: "fts",
+            message: isIncremental ? "Rebuilt full-text search index (dirty rows only)." : "Rebuilt full-text search index.",
+        });
         const tFtsEnd = Date.now();
         // Re-link detached usage_events to their new entry_ids via entry_ref.
         // entry_ref is "type:name" (e.g., "skill:code-review"), entry_key is "stashDir:type:name".
@@ -124,7 +131,7 @@ export async function akmIndex(options) {
         // are read-only caches, and regenerating their indexes would mutate
         // cache content.
         try {
-            const { regenerateAllWikiIndexes } = await import("./wiki.js");
+            const { regenerateAllWikiIndexes } = await import("../wiki/wiki.js");
             regenerateAllWikiIndexes(stashDir);
         }
         catch {
@@ -136,7 +143,7 @@ export async function akmIndex(options) {
         // Update metadata
         setMeta(db, "builtAt", new Date().toISOString());
         setMeta(db, "stashDir", stashDir);
-        setMeta(db, "stashDirs", JSON.stringify(allStashDirs));
+        setMeta(db, "stashDirs", JSON.stringify(allSourceDirs));
         setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
         const totalEntries = getEntryCount(db);
         // Warn on every index run if using JS fallback with many entries
@@ -182,7 +189,7 @@ export async function akmIndex(options) {
     }
 }
 // ── Extracted helpers for indexing ────────────────────────────────────────────
-async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete = false) {
+async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFullDelete = false) {
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
@@ -190,12 +197,12 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
     const seenPaths = new Set();
     const dirsNeedingLlm = [];
     const dirRecords = [];
-    for (const stashSource of allStashSources) {
-        const currentStashDir = stashSource.path;
+    for (const sourceAdded of allSourceEntries) {
+        const currentStashDir = sourceAdded.path;
         const fileContexts = walkStashFlat(currentStashDir);
         // Wiki-root stashes: all .md files are indexed as wiki pages under wikiName
-        if (stashSource.wikiName) {
-            const wikiName = stashSource.wikiName;
+        if (sourceAdded.wikiName) {
+            const wikiName = sourceAdded.wikiName;
             const wikiDirGroups = new Map();
             for (const ctx of fileContexts) {
                 if (ctx.ext !== ".md")
@@ -347,7 +354,13 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
                     const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                     const searchText = buildSearchText(entry);
                     const entryWithSize = attachFileSize(entry, entryPath);
-                    upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
+                    const entryId = upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
+                    if (entry.type === "workflow") {
+                        const doc = takeWorkflowDocument(entry);
+                        if (doc) {
+                            upsertWorkflowDocument(db, entryId, doc, fs.readFileSync(entryPath));
+                        }
+                    }
                 }
                 // Collect dirs needing LLM enhancement during the first walk
                 if (stash.entries.some((e) => e.quality === "generated")) {
@@ -362,13 +375,17 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
 async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     if (!config.llm || dirsNeedingLlm.length === 0)
         return;
+    // Aggregate per-entry failures so a misconfigured LLM endpoint surfaces
+    // as a single visible warning instead of silently degrading every entry
+    // and leaving the user wondering why nothing got enhanced.
+    const summary = { attempted: 0, succeeded: 0, failureSamples: [] };
     for (const { dirPath, files, currentStashDir, stash: originalStash } of dirsNeedingLlm) {
         // Only enhance generated entries; user-provided overrides should not be overwritten
         const generatedEntries = originalStash.entries.filter((e) => e.quality === "generated");
         if (generatedEntries.length === 0)
             continue;
         const generatedStash = { entries: generatedEntries };
-        const enhanced = await enhanceStashWithLlm(config.llm, generatedStash, files);
+        const enhanced = await enhanceStashWithLlm(config.llm, generatedStash, files, summary);
         // Re-upsert the enhanced entries in a single transaction so a crash
         // cannot leave half the entries updated and the rest stale.
         db.transaction(() => {
@@ -380,6 +397,16 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
             }
         })();
     }
+    if (summary.attempted > 0 && summary.succeeded === 0) {
+        const sample = summary.failureSamples.length ? ` Example: ${summary.failureSamples[0]}` : "";
+        warn(`LLM enhancement failed for all ${summary.attempted} attempted entries — index built without LLM enrichment.` +
+            ` Check llm.endpoint and llm.model in your config.${sample}`);
+    }
+    else if (summary.attempted > 0 && summary.succeeded < summary.attempted) {
+        const failed = summary.attempted - summary.succeeded;
+        const sample = summary.failureSamples.length ? ` Examples: ${summary.failureSamples.join("; ")}` : "";
+        warn(`LLM enhancement failed for ${failed}/${summary.attempted} entries — they were left un-enhanced.${sample}`);
+    }
 }
 async function generateEmbeddingsForDb(db, config, onProgress) {
     if (config.semanticSearchMode === "off") {
@@ -408,7 +435,7 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
         setMeta(db, "hasEmbeddings", "0");
     }
     try {
-        const { embedBatch } = await import("./embedder.js");
+        const { embedBatch } = await import("../llm/embedder.js");
         const allEntries = getAllEntriesForEmbedding(db);
         if (allEntries.length === 0) {
             onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
@@ -466,10 +493,32 @@ function attachFileSize(entry, entryPath) {
         return entry;
     }
 }
+function upsertWorkflowDocument(db, entryId, doc, content) {
+    const sourceHash = computeSourceHash(content);
+    db.prepare(`INSERT INTO workflow_documents (entry_id, schema_version, document_json, source_path, source_hash, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(entry_id) DO UPDATE SET
+       schema_version = excluded.schema_version,
+       document_json = excluded.document_json,
+       source_path = excluded.source_path,
+       source_hash = excluded.source_hash,
+       updated_at = excluded.updated_at`).run(entryId, doc.schemaVersion, JSON.stringify(doc), doc.source.path, sourceHash, new Date().toISOString());
+}
+function computeSourceHash(content) {
+    // Cheap, stable identity for the source markdown — used by future
+    // incremental fast-paths that skip re-validation when content is unchanged.
+    // Not security-sensitive; FNV-1a over the bytes is sufficient.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < content.length; i++) {
+        hash ^= content[i];
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
 function buildIndexSummaryMessage(options) {
-    const stashSourceLabel = options.stashSources === 1 ? "stash source" : "stash sources";
+    const stashSourceLabel = options.sourcesCount === 1 ? "stash source" : "stash sources";
     const semanticDetail = getSemanticSearchLabel(options.semanticSearchMode, options.embeddingProvider, options.vecAvailable);
-    return `Starting ${options.mode} index (${options.stashSources} ${stashSourceLabel}, semantic search: ${semanticDetail}, LLM: ${options.llmEnabled ? "enabled" : "disabled"}).`;
+    return `Starting ${options.mode} index (${options.sourcesCount} ${stashSourceLabel}, semantic search: ${semanticDetail}, LLM: ${options.llmEnabled ? "enabled" : "disabled"}).`;
 }
 function getEmbeddingProvider(embedding) {
     return isHttpUrl(embedding?.endpoint) ? "remote" : "local";
@@ -569,10 +618,11 @@ function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     }
     return false;
 }
-async function enhanceStashWithLlm(llmConfig, stash, files) {
-    const { enhanceMetadata } = await import("./llm.js");
+async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
+    const { enhanceMetadata } = await import("../llm/metadata-enhance");
     const enhanced = [];
     for (const entry of stash.entries) {
+        summary.attempted++;
         try {
             const entryFile = entry.filename
                 ? (files.find((f) => path.basename(f) === entry.filename) ?? files[0])
@@ -595,9 +645,16 @@ async function enhanceStashWithLlm(llmConfig, stash, files) {
             if (improvements.tags?.length)
                 updated.tags = improvements.tags;
             enhanced.push(updated);
+            summary.succeeded++;
         }
-        catch {
+        catch (err) {
             enhanced.push(entry);
+            const msg = toErrorMessage(err);
+            // failureSamples is bounded to 3 items, so a linear scan is cheaper
+            // than maintaining a parallel Set for membership checks (#177 review).
+            if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(msg)) {
+                summary.failureSamples.push(msg);
+            }
         }
     }
     return { entries: enhanced };
@@ -639,7 +696,73 @@ export function matchEntryToFile(entryName, fileMap, files) {
     // Fallback to first file, or null if no files are available
     return files[0] || null;
 }
-export { buildSearchFields, buildSearchText } from "./search-fields";
+/**
+ * Look up a single asset by ref. Spec §6.2 — `akm show` queries this and
+ * reads the file from disk. The index is the source of truth for which
+ * file corresponds to which ref; the indexer walks `provider.path()` for
+ * every configured source, so this query covers all source kinds.
+ *
+ * Match rules:
+ *   - `ref.origin === undefined` → first match across all sources (primary
+ *     source first, then in declared order — same priority as the indexer's
+ *     write order).
+ *   - `ref.origin === "local"`   → primary source only (entry_key prefix is
+ *     the primary stash dir).
+ *   - `ref.origin === <name>`    → restrict to the matching source name. We
+ *     resolve the source's directory and match on `entry_key` prefix.
+ *
+ * Returns `null` when no row matches — callers translate that into a
+ * `NotFoundError` with their own messaging.
+ */
+export async function lookup(ref) {
+    const { loadConfig } = await import("../core/config.js");
+    const { resolveSourceEntries } = await import("./search-source.js");
+    const config = loadConfig();
+    const sources = resolveSourceEntries(undefined, config);
+    if (sources.length === 0)
+        return null;
+    const dbPath = getDbPath();
+    const db = openDatabase(dbPath);
+    try {
+        // entry_key shape: `${stashDir}:${type}:${name}`. Suffix-match on
+        // `:type:name` so we can scope by source dir as a prefix when origin is
+        // supplied. Use parameterised queries throughout — names may include
+        // user-supplied glob characters.
+        const escapeLike = (value) => value.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+        const suffix = `:${ref.type}:${ref.name}`;
+        const escapedSuffix = escapeLike(suffix);
+        const candidateDirs = (() => {
+            if (!ref.origin)
+                return sources.map((s) => s.path);
+            if (ref.origin === "local")
+                return [sources[0].path];
+            const named = sources.find((s) => s.registryId === ref.origin);
+            return named ? [named.path] : [];
+        })();
+        if (candidateDirs.length === 0)
+            return null;
+        for (const dir of candidateDirs) {
+            const escapedDir = escapeLike(dir);
+            const row = db
+                .prepare("SELECT entry_key AS entryKey, file_path AS filePath, stash_dir AS stashDir, entry_type AS type FROM entries " +
+                "WHERE entry_key LIKE ? ESCAPE '\\' AND entry_type = ? LIMIT 1")
+                .get(`${escapedDir}${escapedSuffix}`, ref.type);
+            if (row) {
+                return {
+                    entryKey: row.entryKey,
+                    filePath: row.filePath,
+                    stashDir: row.stashDir,
+                    type: row.type,
+                    name: ref.name,
+                };
+            }
+        }
+        return null;
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
 // ── Utility score recomputation ──────────────────────────────────────────────
 /** Retention window for usage events: events older than this are purged. */
 const USAGE_EVENT_RETENTION_DAYS = 90;

package/dist/{manifest.js → indexer/manifest.js}

@@ -8,16 +8,16 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
-import { resolveStashDir } from "./common";
-import { loadConfig } from "./config";
+import { makeAssetRef } from "../core/asset-ref";
+import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
+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 { generateMetadataFlat, loadStashFile } from "./metadata";
-import { getDbPath } from "./paths";
-import { resolveStashSources } from "./search-source";
-import { makeAssetRef } from "./stash-ref";
+import { resolveSourceEntries } from "./search-source";
 import { walkStashFlat } from "./walker";
-import { warn } from "./warn";
 const MAX_DESCRIPTION_LENGTH = 80;
 /**
  * Truncate a description string to a maximum length, appending "..." if truncated.
@@ -99,9 +99,9 @@ function getManifestFromDb(stashDir, config, sources, type) {
  * Get the manifest by walking the stash directory (fallback when no index).
  */
 async function getManifestFromWalker(sources, type) {
-    const allStashDirs = sources.map((s) => s.path);
+    const allSourceDirs = sources.map((s) => s.path);
     const entries = [];
-    for (const currentStashDir of allStashDirs) {
+    for (const currentStashDir of allSourceDirs) {
         const fileContexts = walkStashFlat(currentStashDir);
         // Group by parent directory
         const dirGroups = new Map();
@@ -154,7 +154,7 @@ export async function akmManifest(options) {
     const stashDir = options?.stashDir ?? resolveStashDir();
     const type = options?.type;
     const config = loadConfig();
-    const sources = resolveStashSources(stashDir, config);
+    const sources = resolveSourceEntries(stashDir, config);
     // Fast path: try database
     const dbEntries = getManifestFromDb(stashDir, config, sources, type);
     if (dbEntries !== null) {

package/dist/{matchers.js → indexer/matchers.js}

@@ -18,7 +18,8 @@
  * - `wikiMatcher` (20) -- classifies any `.md` under `wikis/<name>/…` as
  *   `wiki`. Registered last so the later-wins tiebreaker beats agent at 20.
  */
-import { SCRIPT_EXTENSIONS } from "./asset-spec";
+import { SCRIPT_EXTENSIONS } from "../core/asset-spec";
+import { looksLikeWorkflow } from "../workflows/parser";
 import { registerMatcher } from "./file-context";
 // ── extensionMatcher (specificity: 3) ────────────────────────────────────────
 /**
@@ -51,7 +52,7 @@ export function extensionMatcher(ctx) {
  * directory segment from the stash root matches a known type name.
  *
  * The first matching type-like ancestor wins. This preserves intuitive
- * behavior for nested kit layouts such as `agent-stash/agents/blog/foo.md`
+ * behavior for nested stash layouts such as `agent-stash/agents/blog/foo.md`
  * while still honoring earlier type roots like `commands/agents/foo.md`.
  */
 export function directoryMatcher(ctx) {
@@ -140,11 +141,7 @@ export function smartMdMatcher(ctx) {
     if (ctx.ext !== ".md")
         return null;
     const body = ctx.content();
-    const hasWorkflowSignals = /^#\s+Workflow:\s+/m.test(body) &&
-        /^##\s+Step:\s+/m.test(body) &&
-        /^Step ID:\s+/m.test(body) &&
-        /^###\s+Instructions\s*$/m.test(body);
-    if (hasWorkflowSignals) {
+    if (looksLikeWorkflow(body)) {
         return { type: "workflow", specificity: 19, renderer: "workflow-md" };
     }
     const fm = ctx.frontmatter();

package/dist/{metadata.js → indexer/metadata.js}

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile } from "./asset-spec";
-import { isAssetType } from "./common";
+import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, } from "../core/asset-spec";
+import { isAssetType } from "../core/common";
+import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
+import { warn } from "../core/warn";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-import { warn } from "./warn";
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
 export function stashFilePath(dirPath) {
@@ -568,7 +568,11 @@ export async function generateMetadataFlat(stashRoot, files) {
 }
 function buildMetadataSkipWarning(filePath, assetType, error) {
     const detail = error instanceof Error ? error.message : String(error);
-    const warning = `Skipped malformed ${assetType} asset at ${filePath}: ${detail}`;
+    // Workflow errors are already multi-line `path:line — message` blocks; print
+    // them as-is so the author sees a flat list without a redundant prefix.
+    const warning = assetType === "workflow"
+        ? `Skipped workflow ${filePath}:\n${detail}`
+        : `Skipped malformed ${assetType} asset at ${filePath}: ${detail}`;
     warn(warning);
     return warning;
 }

package/dist/{search-source.js → indexer/search-source.js}

@@ -1,21 +1,35 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "./common";
-import { loadConfig } from "./config";
-import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "./stash-providers/git";
-import { ensureWebsiteMirror, getCachePaths as getWebsiteCachePaths } from "./stash-providers/website";
-import { warn } from "./warn";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { resolveSourceProviderFactory } from "../sources/provider-factory";
+// Eager side-effect imports so all built-in source providers self-register
+// before resolveEntryContentDir() runs.
+import "../sources/providers/index";
+import { warn } from "../core/warn";
+import { ensureGitMirror, getCachePaths, parseGitRepoUrl } from "../sources/providers/git";
+import { ensureWebsiteMirror } from "../sources/providers/website";
+// 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.
+const GIT_STASH_TYPES = new Set(["git"]);
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
- * Build the ordered list of stash sources:
- *   1. Primary stash dir (user's own, destination for clone)
- *   2. Additional stashes (filesystem and remote providers)
- *   3. Installed kit paths (cache-managed, from registry)
+ * Build the ordered list of stash sources, walking every configured stash
+ * once. Iteration order:
  *
- * The first entry is always the primary stash. Additional entries come
- * from `stashes` config and `installed` kit entries.
+ *   1. The primary stash directory (the entry marked `primary: true`, or the
+ *      legacy top-level `stashDir`). Always emitted, even when the directory
+ *      does not yet exist on disk, so callers can use it as the clone target.
+ *   2. Each entry in `config.sources ?? config.stashes[]` (in declared order), excluding the
+ *      one already emitted as the primary.
+ *   3. Each entry in `config.installed[]` (registry-managed stashes).
+ *
+ * Replaces the previous four-pass loop that walked `stashes[]` separately
+ * for each provider kind. Disabled entries (`enabled: false`) and entries
+ * whose disk path doesn't exist are filtered after deduplication.
  */
-export function resolveStashSources(overrideStashDir, existingConfig) {
+export function resolveSourceEntries(overrideStashDir, existingConfig) {
     const stashDir = overrideStashDir ?? resolveStashDir();
     const config = existingConfig ?? loadConfig();
     const sources = [{ path: stashDir }];
@@ -36,53 +50,86 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             });
         }
     };
-    // Filesystem entries from stashes[]
-    for (const entry of config.stashes ?? []) {
-        if (entry.type === "filesystem" && entry.path && entry.enabled !== false) {
-            addSource(entry.path, entry.name, entry.wikiName);
-        }
+    // (1) + (2) Single pass over declared stashes — primary first if present,
+    // then the rest in declared order. The primary's directory is already
+    // injected as `sources[0]` above, so we only need to dedupe the source set.
+    const stashes = config.sources ?? config.stashes ?? [];
+    const primaryIdx = stashes.findIndex((entry) => entry.primary === true);
+    const ordered = [];
+    if (primaryIdx >= 0) {
+        ordered.push(stashes[primaryIdx]);
+        stashes.forEach((entry, i) => {
+            if (i !== primaryIdx)
+                ordered.push(entry);
+        });
     }
-    // Git stash entries: resolve cache directory so the indexer can walk it.
-    // "git" provider type (and its legacy aliases "context-hub", "github") are handled.
-    for (const entry of config.stashes ?? []) {
-        if (GIT_STASH_TYPES.has(entry.type) && entry.url && entry.enabled !== false) {
-            try {
-                const repo = parseGitRepoUrl(entry.url);
-                const cachePaths = getCachePaths(repo.canonicalUrl);
-                // The content/ subdirectory inside the extracted repo is the actual
-                // stash root containing DOC.md / SKILL.md files that the walker indexes.
-                const contentDir = path.join(cachePaths.repoDir, "content");
-                addSource(contentDir, entry.name, entry.wikiName);
-            }
-            catch (err) {
-                warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
+    else {
+        ordered.push(...stashes);
     }
-    // Website stash entries: resolve cache directory so the indexer can walk
-    // the scraped markdown snapshots.
-    for (const entry of config.stashes ?? []) {
-        if (entry.type === "website" && entry.url && entry.enabled !== false) {
-            try {
-                const cachePaths = getWebsiteCachePaths(entry.url);
-                addSource(cachePaths.stashDir, entry.name ?? entry.url, entry.wikiName);
-            }
-            catch (err) {
-                warn(`Warning: failed to resolve website stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
+    for (const entry of ordered) {
+        if (entry.enabled === false)
+            continue;
+        const dir = resolveEntryContentDir(entry);
+        if (dir == null)
+            continue;
+        addSource(dir, entry.name, entry.wikiName);
     }
-    // Installed kits (registry and local)
+    // (3) Installed stashes (registry-managed). Always last.
     for (const entry of config.installed ?? []) {
         addSource(entry.stashRoot, entry.id, entry.wikiName);
     }
     return sources;
 }
+/**
+ * Resolve the content directory the indexer should walk for a given config
+ * entry. Returns `undefined` if the entry has no walkable content
+ * so the caller can skip it.
+ *
+ * Single source of truth: each provider owns its own path. We instantiate the
+ * registered {@link import("../sources/provider").SourceProvider} for the entry
+ * and call `provider.path()`. This replaces the old per-kind switch ladder
+ * (filesystem path / git cache / website cache) that lived here in 0.6.0 —
+ * see spec §10 step 4 and §7 "Removed from 0.6.0".
+ *
+ * The git case still does one extra step: the provider returns the cloned
+ * repo dir, but the indexer walks the `content/` subdirectory inside it.
+ * That convention is part of the akm content layout, not a provider concern,
+ * so it stays here.
+ */
+function resolveEntryContentDir(entry) {
+    const factory = resolveSourceProviderFactory(entry.type);
+    if (!factory)
+        return undefined;
+    let provider;
+    try {
+        provider = factory(entry);
+    }
+    catch (err) {
+        warn(`Warning: failed to construct ${entry.type} source provider for "${entry.name ?? entry.url ?? entry.path}": ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+    let dir;
+    try {
+        dir = provider.path();
+    }
+    catch (err) {
+        warn(`Warning: failed to resolve ${entry.type} source path for "${entry.name ?? entry.url ?? entry.path}": ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+    // Git providers expose the cloned repo root as their path. The akm content
+    // layout puts indexable files under `<repo>/content/`, so the walker needs
+    // 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");
+    }
+    return dir;
+}
 /**
  * Convenience: returns just the directory paths, preserving priority order.
  */
 export function resolveAllStashDirs(overrideStashDir) {
-    return resolveStashSources(overrideStashDir).map((s) => s.path);
+    return resolveSourceEntries(overrideStashDir).map((s) => s.path);
 }
 /**
  * Find which source a file path belongs to.
@@ -168,15 +215,14 @@ function isValidDirectory(dir) {
         return false;
     }
 }
-// ── Git stash cache integration ──────────────────────────────────────────────
-const GIT_STASH_TYPES = new Set(["context-hub", "github", "git"]);
+// ── Stash cache integration ─────────────────────────────────────────────────
 /**
  * Ensure all cache-backed stash providers are refreshed so their cache
  * directories exist on disk. Must be called (async) before
- * `resolveStashSources()` so the content directories pass the
+ * `resolveSourceEntries()` so the content directories pass the
  * `isValidDirectory()` check.
  */
-export async function ensureStashCaches(config) {
+export async function ensureSourceCaches(config) {
     const cfg = config ?? loadConfig();
     for (const entry of cfg.stashes ?? []) {
         if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
@@ -201,7 +247,3 @@ export async function ensureStashCaches(config) {
         }
     }
 }
-/** @deprecated Use ensureStashCaches instead. */
-export const ensureGitCaches = ensureStashCaches;
-/** @deprecated Use ensureStashCaches instead. */
-export const ensureContextHubCaches = ensureStashCaches;

package/dist/{semantic-status.js → indexer/semantic-status.js}

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { DEFAULT_LOCAL_MODEL } from "./embedder";
-import { getCacheDir, getSemanticStatusPath } from "./paths";
+import { getCacheDir, getSemanticStatusPath } from "../core/paths";
+import { DEFAULT_LOCAL_MODEL } from "../llm/embedder";
 export function deriveSemanticProviderFingerprint(embedding) {
     if (embedding?.endpoint) {
         return `remote:${embedding.endpoint}|${embedding.model}|${embedding.dimension ?? "default"}`;

package/dist/{walker.js → indexer/walker.js}

@@ -7,7 +7,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { isRelevantAssetFile } from "./asset-spec";
+import { isRelevantAssetFile } from "../core/asset-spec";
 import { buildFileContext } from "./file-context";
 const SKIP_DIRS = new Set([".git", "node_modules", "bin", ".cache"]);
 /**