agentikit 0.0.12 → 0.0.14

package/dist/stash-clone.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TYPE_DIRS } from "./asset-spec";
+import { parseAssetRef, makeAssetRef } from "./stash-ref";
+import { resolveSourcesForOrigin, isRemoteOrigin } from "./origin-resolve";
+import { resolveAssetPath } from "./stash-resolve";
+import { resolveStashSources, findSourceForPath, getPrimarySource } from "./stash-source";
+import { installRegistryRef } from "./registry-install";
+export async function agentikitClone(options) {
+    const parsed = parseAssetRef(options.sourceRef);
+    // When --dest is provided, the working stash is optional
+    let allSources;
+    try {
+        allSources = resolveStashSources();
+    }
+    catch (err) {
+        if (options.dest) {
+            allSources = [];
+        }
+        else {
+            throw err;
+        }
+    }
+    const primarySource = getPrimarySource(allSources);
+    const destRoot = options.dest ? path.resolve(options.dest) : primarySource?.path;
+    if (!destRoot) {
+        throw new Error("No working stash configured and no --dest provided. Run `akm init` or pass --dest.");
+    }
+    let searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    // Remote fetch fallback: if no local source matched and origin looks remote, fetch it
+    let remoteFetched;
+    if (searchSources.length === 0 && parsed.origin && isRemoteOrigin(parsed.origin, allSources)) {
+        const installResult = await installRegistryRef(parsed.origin);
+        const syntheticSource = {
+            path: installResult.stashRoot,
+            registryId: installResult.id,
+        };
+        searchSources = [syntheticSource];
+        allSources = [...allSources, syntheticSource];
+        remoteFetched = {
+            origin: parsed.origin,
+            stashRoot: installResult.stashRoot,
+            cacheDir: installResult.cacheDir,
+        };
+    }
+    let sourcePath;
+    let lastError;
+    for (const source of searchSources) {
+        try {
+            sourcePath = resolveAssetPath(source.path, parsed.type, parsed.name);
+            break;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    if (!sourcePath) {
+        const context = remoteFetched ? ` (remote package fetched but asset not found inside it)` : "";
+        throw lastError ?? new Error(`Source asset not found for ref: ${options.sourceRef}${context}`);
+    }
+    const sourceSource = findSourceForPath(sourcePath, allSources);
+    const destName = options.newName ?? parsed.name;
+    const typeDir = TYPE_DIRS[parsed.type];
+    const destLabel = options.dest ? "at destination" : "in working stash";
+    // Guard against self-clone
+    if (parsed.type === "skill") {
+        const sourceSkillDir = path.resolve(path.dirname(sourcePath));
+        const destSkillDir = path.resolve(path.join(destRoot, typeDir, destName));
+        if (sourceSkillDir === destSkillDir) {
+            throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
+        }
+    }
+    else {
+        const resolvedSource = path.resolve(sourcePath);
+        const resolvedDest = path.resolve(path.join(destRoot, typeDir, destName));
+        if (resolvedSource === resolvedDest) {
+            throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
+        }
+    }
+    let destPath;
+    if (parsed.type === "skill") {
+        const sourceSkillDir = path.dirname(sourcePath);
+        const destSkillDir = path.join(destRoot, typeDir, destName);
+        const overwritten = fs.existsSync(destSkillDir);
+        if (overwritten && !options.force) {
+            throw new Error(`Asset already exists ${destLabel}: ${destSkillDir}. Use --force to overwrite.`);
+        }
+        if (overwritten) {
+            fs.rmSync(destSkillDir, { recursive: true, force: true });
+        }
+        fs.cpSync(sourceSkillDir, destSkillDir, { recursive: true });
+        destPath = path.join(destSkillDir, "SKILL.md");
+        const ref = makeAssetRef(parsed.type, destName, "local");
+        return {
+            source: { path: sourcePath, registryId: sourceSource?.registryId },
+            destination: { path: destPath, ref },
+            overwritten,
+            ...(remoteFetched ? { remoteFetched } : {}),
+        };
+    }
+    destPath = path.join(destRoot, typeDir, destName);
+    const overwritten = fs.existsSync(destPath);
+    if (overwritten && !options.force) {
+        throw new Error(`Asset already exists ${destLabel}: ${destPath}. Use --force to overwrite.`);
+    }
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.copyFileSync(sourcePath, destPath);
+    const ref = makeAssetRef(parsed.type, destName, "local");
+    return {
+        source: { path: sourcePath, registryId: sourceSource?.registryId },
+        destination: { path: destPath, ref },
+        overwritten,
+        ...(remoteFetched ? { remoteFetched } : {}),
+    };
+}

package/dist/{src/stash-registry.js → stash-registry.js}

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
 import { agentikitIndex } from "./indexer";
+import { removeLockEntry, upsertLockEntry } from "./lockfile";
 import { installRegistryRef, removeInstalledRegistryEntry, upsertInstalledRegistryEntry, } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
 export async function agentikitList(input) {
@@ -29,6 +30,7 @@ export async function agentikitRemove(input) {
     const installed = config.registry?.installed ?? [];
     const entry = resolveInstalledTarget(installed, target);
     const updatedConfig = removeInstalledRegistryEntry(entry.id);
+    removeLockEntry(entry.id);
     cleanupDirectoryBestEffort(entry.cacheDir);
     const index = await agentikitIndex({ stashDir });
     return {
@@ -42,7 +44,7 @@ export async function agentikitRemove(input) {
             stashRoot: entry.stashRoot,
         },
         config: {
-            mountedStashDirs: updatedConfig.mountedStashDirs,
+            searchPaths: updatedConfig.searchPaths,
             installedRegistryCount: updatedConfig.registry?.installed.length ?? 0,
         },
         index: {
@@ -53,56 +55,28 @@ export async function agentikitRemove(input) {
         },
     };
 }
-export async function agentikitReinstall(input) {
+export async function agentikitUpdate(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
     const target = input?.target?.trim();
     const all = input?.all === true;
+    const force = input?.force === true;
     const installedEntries = loadConfig().registry?.installed ?? [];
     const selectedEntries = selectTargets(installedEntries, target, all);
     const processed = [];
     for (const entry of selectedEntries) {
-        const installed = await installRegistryRef(entry.ref);
-        upsertInstalledRegistryEntry(toInstalledEntry(installed));
-        if (entry.cacheDir !== installed.cacheDir) {
+        if (force) {
             cleanupDirectoryBestEffort(entry.cacheDir);
         }
-        processed.push({
-            id: entry.id,
-            source: entry.source,
-            ref: entry.ref,
-            previousCacheDir: entry.cacheDir,
-            installed: toInstallStatus(installed),
-        });
-    }
-    const index = await agentikitIndex({ stashDir });
-    const config = loadConfig();
-    return {
-        stashDir,
-        target,
-        all,
-        processed,
-        config: {
-            mountedStashDirs: config.mountedStashDirs,
-            installedRegistryCount: config.registry?.installed.length ?? 0,
-        },
-        index: {
-            mode: index.mode,
-            totalEntries: index.totalEntries,
-            directoriesScanned: index.directoriesScanned,
-            directoriesSkipped: index.directoriesSkipped,
-        },
-    };
-}
-export async function agentikitUpdate(input) {
-    const stashDir = input?.stashDir ?? resolveStashDir();
-    const target = input?.target?.trim();
-    const all = input?.all === true;
-    const installedEntries = loadConfig().registry?.installed ?? [];
-    const selectedEntries = selectTargets(installedEntries, target, all);
-    const processed = [];
-    for (const entry of selectedEntries) {
         const installed = await installRegistryRef(entry.ref);
         upsertInstalledRegistryEntry(toInstalledEntry(installed));
+        upsertLockEntry({
+            id: installed.id,
+            source: installed.source,
+            ref: installed.ref,
+            resolvedVersion: installed.resolvedVersion,
+            resolvedRevision: installed.resolvedRevision,
+            integrity: installed.integrity ?? (installed.source === "local" ? "local" : undefined),
+        });
         if (entry.cacheDir !== installed.cacheDir) {
             cleanupDirectoryBestEffort(entry.cacheDir);
         }
@@ -133,7 +107,7 @@ export async function agentikitUpdate(input) {
         all,
         processed,
         config: {
-            mountedStashDirs: config.mountedStashDirs,
+            searchPaths: config.searchPaths,
             installedRegistryCount: config.registry?.installed.length ?? 0,
         },
         index: {

package/dist/{src/stash-search.js → stash-search.js}

@@ -5,9 +5,9 @@ import { walkStash } from "./walker";
 import { makeAssetRef } from "./stash-ref";
 import { loadConfig } from "./config";
 import { searchRegistry } from "./registry-search";
-import { openDatabase, closeDatabase, getDbPath, getMeta, searchFts, searchVec, getAllEntries, getEntryCount, getEntryById, isVecAvailable, } from "./db";
+import { openDatabase, closeDatabase, getDbPath, getMeta, searchFts, searchVec, getAllEntries, getEntryCount, getEntryById, } from "./db";
 import { tryGetHandler } from "./asset-type-handler";
-import { resolveStashSources, findSourceForPath } from "./stash-source";
+import { resolveStashSources, findSourceForPath, isEditable, buildEditHint } from "./stash-source";
 const DEFAULT_LIMIT = 20;
 export async function agentikitSearch(input) {
     const t0 = Date.now();
@@ -18,6 +18,15 @@ export async function agentikitSearch(input) {
     const usageMode = parseSearchUsageMode(input.usage);
     const source = parseSearchSource(input.source);
     const sources = resolveStashSources();
+    if (sources.length === 0) {
+        return {
+            stashDir: "",
+            source: source ?? "all",
+            hits: [],
+            warnings: ["No stash sources configured. Run `akm init` first."],
+            timing: { totalMs: Date.now() - t0 },
+        };
+    }
     const stashDir = sources[0].path;
     const localResult = source === "registry"
         ? undefined
@@ -40,11 +49,12 @@ export async function agentikitSearch(input) {
             hits: localResult?.hits ?? [],
             usageGuide: localResult?.usageGuide,
             tip: localResult?.tip,
+            warnings: localResult?.warnings,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
-        const installRef = hit.source === "npm" ? `npm:${hit.ref}` : `github:${hit.ref}`;
+        const installRef = hit.source === "npm" ? `npm:${hit.ref}` : hit.source === "git" ? `git+${hit.ref}` : `github:${hit.ref}`;
         return {
             hitSource: "registry",
             type: "registry",
@@ -79,7 +89,9 @@ export async function agentikitSearch(input) {
         hits: mergedHits,
         usageGuide: localResult?.usageGuide,
         tip: mergedHits.length === 0 ? "No matching stash assets or registry entries were found." : undefined,
-        warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
+        warnings: [...(localResult?.warnings ?? []), ...(registryResult?.warnings ?? [])].length
+            ? [...(localResult?.warnings ?? []), ...(registryResult?.warnings ?? [])]
+            : undefined,
         timing: { totalMs: Date.now() - t0 },
     };
 }
@@ -116,7 +128,7 @@ async function searchLocal(input) {
         console.warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
     }
     const hits = allStashDirs
-        .flatMap((dir) => substringSearch(query, searchType, limit, dir, sources))
+        .flatMap((dir) => substringSearch(query, searchType, limit, dir, sources, config))
         .slice(0, limit);
     const usageGuide = shouldIncludeUsageGuide(usageMode) ? buildUsageGuide(hits.map((hit) => hit.type), searchType) : undefined;
     return {
@@ -142,6 +154,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             allStashDirs,
             sources,
             includeItemUsage: shouldIncludeItemUsage(usageMode),
+            config,
         }));
         return {
             hits,
@@ -157,58 +170,67 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
     const tRank0 = Date.now();
     const typeFilter = searchType === "any" ? undefined : searchType;
     const ftsResults = searchFts(db, query, limit * 3, typeFilter);
-    // Build score map from FTS results (normalize BM25 scores)
-    const ftsScoreMap = new Map();
-    for (const r of ftsResults) {
-        // BM25 returns negative scores (more negative = better match), normalize to 0-1
-        const absScore = Math.abs(r.bm25Score);
-        const normalized = absScore / (1 + absScore);
-        ftsScoreMap.set(r.id, { score: normalized, result: r });
+    // Reciprocal Rank Fusion (RRF) constant
+    const RRF_K = 60;
+    // Build FTS rank map: rank 1 = best BM25, rank 2 = second best, etc.
+    // FTS results are already sorted by bm25Score (ascending, more negative = better)
+    const ftsRankMap = new Map();
+    for (let i = 0; i < ftsResults.length; i++) {
+        const r = ftsResults[i];
+        ftsRankMap.set(r.id, { rank: i + 1, result: r });
+    }
+    // Build embedding rank map: sort by cosine similarity descending
+    const embedRankMap = new Map();
+    if (embeddingScores) {
+        const sortedEmbeddings = [...embeddingScores.entries()].sort((a, b) => b[1] - a[1]);
+        for (let i = 0; i < sortedEmbeddings.length; i++) {
+            embedRankMap.set(sortedEmbeddings[i][0], i + 1);
+        }
     }
-    // Blend scores
+    // Merge results using RRF
     const scored = [];
     const seenIds = new Set();
     // Process FTS results
-    for (const [id, { score: ftsScore, result }] of ftsScoreMap) {
+    for (const [id, { rank, result }] of ftsRankMap) {
         seenIds.add(id);
-        const embScore = embeddingScores?.get(id);
-        if (embScore !== undefined) {
-            const blended = embScore * 0.7 + ftsScore * 0.3;
-            if (blended > 0)
-                scored.push({ id, entry: result.entry, filePath: result.filePath, score: blended, rankingMode: "semantic" });
-        }
-        else if (ftsScore > 0) {
-            scored.push({ id, entry: result.entry, filePath: result.filePath, score: ftsScore, rankingMode: "fts" });
-        }
+        const ftsRrf = 1 / (RRF_K + rank);
+        const embedRank = embedRankMap.get(id);
+        const embedRrf = embedRank !== undefined ? 1 / (RRF_K + embedRank) : 0;
+        const rrfScore = ftsRrf + embedRrf;
+        const rankingMode = embedRrf > 0 ? "semantic" : "fts";
+        scored.push({ id, entry: result.entry, filePath: result.filePath, score: rrfScore, rankingMode });
     }
     // Add vec-only results not already in FTS results
     if (embeddingScores) {
-        for (const [id, embScore] of embeddingScores) {
+        for (const [id] of embeddingScores) {
             if (seenIds.has(id))
                 continue;
+            const embedRank = embedRankMap.get(id);
             const found = getEntryById(db, id);
             if (found) {
                 if (typeFilter && found.entry.type !== typeFilter)
                     continue;
+                const rrfScore = 1 / (RRF_K + embedRank);
                 scored.push({
                     id,
                     entry: found.entry,
                     filePath: found.filePath,
-                    score: embScore,
+                    score: rrfScore,
                     rankingMode: "semantic",
                 });
             }
         }
     }
-    // Apply boosts (tag, intent, name matches)
+    // Apply boosts as multiplicative factors
     const queryTokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     for (const item of scored) {
         const entry = item.entry;
+        let boostSum = 0;
         // Tag boost
         if (entry.tags) {
             for (const tag of entry.tags) {
                 if (queryTokens.some((t) => tag.toLowerCase() === t)) {
-                    item.score += 0.15;
+                    boostSum += 0.15;
                 }
             }
         }
@@ -218,7 +240,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
                 const intentLower = intent.toLowerCase();
                 for (const token of queryTokens) {
                     if (intentLower.includes(token)) {
-                        item.score += 0.12;
+                        boostSum += 0.12;
                         break;
                     }
                 }
@@ -227,11 +249,9 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         // Name boost
         const nameLower = entry.name.toLowerCase().replace(/[-_]/g, " ");
         if (queryTokens.some((t) => nameLower.includes(t))) {
-            item.score += 0.1;
+            boostSum += 0.1;
         }
-    }
-    for (const item of scored) {
-        item.score = Math.min(item.score, 1.0);
+        item.score = item.score * (1 + boostSum);
     }
     scored.sort((a, b) => b.score - a.score);
     const rankMs = Date.now() - tRank0;
@@ -246,6 +266,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         allStashDirs,
         sources,
         includeItemUsage: shouldIncludeItemUsage(usageMode),
+        config,
     }));
     return {
         embedMs,
@@ -258,7 +279,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
 }
 // ── Vector scorer ───────────────────────────────────────────────────────────
 async function tryVecScores(db, query, k, config) {
-    if (!config.semanticSearch || !isVecAvailable())
+    if (!config.semanticSearch)
         return null;
     const hasEmbeddings = getMeta(db, "hasEmbeddings");
     if (hasEmbeddings !== "1")
@@ -281,13 +302,13 @@ async function tryVecScores(db, query, k, config) {
     }
 }
 // ── Substring fallback (no index) ───────────────────────────────────────────
-function substringSearch(query, searchType, limit, stashDir, sources) {
+function substringSearch(query, searchType, limit, stashDir, sources, config) {
     const assets = indexAssets(stashDir, searchType);
     return assets
         .filter((asset) => asset.name.toLowerCase().includes(query))
         .sort(compareAssets)
         .slice(0, limit)
-        .map((asset) => assetToSearchHit(asset, stashDir, sources));
+        .map((asset) => assetToSearchHit(asset, stashDir, sources, config));
 }
 // ── Hit building ────────────────────────────────────────────────────────────
 function buildDbHit(input) {
@@ -297,9 +318,10 @@ function buildDbHit(input) {
         ?? input.entry.name;
     const qualityBoost = input.entry.generated === true ? 0 : 0.05;
     const confidenceBoost = typeof input.entry.confidence === "number" ? Math.min(0.05, Math.max(0, input.entry.confidence) * 0.05) : 0;
-    const score = Math.min(Math.round((input.score + qualityBoost + confidenceBoost) * 1000) / 1000, 1.0);
+    const score = Math.round(input.score * (1 + qualityBoost + confidenceBoost) * 1000) / 1000;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost);
     const source = findSourceForPath(input.path, input.sources);
+    const editable = isEditable(input.path, input.config);
     const hit = {
         hitSource: "local",
         type: input.entry.type,
@@ -307,7 +329,8 @@ function buildDbHit(input) {
         path: input.path,
         openRef: makeAssetRef(input.entry.type, openRefName, source?.registryId),
         registryId: source?.registryId,
-        editable: source?.writable ?? false,
+        editable,
+        ...(!editable ? { editHint: buildEditHint(input.path, input.entry.type, openRefName, source?.registryId) } : {}),
         description: input.entry.description,
         tags: input.entry.tags,
         score,
@@ -344,8 +367,9 @@ function buildWhyMatched(entry, query, rankingMode, qualityBoost, confidenceBoos
     return reasons;
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function assetToSearchHit(asset, stashDir, sources) {
+function assetToSearchHit(asset, stashDir, sources, config) {
     const source = findSourceForPath(asset.path, sources);
+    const editable = isEditable(asset.path, config);
     const hit = {
         hitSource: "local",
         type: asset.type,
@@ -353,7 +377,8 @@ function assetToSearchHit(asset, stashDir, sources) {
         path: asset.path,
         openRef: makeAssetRef(asset.type, asset.name, source?.registryId),
         registryId: source?.registryId,
-        editable: source?.writable ?? false,
+        editable,
+        ...(!editable ? { editHint: buildEditHint(asset.path, asset.type, asset.name, source?.registryId) } : {}),
     };
     const handler = tryGetHandler(asset.type);
     if (handler?.enrichSearchHit) {
@@ -383,22 +408,9 @@ function parseSearchSource(source) {
     throw new Error(`Invalid search source: ${String(source)}. Expected one of: local|registry|both`);
 }
 function mergeSearchHits(localHits, registryHits, limit) {
-    const merged = [];
-    let localIndex = 0;
-    let registryIndex = 0;
-    while (merged.length < limit && (localIndex < localHits.length || registryIndex < registryHits.length)) {
-        if (localIndex < localHits.length) {
-            merged.push(localHits[localIndex]);
-            localIndex += 1;
-            if (merged.length >= limit)
-                break;
-        }
-        if (registryIndex < registryHits.length) {
-            merged.push(registryHits[registryIndex]);
-            registryIndex += 1;
-        }
-    }
-    return merged;
+    const all = [...localHits, ...registryHits];
+    all.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    return all.slice(0, limit);
 }
 function shouldIncludeUsageGuide(mode) {
     return mode === "both" || mode === "guide";

package/dist/{src/stash-show.js → stash-show.js}

@@ -3,9 +3,12 @@ import { parseAssetRef } from "./stash-ref";
 import { resolveSourcesForOrigin } from "./origin-resolve";
 import { resolveAssetPath } from "./stash-resolve";
 import { getHandler } from "./asset-type-handler";
-import { resolveStashSources, findSourceForPath } from "./stash-source";
+import { resolveStashSources, findSourceForPath, isEditable, buildEditHint } from "./stash-source";
+import { buildFileContext, runMatchers, getRenderer, buildRenderContext } from "./file-context";
+import { loadConfig } from "./config";
 export async function agentikitShow(input) {
     const parsed = parseAssetRef(input.ref);
+    const config = loadConfig();
     const allSources = resolveStashSources();
     const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
     const allStashDirs = searchSources.map((s) => s.path);
@@ -28,8 +31,30 @@ export async function agentikitShow(input) {
     if (!assetPath) {
         throw lastError ?? new Error(`Stash asset not found for ref: ${parsed.type}:${parsed.name}`);
     }
-    const content = fs.readFileSync(assetPath, "utf8");
     const source = findSourceForPath(assetPath, allSources);
+    const sourceStashDir = source?.path ?? allStashDirs[0];
+    // Try new renderer pipeline first
+    if (sourceStashDir) {
+        const fileCtx = buildFileContext(sourceStashDir, assetPath);
+        const match = runMatchers(fileCtx);
+        if (match) {
+            match.meta = { ...match.meta, name: parsed.name, view: input.view };
+            const renderer = getRenderer(match.renderer);
+            if (renderer) {
+                const renderCtx = buildRenderContext(fileCtx, match, allStashDirs);
+                const response = renderer.buildShowResponse(renderCtx);
+                const editable = isEditable(assetPath, config);
+                return {
+                    ...response,
+                    registryId: source?.registryId,
+                    editable,
+                    ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
+                };
+            }
+        }
+    }
+    // Fallback to legacy handler
+    const content = fs.readFileSync(assetPath, "utf8");
     const handler = getHandler(parsed.type);
     const response = handler.buildShowResponse({
         name: parsed.name,
@@ -38,9 +63,11 @@ export async function agentikitShow(input) {
         view: input.view,
         stashDirs: allStashDirs,
     });
+    const editable = isEditable(assetPath, config);
     return {
         ...response,
         registryId: source?.registryId,
-        editable: source?.writable ?? false,
+        editable,
+        ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
     };
 }

package/dist/{src/stash-source.js → stash-source.js}

@@ -4,23 +4,26 @@ import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
- * Build the ordered list of stash sources:
- *   1. Working stash (writable)
- *   2. Mounted stash dirs (read-only, user-configured)
- *   3. Installed stash dirs (read-only, derived from registry.installed)
+ * Build the ordered list of stash sources (search paths):
+ *   1. Primary stash dir (user's own, destination for clone)
+ *   2. Additional search paths (user-configured)
+ *   3. Installed kit paths (cache-managed, from registry)
+ *
+ * The first entry is always the primary stash. Additional entries come
+ * from `searchPaths` config and `registry.installed` entries.
  */
 export function resolveStashSources(overrideStashDir) {
     const stashDir = overrideStashDir ?? resolveStashDir();
     const config = loadConfig();
     const sources = [
-        { kind: "working", path: stashDir, writable: true },
+        { path: stashDir },
     ];
-    for (const dir of config.mountedStashDirs) {
+    for (const dir of config.searchPaths) {
         if (isSuspiciousStashRoot(dir)) {
             console.warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`);
         }
         if (isValidDirectory(dir)) {
-            sources.push({ kind: "mounted", path: dir, writable: false });
+            sources.push({ path: dir });
         }
     }
     for (const entry of config.registry?.installed ?? []) {
@@ -29,10 +32,8 @@ export function resolveStashSources(overrideStashDir) {
         }
         if (isValidDirectory(entry.stashRoot)) {
             sources.push({
-                kind: "installed",
                 path: entry.stashRoot,
                 registryId: entry.id,
-                writable: false,
             });
         }
     }
@@ -55,6 +56,52 @@ export function findSourceForPath(filePath, sources) {
     }
     return undefined;
 }
+/**
+ * Return the primary stash source (first entry in the list).
+ * This is the user's working stash and the default destination for clone.
+ */
+export function getPrimarySource(sources) {
+    return sources[0];
+}
+// ── Editability ─────────────────────────────────────────────────────────────
+/**
+ * Determine whether a file is safe to edit in place.
+ *
+ * The only files that are NOT editable are those inside a cache directory
+ * managed by the package manager (`registry.installed[].cacheDir`). These
+ * will be overwritten by `akm update` without warning.
+ *
+ * Everything else — working stash, search paths, local project dirs — is
+ * the user's domain to manage.
+ */
+export function isEditable(filePath, config) {
+    const cfg = config ?? loadConfig();
+    const resolved = path.resolve(filePath);
+    const cacheManaged = cfg.registry?.installed ?? [];
+    const isWin = process.platform === "win32";
+    for (const entry of cacheManaged) {
+        const cacheRoot = path.resolve(entry.cacheDir);
+        if (isWin) {
+            // Windows paths are case-insensitive — normalize both sides
+            if (resolved.toLowerCase().startsWith(cacheRoot.toLowerCase() + path.sep))
+                return false;
+        }
+        else {
+            if (resolved.startsWith(cacheRoot + path.sep))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Build an actionable hint for the agent when a file is not editable.
+ * Callers must check `isEditable()` before calling — this function
+ * unconditionally returns the hint string.
+ */
+export function buildEditHint(filePath, assetType, assetName, origin) {
+    const ref = origin ? `${origin}//${assetType}:${assetName}` : `${assetType}:${assetName}`;
+    return `This asset is managed by akm and may be overwritten on update. To edit, run: akm clone ${ref}`;
+}
 // ── Validation ──────────────────────────────────────────────────────────────
 const SUSPICIOUS_ROOTS = new Set(['/', '/etc', '/bin', '/sbin', '/usr', '/var', '/tmp', '/dev', '/proc', '/sys']);
 function isSuspiciousStashRoot(dir) {