akm-cli 0.6.0-rc1 → 0.6.0

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}.`,
@@ -130,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 {
@@ -142,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
@@ -188,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;
@@ -196,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")
@@ -353,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")) {
@@ -428,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." });
@@ -486,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";
@@ -590,9 +619,8 @@ function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     return false;
 }
 async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
-    const { enhanceMetadata } = await import("./llm.js");
+    const { enhanceMetadata } = await import("../llm/metadata-enhance");
     const enhanced = [];
-    const seenSamples = new Set();
     for (const entry of stash.entries) {
         summary.attempted++;
         try {
@@ -621,10 +649,11 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
         }
         catch (err) {
             enhanced.push(entry);
-            const msg = err instanceof Error ? err.message : String(err);
-            if (summary.failureSamples.length < 3 && !seenSamples.has(msg)) {
+            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);
-                seenSamples.add(msg);
             }
         }
     }
@@ -667,10 +696,73 @@ export function matchEntryToFile(entryName, fileMap, files) {
     // Fallback to first file, or null if no files are available
     return files[0] || null;
 }
-// `buildSearchFields` and `buildSearchText` were previously re-exported from
-// here for backwards compatibility. Importers should now pull them directly
-// from `./search-fields` to avoid loading the indexer's full dependency
-// graph (LLM client, embedder facade) when only the text builder is needed.
+/**
+ * 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;
@@ -680,8 +772,10 @@ const USAGE_EVENT_RETENTION_DAYS = 90;
  * For each entry:
  *   - Count search appearances (event_type = 'search')
  *   - Count show events (event_type = 'show')
+ *   - Count positive/negative feedback events
  *   - Compute select_rate = showCount / searchCount, clamped to [0, 1]
- *   - Update utility via EMA: utility = previousUtility * 0.7 + selectRate * 0.3
+ *   - Convert feedback counts into a positive-only feedback_rate
+ *   - Update utility via EMA from the stronger of select_rate / feedback_rate
  *
  * Also purges usage_events older than 90 days and ensures the M-1
  * usage_events table exists before querying.
@@ -711,6 +805,8 @@ export function recomputeUtilityScores(db) {
       SELECT entry_id,
              SUM(CASE WHEN event_type = 'search' THEN 1 ELSE 0 END) AS search_count,
              SUM(CASE WHEN event_type = 'show'   THEN 1 ELSE 0 END) AS show_count,
+             SUM(CASE WHEN event_type = 'feedback' AND signal = 'positive' THEN 1 ELSE 0 END) AS positive_feedback_count,
+             SUM(CASE WHEN event_type = 'feedback' AND signal = 'negative' THEN 1 ELSE 0 END) AS negative_feedback_count,
              MAX(created_at) AS last_used_at
       FROM usage_events
       WHERE entry_id IS NOT NULL
@@ -729,8 +825,11 @@ export function recomputeUtilityScores(db) {
     }
     for (const row of usageRows) {
         const selectRate = row.search_count > 0 ? Math.min(1, row.show_count / row.search_count) : 0;
+        const feedbackTotal = row.positive_feedback_count + row.negative_feedback_count;
+        const feedbackRate = feedbackTotal > 0 ? Math.max(0, row.positive_feedback_count - row.negative_feedback_count) / feedbackTotal : 0;
+        const effectiveRate = Math.max(selectRate, feedbackRate);
         const prevUtility = existingScores.get(row.entry_id) ?? 0;
-        const utility = prevUtility * emaDecay + selectRate * emaNew;
+        const utility = prevUtility * emaDecay + effectiveRate * emaNew;
         upsertUtilityScore(db, row.entry_id, {
             utility,
             showCount: row.show_count,

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) ────────────────────────────────────────
 /**
@@ -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,10 +1,14 @@
 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.
@@ -17,7 +21,7 @@ const GIT_STASH_TYPES = new Set(["git"]);
  *   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.stashes[]` (in declared order), excluding the
+ *   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).
  *
@@ -25,7 +29,7 @@ const GIT_STASH_TYPES = new Set(["git"]);
  * 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 }];
@@ -49,7 +53,7 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
     // (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.stashes ?? [];
+    const stashes = config.sources ?? config.stashes ?? [];
     const primaryIdx = stashes.findIndex((entry) => entry.primary === true);
     const ordered = [];
     if (primaryIdx >= 0) {
@@ -78,43 +82,54 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
 }
 /**
  * Resolve the content directory the indexer should walk for a given config
- * entry. Returns `undefined` if the entry has no walkable content (e.g. an
- * `openviking` remote stash) so the caller can skip it.
+ * 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) {
-    if (entry.type === "filesystem" && entry.path) {
-        return entry.path;
+    const factory = resolveSourceProviderFactory(entry.type);
+    if (!factory)
+        return undefined;
+    let provider;
+    try {
+        provider = factory(entry);
     }
-    if (GIT_STASH_TYPES.has(entry.type) && entry.url) {
-        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.
-            return path.join(cachePaths.repoDir, "content");
-        }
-        catch (err) {
-            warn(`Warning: failed to resolve git stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-            return undefined;
-        }
+    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;
     }
-    if (entry.type === "website" && entry.url) {
-        try {
-            return getWebsiteCachePaths(entry.url).stashDir;
-        }
-        catch (err) {
-            warn(`Warning: failed to resolve website stash cache for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
-            return undefined;
-        }
+    let dir;
+    try {
+        dir = provider.path();
     }
-    // Remote-only providers (openviking) have no walkable directory.
-    return undefined;
+    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.
@@ -204,10 +219,10 @@ function isValidDirectory(dir) {
 /**
  * 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)
@@ -232,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"]);
 /**

package/dist/{lockfile.js → integrations/lockfile.js}

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { getConfigDir } from "./config";
+import { getConfigDir } from "../core/config";
 // ── Paths ───────────────────────────────────────────────────────────────────
 const LOCKFILE_NAME = "akm.lock";
 const LEGACY_LOCKFILE_NAME = "stash.lock";

package/dist/{llm-client.js → llm/client.js}

@@ -7,7 +7,7 @@
  *
  * `llm.ts` re-exports everything from this module for backward compatibility.
  */
-import { fetchWithTimeout } from "./common";
+import { fetchWithTimeout } from "../core/common";
 export async function chatCompletion(config, messages, options) {
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {

package/dist/{embedders → llm/embedders}/local.js

@@ -7,8 +7,8 @@
  * shared instance for the production code path.
  */
 import path from "node:path";
-import { getCacheDir } from "../paths";
-import { warn } from "../warn";
+import { getCacheDir } from "../../core/paths";
+import { warn } from "../../core/warn";
 /**
  * Default local transformer model for embeddings.
  * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous

package/dist/{embedders → llm/embedders}/remote.js

@@ -4,7 +4,7 @@
  * Calls the configured `/embeddings` endpoint and L2-normalizes the returned
  * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
  */
-import { fetchWithTimeout, isHttpUrl } from "../common";
+import { fetchWithTimeout, isHttpUrl } from "../../core/common";
 const REMOTE_BATCH_SIZE = 100;
 export class RemoteEmbedder {
     config;

package/dist/{embedders → llm/embedders}/types.js

@@ -36,4 +36,4 @@ export function cosineSimilarity(a, b) {
 }
 // Imported lazily to keep this types module dependency-free where possible;
 // `warn` is a thin printf wrapper so the cost is negligible.
-import { warn } from "../warn";
+import { warn } from "../../core/warn";

package/dist/{metadata-enhance.js → llm/metadata-enhance.js}

@@ -3,9 +3,9 @@
  *
  * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
  * improve descriptions/tags/searchHints) lives separately from the low-level
- * transport client in `llm-client.ts`.
+ * transport client in `client.ts`.
  */
-import { chatCompletion, parseJsonResponse } from "./llm-client";
+import { chatCompletion, parseJsonResponse } from "./client";
 const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,

package/dist/{cli-hints.js → output/cli-hints.js}

@@ -121,9 +121,12 @@ akm remember --name release-retro < notes.md   # Save multiline memory from stdi
 akm import ./docs/auth-flow.md                 # Import a file as knowledge
 akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
 akm workflow create ship-release               # Create a workflow asset in the stash
+akm workflow validate workflows/foo.md         # Validate a workflow file or ref; lists every error
 akm workflow next workflow:ship-release        # Start or resume the next workflow step
 akm feedback skill:code-review --positive      # Record that an asset helped
 akm feedback agent:reviewer --negative         # Record that an asset missed the mark
+akm feedback memory:deployment-notes --positive # Works for memories too
+akm feedback vault:prod --positive             # Records vault feedback without surfacing values
 \`\`\`
 
 Use \`akm feedback\` whenever an asset materially helps or fails so future search