akm-cli 0.5.0-rc2 → 0.5.0-rc4

package/dist/cli.js

@@ -320,6 +320,12 @@ function formatPlain(command, result, detail) {
         case "index": {
             const indexResult = result;
             let out = `Indexed ${indexResult.totalEntries ?? 0} entries from ${indexResult.directoriesScanned ?? 0} directories (mode: ${indexResult.mode ?? "unknown"})`;
+            const warnings = indexResult.warnings;
+            if (Array.isArray(warnings) && warnings.length > 0) {
+                out += `\nWarnings (${warnings.length}):`;
+                for (const message of warnings)
+                    out += `\n  - ${String(message)}`;
+            }
             const verification = indexResult.verification;
             if (verification?.ok === false && verification.message) {
                 out += `\nVerification: ${String(verification.message)}`;
@@ -458,6 +464,8 @@ function formatPlain(command, result, detail) {
                 const ver = typeof src.version === "string" ? ` v${src.version}` : "";
                 const prov = typeof src.provider === "string" ? ` (${src.provider})` : "";
                 const flags = [];
+                if (typeof src.wiki === "string")
+                    flags.push(`wiki:${src.wiki}`);
                 if (src.updatable === true)
                     flags.push("updatable");
                 if (src.writable === true)
@@ -472,6 +480,12 @@ function formatPlain(command, result, detail) {
             const scanned = index?.directoriesScanned ?? 0;
             const total = index?.totalEntries ?? 0;
             const lines = [`Installed ${r.ref} (${scanned} directories scanned, ${total} total assets indexed)`];
+            const warnings = index?.warnings;
+            if (Array.isArray(warnings) && warnings.length > 0) {
+                lines.push(`Warnings (${warnings.length}):`);
+                for (const message of warnings)
+                    lines.push(`  - ${String(message)}`);
+            }
             const installed = r.installed;
             const audit = installed?.audit;
             if (audit && typeof audit === "object") {
@@ -651,7 +665,7 @@ function formatSearchPlain(r, detail) {
 function formatWikiListPlain(r) {
     const wikis = Array.isArray(r.wikis) ? r.wikis : [];
     if (wikis.length === 0)
-        return "No wikis. Create one with `akm wiki create <name>`.";
+        return "No wikis. Create one with `akm wiki create <name>` or register one with `akm wiki register <name> <path-or-repo>`.";
     const lines = ["NAME\tPAGES\tRAWS\tLAST-MODIFIED"];
     for (const w of wikis) {
         const name = typeof w.name === "string" ? w.name : "?";
@@ -1205,11 +1219,19 @@ const addCommand = defineCommand({
             if (shouldWarnOnPlainHttp(ref)) {
                 warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
             }
-            const websiteOptions = {};
-            if (args["max-pages"])
-                websiteOptions.maxPages = args["max-pages"];
-            if (args["max-depth"])
-                websiteOptions.maxDepth = args["max-depth"];
+            const websiteOptions = buildWebsiteOptions(args);
+            if (args.type === "wiki") {
+                const { registerWikiSource } = await import("./stash-add");
+                const result = await registerWikiSource({
+                    ref,
+                    name: args.name,
+                    options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
+                    trustThisInstall: args.trust,
+                    writable: args.writable,
+                });
+                output("add", result);
+                return;
+            }
             const result = await akmAdd({
                 ref,
                 name: args.name,
@@ -1222,6 +1244,14 @@ const addCommand = defineCommand({
         });
     },
 });
+function buildWebsiteOptions(args) {
+    const websiteOptions = {};
+    if (typeof args["max-pages"] === "string" && args["max-pages"].length > 0)
+        websiteOptions.maxPages = args["max-pages"];
+    if (typeof args["max-depth"] === "string" && args["max-depth"].length > 0)
+        websiteOptions.maxDepth = args["max-depth"];
+    return websiteOptions;
+}
 const VALID_SOURCE_KINDS = new Set(["local", "managed", "remote"]);
 function parseKindFilter(raw) {
     if (!raw)
@@ -2464,6 +2494,41 @@ const wikiCreateCommand = defineCommand({
         });
     },
 });
+const wikiRegisterCommand = defineCommand({
+    meta: {
+        name: "register",
+        description: "Register an existing directory or repo as a first-class wiki without copying or mutating it; refreshes source and wiki search state immediately",
+    },
+    args: {
+        name: { type: "positional", description: "Wiki name (lowercase, digits, hyphens)", required: true },
+        ref: { type: "positional", description: "Path or repo ref for the external wiki source", required: true },
+        writable: {
+            type: "boolean",
+            description: "Mark a git-backed source as writable so changes can be pushed back",
+            default: false,
+        },
+        trust: {
+            type: "boolean",
+            description: "Bypass install-audit blocking for this registration only",
+            default: false,
+        },
+        "max-pages": { type: "string", description: "Maximum pages to crawl for website sources (default: 50)" },
+        "max-depth": { type: "string", description: "Maximum crawl depth for website sources (default: 3)" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { registerWikiSource } = await import("./stash-add");
+            const result = await registerWikiSource({
+                ref: args.ref.trim(),
+                name: args.name,
+                options: Object.keys(buildWebsiteOptions(args)).length > 0 ? buildWebsiteOptions(args) : undefined,
+                trustThisInstall: args.trust,
+                writable: args.writable,
+            });
+            output("wiki-register", result);
+        });
+    },
+});
 const wikiListCommand = defineCommand({
     meta: { name: "list", description: "List wikis with page/raw counts and last-modified timestamps" },
     run() {
@@ -2492,7 +2557,7 @@ const wikiShowCommand = defineCommand({
 const wikiRemoveCommand = defineCommand({
     meta: {
         name: "remove",
-        description: "Remove a wiki. Preserves raw/ by default; pass --with-sources to also delete raw/",
+        description: "Remove a wiki and refresh the index. Preserves raw/ by default; pass --with-sources to also delete raw/",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
@@ -2514,8 +2579,10 @@ const wikiRemoveCommand = defineCommand({
             }
             const withSources = Boolean(args["with-sources"]);
             const { removeWiki } = await import("./wiki.js");
+            const { akmIndex } = await import("./indexer");
             const stashDir = resolveStashDir();
             const result = removeWiki(stashDir, args.name, { withSources });
+            await akmIndex({ stashDir });
             output("wiki-remove", result);
         });
     },
@@ -2540,7 +2607,7 @@ const wikiPagesCommand = defineCommand({
 const wikiSearchCommand = defineCommand({
     meta: {
         name: "search",
-        description: "Search wiki pages within a single wiki (scoped wrapper over `akm search --type wiki`; excludes raw/schema/index/log)",
+        description: "Search wiki pages within a single wiki (scoped wrapper over `akm search --type wiki`; excludes raw/schema/index/log and returns canonical wiki refs)",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
@@ -2549,12 +2616,9 @@ const wikiSearchCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { searchInWiki } = await import("./wiki.js");
+            const { resolveWikiSource, searchInWiki } = await import("./wiki.js");
             const stashDir = resolveStashDir();
-            const wikiDir = path.join(stashDir, "wikis", args.name);
-            if (!fs.existsSync(wikiDir)) {
-                throw new NotFoundError(`Wiki not found: ${args.name}`);
-            }
+            resolveWikiSource(stashDir, args.name);
             const parsedLimit = args.limit ? Number(args.limit) : undefined;
             const limit = typeof parsedLimit === "number" && Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : undefined;
             const response = await searchInWiki({ stashDir, wikiName: args.name, query: args.query, limit });
@@ -2633,6 +2697,7 @@ const wikiCommand = defineCommand({
     },
     subCommands: {
         create: wikiCreateCommand,
+        register: wikiRegisterCommand,
         list: wikiListCommand,
         show: wikiShowCommand,
         remove: wikiRemoveCommand,
@@ -2695,7 +2760,18 @@ const main = defineCommand({
 });
 const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "get", "set", "unset"]);
 const VAULT_SUBCOMMAND_SET = new Set(["list", "show", "create", "set", "unset", "load"]);
-const WIKI_SUBCOMMAND_SET = new Set(["create", "list", "show", "remove", "pages", "search", "stash", "lint", "ingest"]);
+const WIKI_SUBCOMMAND_SET = new Set([
+    "create",
+    "register",
+    "list",
+    "show",
+    "remove",
+    "pages",
+    "search",
+    "stash",
+    "lint",
+    "ingest",
+]);
 const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
 // citty reads process.argv directly and does not accept a custom argv array,
 // so we must replace process.argv with the normalized version before runMain.
@@ -2974,14 +3050,15 @@ ranking can learn from actual usage.
 
 ## Wikis
 
-Multi-wiki knowledge bases (Karpathy-style). Each wiki is a directory at
-\`<stashDir>/wikis/<name>/\` with \`schema.md\`, \`index.md\`, \`log.md\`, \`raw/\`,
-and agent-authored pages. akm owns lifecycle + raw-slug + lint + index
-regeneration; page edits use your native Read/Write/Edit tools.
+Multi-wiki knowledge bases (Karpathy-style). A stash-owned wiki lives at
+\`<stashDir>/wikis/<name>/\`; external directories or repos can also be registered
+as first-class wikis. akm owns lifecycle + raw-slug + lint + index regeneration
+for stash-owned wikis; page edits use your native Read/Write/Edit tools.
 
 \`\`\`sh
 akm wiki list                                  # List wikis (name, pages, raws, last-modified)
 akm wiki create research                       # Scaffold a new wiki
+akm wiki register ics-docs ~/code/ics-documentation # Register an external wiki
 akm wiki show research                         # Path, description, counts, last 3 log entries
 akm wiki pages research                        # Page refs + descriptions (excludes schema/index/log/raw)
 akm wiki search research "attention"           # Scoped search (equivalent to --type wiki --wiki research)

package/dist/indexer.js

@@ -80,7 +80,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 } = await indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete);
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete);
         onProgress({
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -166,6 +166,7 @@ export async function akmIndex(options) {
             mode: isIncremental ? "incremental" : "full",
             directoriesScanned: scannedDirs,
             directoriesSkipped: skippedDirs,
+            ...(warnings.length > 0 ? { warnings } : {}),
             verification,
             timing: {
                 totalMs: tEnd - t0,
@@ -185,6 +186,7 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
+    const warnings = [];
     const seenPaths = new Set();
     const dirsNeedingLlm = [];
     const dirRecords = [];
@@ -261,6 +263,8 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
                 const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
                 if (uncoveredFiles.length > 0) {
                     const generated = await generateMetadataFlat(currentStashDir, uncoveredFiles);
+                    if (generated.warnings?.length)
+                        warnings.push(...generated.warnings);
                     if (generated.entries.length > 0) {
                         stash = { entries: [...stash.entries, ...generated.entries] };
                         generatedCount += generated.entries.length;
@@ -269,6 +273,8 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
             }
             if (!stash) {
                 const generated = await generateMetadataFlat(currentStashDir, files);
+                if (generated.warnings?.length)
+                    warnings.push(...generated.warnings);
                 if (generated.entries.length > 0) {
                     stash = { entries: generated.entries };
                     generatedCount += generated.entries.length;
@@ -351,7 +357,7 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
         }
     });
     insertTransaction();
-    return { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm };
+    return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
 }
 async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     if (!config.llm || dirsNeedingLlm.length === 0)

package/dist/installed-kits.js

@@ -29,6 +29,7 @@ export async function akmListSources(input) {
         sources.push({
             name,
             kind,
+            wiki: stash.wikiName,
             path: stash.path,
             provider: isRemote ? stash.type : undefined,
             updatable: false,
@@ -44,6 +45,7 @@ export async function akmListSources(input) {
         sources.push({
             name: entry.id,
             kind,
+            wiki: entry.wikiName,
             path: entry.stashRoot,
             ref: entry.ref,
             version: entry.resolvedVersion,

package/dist/local-search.js

@@ -29,6 +29,15 @@ export function buildLocalAction(type, ref) {
     const builder = ACTION_BUILDERS[type];
     return builder ? builder(ref) : `akm show ${ref}`;
 }
+function resolveSearchHitRef(entry, refName, source) {
+    if (source?.wikiName) {
+        return makeAssetRef(entry.type, entry.name);
+    }
+    return makeAssetRef(entry.type, refName, source?.registryId);
+}
+function resolveSearchHitOrigin(source) {
+    return source?.wikiName ? null : (source?.registryId ?? null);
+}
 // ── Main search entrypoint ───────────────────────────────────────────────────
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
@@ -393,7 +402,7 @@ async function tryVecScores(db, query, k, config) {
 }
 // ── Substring fallback (no index) ───────────────────────────────────────────
 async function substringSearch(query, searchType, limit, stashDir, sources, config) {
-    const assets = await indexAssets(stashDir, searchType);
+    const assets = await indexAssets(stashDir, searchType, sources);
     const matched = assets.filter((asset) => !query || buildSearchText(asset.entry).includes(query));
     if (!query) {
         const sorted = matched.sort(compareAssets);
@@ -448,20 +457,21 @@ export async function buildDbHit(input) {
     const score = Math.round(input.score * 10000) / 10000;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost, input.utilityBoosted);
     const source = findSourceForPath(input.path, input.sources);
+    const ref = resolveSearchHitRef(input.entry, refName, source);
     const editable = isEditable(input.path, input.config);
     const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
     const hit = {
         type: input.entry.type,
         name: input.entry.name,
         path: input.path,
-        ref: makeAssetRef(input.entry.type, refName, source?.registryId),
-        origin: source?.registryId ?? null,
+        ref,
+        origin: resolveSearchHitOrigin(source),
         editable,
         ...(!editable ? { editHint: buildEditHint(input.path, input.entry.type, refName, source?.registryId) } : {}),
         description: input.entry.description,
         tags: input.entry.tags,
         size: deriveSize(input.entry.fileSize),
-        action: buildLocalAction(input.entry.type, makeAssetRef(input.entry.type, refName, source?.registryId)),
+        action: buildLocalAction(input.entry.type, ref),
         score,
         whyMatched,
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
@@ -523,7 +533,7 @@ rankingMode, qualityBoost, confidenceBoost, utilityBoosted) {
 async function assetToSearchHit(asset, stashDir, sources, config, score) {
     const source = findSourceForPath(asset.path, sources);
     const editable = isEditable(asset.path, config);
-    const ref = makeAssetRef(asset.entry.type, asset.entry.name, source?.registryId);
+    const ref = resolveSearchHitRef(asset.entry, asset.entry.name, source);
     const fileSize = readFileSize(asset.path);
     const size = deriveSize(fileSize);
     const estimatedTokens = typeof fileSize === "number" ? Math.round(fileSize / 4) : undefined;
@@ -532,7 +542,7 @@ async function assetToSearchHit(asset, stashDir, sources, config, score) {
         name: asset.entry.name,
         path: asset.path,
         ref,
-        origin: source?.registryId ?? null,
+        origin: resolveSearchHitOrigin(source),
         editable,
         ...(!editable
             ? { editHint: buildEditHint(asset.path, asset.entry.type, asset.entry.name, source?.registryId) }
@@ -568,7 +578,12 @@ function readFileSize(filePath) {
         return undefined;
     }
 }
-async function indexAssets(stashDir, type) {
+async function indexAssets(stashDir, type, sources) {
+    const resolvedStashDir = realpathOrResolve(stashDir);
+    const source = sources?.find((entry) => realpathOrResolve(entry.path) === resolvedStashDir);
+    if (source?.wikiName) {
+        return indexWikiRootAssets(stashDir, source.wikiName, type);
+    }
     const assets = [];
     const filterType = type === "any" ? undefined : type;
     const fileContexts = walkStashFlat(stashDir);
@@ -626,6 +641,29 @@ async function indexAssets(stashDir, type) {
     }
     return assets;
 }
+async function indexWikiRootAssets(wikiRoot, wikiName, type) {
+    if (type !== "any" && type !== "wiki")
+        return [];
+    const assets = [];
+    for (const ctx of walkStashFlat(wikiRoot)) {
+        if (ctx.ext !== ".md")
+            continue;
+        if (!shouldIndexStashFile(wikiRoot, ctx.absPath, { treatStashRootAsWikiRoot: true }))
+            continue;
+        const relNoExt = ctx.relPath.replace(/\.md$/, "");
+        assets.push({
+            entry: {
+                name: `${wikiName}/${relNoExt}`,
+                type: "wiki",
+                filename: ctx.fileName,
+                description: ctx.frontmatter()?.description,
+                source: "frontmatter",
+            },
+            path: ctx.absPath,
+        });
+    }
+    return assets;
+}
 function compareAssets(a, b) {
     if (a.entry.type !== b.entry.type)
         return a.entry.type.localeCompare(b.entry.type);
@@ -659,3 +697,11 @@ function deduplicateAssetsByPath(assets) {
         return true;
     });
 }
+function realpathOrResolve(targetPath) {
+    try {
+        return fs.realpathSync(targetPath);
+    }
+    catch {
+        return path.resolve(targetPath);
+    }
+}

package/dist/metadata.js

@@ -362,6 +362,7 @@ function mergeParameters(existing, additional) {
 // ── Metadata Generation ─────────────────────────────────────────────────────
 export async function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
+    const warnings = [];
     const pkgMeta = extractPackageMetadata(dirPath);
     for (const file of files) {
         const ext = path.extname(file).toLowerCase();
@@ -428,7 +429,13 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
             const renderer = await getRenderer(match.renderer);
             if (renderer?.extractMetadata) {
                 const renderCtx = buildRenderContext(fileCtx, match, [typeRoot]);
-                renderer.extractMetadata(entry, renderCtx);
+                try {
+                    renderer.extractMetadata(entry, renderCtx);
+                }
+                catch (error) {
+                    warnings.push(buildMetadataSkipWarning(file, assetType, error));
+                    continue;
+                }
             }
         }
         // Priority 4: Filename heuristics (fallback)
@@ -447,7 +454,7 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
         entry.filename = path.basename(file);
         entries.push(entry);
     }
-    return { entries };
+    return warnings.length > 0 ? { entries, warnings } : { entries };
 }
 /**
  * Generate metadata for files using the matcher system instead of a fixed asset type.
@@ -458,6 +465,7 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
  */
 export async function generateMetadataFlat(stashRoot, files) {
     const entries = [];
+    const warnings = [];
     const pkgMetaCache = new Map();
     for (const file of files) {
         if (!shouldIndexStashFile(stashRoot, file))
@@ -534,7 +542,13 @@ export async function generateMetadataFlat(stashRoot, files) {
         const renderer = await getRenderer(match.renderer);
         if (renderer?.extractMetadata) {
             const renderCtx = buildRenderContext(ctx, match, [stashRoot]);
-            renderer.extractMetadata(entry, renderCtx);
+            try {
+                renderer.extractMetadata(entry, renderCtx);
+            }
+            catch (error) {
+                warnings.push(buildMetadataSkipWarning(file, assetType, error));
+                continue;
+            }
         }
         // Filename heuristics fallback
         if (!entry.description) {
@@ -550,7 +564,13 @@ export async function generateMetadataFlat(stashRoot, files) {
         entry.filename = path.basename(file);
         entries.push(entry);
     }
-    return { entries };
+    return warnings.length > 0 ? { entries, warnings } : { entries };
+}
+function buildMetadataSkipWarning(filePath, assetType, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const warning = `Skipped malformed ${assetType} asset at ${filePath}: ${detail}`;
+    warn(warning);
+    return warning;
 }
 function normalizeTerms(values) {
     const normalized = new Set();

package/dist/stash-add.js

@@ -9,7 +9,7 @@ import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } fro
 import { parseRegistryRef } from "./registry-resolve";
 import { ensureWebsiteMirror, validateWebsiteInputUrl } from "./stash-providers/website";
 import { warn } from "./warn";
-import { validateWikiName } from "./wiki";
+import { ensureWikiNameAvailable, validateWikiName } from "./wiki";
 const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
 export async function akmAdd(input) {
     const ref = input.ref.trim();
@@ -47,6 +47,20 @@ export async function akmAdd(input) {
     }
     return addRegistryKit(ref, stashDir, input.trustThisInstall, input.writable, wikiName);
 }
+export async function registerWikiSource(input) {
+    const stashDir = resolveStashDir();
+    const name = input.name ?? deriveWikiNameFromRef(input.ref);
+    validateWikiName(name);
+    ensureWikiNameAvailable(stashDir, name);
+    return akmAdd({
+        ref: input.ref,
+        name,
+        overrideType: "wiki",
+        options: input.options,
+        trustThisInstall: input.trustThisInstall,
+        writable: input.writable,
+    });
+}
 /**
  * Add a local directory as a filesystem stash source.
  * Creates a stashes[] entry instead of an installed[] entry.
@@ -58,31 +72,36 @@ async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
     // Check for duplicates in stashes[]
     const stashes = [...(config.stashes ?? [])];
     const existing = stashes.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
+    let persistedEntry;
     if (!existing) {
-        const entry = {
+        persistedEntry = {
             type: "filesystem",
             path: resolvedPath,
             name: wikiName ?? toReadableId(resolvedPath),
             ...(wikiName ? { wikiName } : {}),
         };
-        stashes.push(entry);
+        stashes.push(persistedEntry);
         saveConfig({ ...config, stashes });
     }
-    else if (wikiName && existing.wikiName !== wikiName) {
-        existing.wikiName = wikiName;
-        saveConfig({ ...config, stashes });
+    else {
+        if (wikiName && existing.wikiName !== wikiName) {
+            existing.wikiName = wikiName;
+            saveConfig({ ...config, stashes });
+        }
+        persistedEntry = existing;
     }
     const index = await akmIndex({ stashDir });
     const updatedConfig = loadConfig();
     return {
         schemaVersion: 1,
         stashDir,
-        ref,
+        ref: wikiName ?? ref,
         stashSource: {
             type: "filesystem",
             path: resolvedPath,
-            name: toReadableId(resolvedPath),
+            name: persistedEntry.name ?? toReadableId(resolvedPath),
             stashRoot: resolvedPath,
+            ...(persistedEntry.wikiName ? { wiki: persistedEntry.wikiName } : {}),
         },
         config: {
             stashCount: updatedConfig.stashes?.length ?? 0,
@@ -93,6 +112,7 @@ async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
             totalEntries: index.totalEntries,
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
+            ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
 }
@@ -131,12 +151,13 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
     return {
         schemaVersion: 1,
         stashDir,
-        ref,
+        ref: wikiName ?? ref,
         stashSource: {
             type: "website",
             url: normalizedUrl,
             name: entry.name,
             stashRoot: cachePaths.stashDir,
+            ...(entry.wikiName ? { wiki: entry.wikiName } : {}),
         },
         config: {
             stashCount: updatedConfig.stashes?.length ?? 0,
@@ -147,6 +168,7 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
             totalEntries: index.totalEntries,
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
+            ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
 }
@@ -213,6 +235,7 @@ async function addRegistryKit(ref, stashDir, trustThisInstall, writable, wikiNam
             totalEntries: index.totalEntries,
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
+            ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
 }

package/dist/stash-show.js

@@ -22,11 +22,7 @@ import "./stash-providers/index";
  * `/`, e.g. `wiki:research`.
  */
 async function showWikiRoot(stashDir, wikiName) {
-    const { showWiki, resolveWikiDir } = await import("./wiki.js");
-    const wikiDir = resolveWikiDir(stashDir, wikiName);
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${wikiName}. Run \`akm wiki create ${wikiName}\` to create it.`);
-    }
+    const { showWiki } = await import("./wiki.js");
     const result = showWiki(stashDir, wikiName);
     // Shape the WikiShowResult into a ShowResponse-compatible object.
     // The payload mirrors what `akm wiki show <name>` returns.
@@ -43,6 +39,44 @@ async function showWikiRoot(stashDir, wikiName) {
         recentLog: result.recentLog,
     };
 }
+async function showWikiRootForSource(stashDir, source, wikiName) {
+    const { showWikiAtPath } = await import("./wiki.js");
+    if (source.wikiName === wikiName) {
+        const result = showWikiAtPath(wikiName, source.path);
+        return {
+            type: "wiki",
+            name: result.ref,
+            path: result.path,
+            ...(result.description ? { description: result.description } : {}),
+            origin: null,
+            editable: false,
+            pages: result.pages,
+            raws: result.raws,
+            ...(result.lastModified ? { lastModified: result.lastModified } : {}),
+            recentLog: result.recentLog,
+        };
+    }
+    return showWikiRoot(stashDir, wikiName);
+}
+function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
+    const pageName = assetName === wikiName ? "" : assetName.slice(wikiName.length + 1);
+    if (!pageName) {
+        throw new NotFoundError(`Wiki page not found: wiki:${assetName}`);
+    }
+    const candidate = path.resolve(wikiRoot, `${pageName}.md`);
+    const resolvedRoot = fs.realpathSync(wikiRoot);
+    if (!candidate.startsWith(resolvedRoot + path.sep)) {
+        throw new UsageError("Ref resolves outside the stash root.");
+    }
+    if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+        throw new NotFoundError(`Stash asset not found for ref: wiki:${assetName}`);
+    }
+    const realTarget = fs.realpathSync(candidate);
+    if (!realTarget.startsWith(resolvedRoot + path.sep)) {
+        throw new UsageError("Ref resolves outside the stash root.");
+    }
+    return realTarget;
+}
 /**
  * Unified show: tries local FTS5 index first, then remote providers.
  *
@@ -63,7 +97,7 @@ export async function akmShowUnified(input) {
             let lastError;
             for (const source of searchSources) {
                 try {
-                    return await showWikiRoot(source.path, parsed.name);
+                    return await showWikiRootForSource(allSources[0]?.path ?? source.path, source, parsed.name);
                 }
                 catch (err) {
                     if (!(err instanceof NotFoundError))
@@ -145,8 +179,19 @@ export async function showLocal(input) {
     const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
     const allStashDirs = searchSources.map((s) => s.path);
     let assetPath;
+    const matchedSource = parsed.type === "wiki" ? searchSources.find((source) => parsed.name.startsWith(`${source.wikiName}/`)) : undefined;
     let lastError;
+    if (parsed.type === "wiki" && matchedSource?.wikiName) {
+        try {
+            assetPath = resolveRegisteredWikiAssetPath(matchedSource.path, matchedSource.wikiName, parsed.name);
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
     for (const dir of allStashDirs) {
+        if (assetPath)
+            break;
         try {
             assetPath = await resolveAssetPath(dir, parsed.type, parsed.name);
             break;
@@ -165,14 +210,17 @@ export async function showLocal(input) {
             new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
                 "Check the name with `akm search` or verify the asset exists in your stash."));
     }
-    const source = findSourceForPath(assetPath, allSources);
+    const source = matchedSource ?? findSourceForPath(assetPath, allSources);
     const sourceStashDir = source?.path ?? allStashDirs[0];
     if (!sourceStashDir) {
         throw new UsageError(`Could not determine stash root for asset: ${displayType}:${parsed.name}. ` +
             "Run `akm init` to create the stash directory, or check `akm stash list` for configured paths.");
     }
     const fileCtx = buildFileContext(sourceStashDir, assetPath);
-    const match = await runMatchers(fileCtx);
+    const forcedWikiMatch = parsed.type === "wiki" && source?.wikiName && parsed.name.startsWith(`${source.wikiName}/`)
+        ? { type: "wiki", specificity: 20, renderer: "wiki-md", meta: {} }
+        : undefined;
+    const match = forcedWikiMatch ?? (await runMatchers(fileCtx));
     if (!match) {
         throw new UsageError(`Could not display asset "${displayType}:${parsed.name}" — unsupported file type or unrecognized layout`);
     }

package/dist/wiki.js

@@ -16,8 +16,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
 import { isWithin } from "./common";
+import { loadUserConfig, saveConfig } from "./config";
 import { NotFoundError, UsageError } from "./errors";
 import { parseFrontmatter, parseFrontmatterBlock } from "./frontmatter";
+import { resolveStashSources } from "./search-source";
 import { akmSearch } from "./stash-search";
 import { buildIndexMd, buildLogMd, buildSchemaMd } from "./templates/wiki-templates";
 // ── Constants ───────────────────────────────────────────────────────────────
@@ -58,6 +60,41 @@ export function extractWikiNameFromRef(ref) {
     const match = ref.match(/^wiki:([a-z0-9][a-z0-9-]*)(?:\/|$)/);
     return match?.[1];
 }
+function wikiNotFoundMessage(name) {
+    return `Wiki not found: ${name}. Run \`akm wiki create ${name}\` to create it or \`akm wiki register ${name} <path-or-repo>\` to register an external wiki.`;
+}
+function registeredWikiSources(stashDir) {
+    return resolveStashSources(stashDir)
+        .filter((source) => typeof source.wikiName === "string")
+        .map((source) => ({
+        name: source.wikiName,
+        path: source.path,
+        mode: "external",
+        source,
+    }));
+}
+export function resolveWikiSource(stashDir, name) {
+    validateWikiName(name);
+    const wikiDir = resolveWikiDir(stashDir, name);
+    if (fs.existsSync(wikiDir)) {
+        return { name, path: wikiDir, mode: "stash" };
+    }
+    const external = registeredWikiSources(stashDir).find((source) => source.name === name);
+    if (external)
+        return external;
+    throw new NotFoundError(wikiNotFoundMessage(name));
+}
+export function ensureWikiNameAvailable(stashDir, name) {
+    validateWikiName(name);
+    const wikiDir = resolveWikiDir(stashDir, name);
+    if (fs.existsSync(wikiDir)) {
+        throw new UsageError(`Wiki already exists: ${name}.`);
+    }
+    const external = registeredWikiSources(stashDir).find((source) => source.name === name);
+    if (external) {
+        throw new UsageError(`Wiki already registered: ${name}.`);
+    }
+}
 /**
  * Walk a wiki directory and bucket files into pages vs raws.
  *
@@ -158,25 +195,20 @@ function toIsoDate(ms) {
  */
 export function listWikis(stashDir) {
     const wikisRoot = resolveWikisRoot(stashDir);
-    if (!fs.existsSync(wikisRoot))
-        return [];
-    let entries;
-    try {
-        entries = fs.readdirSync(wikisRoot, { withFileTypes: true });
-    }
-    catch {
-        return [];
+    const summaries = new Map();
+    let entries = [];
+    if (fs.existsSync(wikisRoot)) {
+        try {
+            entries = fs.readdirSync(wikisRoot, { withFileTypes: true });
+        }
+        catch {
+            entries = [];
+        }
     }
-    const summaries = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        if (!WIKI_NAME_RE.test(entry.name))
-            continue;
-        const dir = path.join(wikisRoot, entry.name);
+    const summarize = (name, dir) => {
         const buckets = scanWikiFiles(dir);
         const summary = {
-            name: entry.name,
+            name,
             path: dir,
             pages: buckets.pages.length,
             raws: buckets.raws.length,
@@ -186,10 +218,21 @@ export function listWikis(stashDir) {
             summary.description = description;
         if (buckets.lastModifiedMs !== undefined)
             summary.lastModified = toIsoDate(buckets.lastModifiedMs);
-        summaries.push(summary);
+        summaries.set(name, summary);
+    };
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (!WIKI_NAME_RE.test(entry.name))
+            continue;
+        summarize(entry.name, path.join(wikisRoot, entry.name));
+    }
+    for (const source of registeredWikiSources(stashDir)) {
+        if (summaries.has(source.name))
+            continue;
+        summarize(source.name, source.path);
     }
-    summaries.sort((a, b) => a.name.localeCompare(b.name));
-    return summaries;
+    return Array.from(summaries.values()).sort((a, b) => a.name.localeCompare(b.name));
 }
 // ── Show ────────────────────────────────────────────────────────────────────
 /**
@@ -238,11 +281,7 @@ function readRecentLog(wikiDir, limit = 3) {
     // Newest-first convention: the top `limit` `##` blocks are the most recent.
     return sections.slice(0, limit);
 }
-export function showWiki(stashDir, name) {
-    const wikiDir = resolveWikiDir(stashDir, name);
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}. Run \`akm wiki create ${name}\` to create it.`);
-    }
+export function showWikiAtPath(name, wikiDir) {
     const buckets = scanWikiFiles(wikiDir);
     const result = {
         name,
@@ -259,8 +298,15 @@ export function showWiki(stashDir, name) {
         result.lastModified = toIsoDate(buckets.lastModifiedMs);
     return result;
 }
+export function showWiki(stashDir, name) {
+    return showWikiAtPath(name, resolveWikiSource(stashDir, name).path);
+}
 // ── Create ──────────────────────────────────────────────────────────────────
 export function createWiki(stashDir, name) {
+    const existing = registeredWikiSources(stashDir).find((source) => source.name === name);
+    if (existing) {
+        throw new UsageError(`Wiki already registered: ${name}.`);
+    }
     const wikiDir = resolveWikiDir(stashDir, name);
     fs.mkdirSync(wikiDir, { recursive: true });
     const files = [
@@ -307,7 +353,25 @@ export function createWiki(stashDir, name) {
  * ignore that (e.g. idempotent cleanup) by catching.
  */
 export function removeWiki(stashDir, name, options = {}) {
-    const wikiDir = resolveWikiDir(stashDir, name);
+    const resolved = resolveWikiSource(stashDir, name);
+    const wikiDir = resolved.path;
+    if (resolved.mode === "external") {
+        const config = loadUserConfig();
+        const stashes = (config.stashes ?? []).filter((entry) => entry.wikiName !== name);
+        const installed = (config.installed ?? []).filter((entry) => entry.wikiName !== name);
+        saveConfig({
+            ...config,
+            stashes: stashes.length > 0 ? stashes : undefined,
+            installed: installed.length > 0 ? installed : undefined,
+        });
+        return {
+            name,
+            path: wikiDir,
+            removed: [],
+            preservedRaw: false,
+            unregistered: true,
+        };
+    }
     if (!fs.existsSync(wikiDir)) {
         throw new NotFoundError(`Wiki not found: ${name}.`);
     }
@@ -420,10 +484,7 @@ function readPageFrontmatter(absPath) {
  * path, and frontmatter-derived fields for orientation.
  */
 export function listPages(stashDir, name) {
-    const wikiDir = resolveWikiDir(stashDir, name);
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}.`);
-    }
+    const wikiDir = resolveWikiSource(stashDir, name).path;
     const { pages } = scanWikiFiles(wikiDir);
     const result = [];
     for (const abs of pages) {
@@ -447,13 +508,22 @@ export function listPages(stashDir, name) {
  */
 export async function searchInWiki(input) {
     validateWikiName(input.wikiName);
-    const wikiDir = resolveWikiDir(input.stashDir, input.wikiName);
     const response = await akmSearch({
         query: input.query,
         type: "wiki",
         limit: input.limit,
         source: "stash",
     });
+    let wikiDir;
+    try {
+        wikiDir = resolveWikiSource(input.stashDir, input.wikiName).path;
+    }
+    catch (err) {
+        if (err instanceof NotFoundError) {
+            return { ...response, hits: [], registryHits: undefined };
+        }
+        throw err;
+    }
     const rawDir = path.join(wikiDir, RAW_SUBDIR);
     const filtered = [];
     for (const hit of response.hits) {
@@ -564,10 +634,7 @@ function ensureTrailingNewline(value) {
  * job (see `akm wiki ingest <name>` for the workflow).
  */
 export function stashRaw(input) {
-    const wikiDir = resolveWikiDir(input.stashDir, input.wikiName);
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${input.wikiName}. Run \`akm wiki create ${input.wikiName}\` first.`);
-    }
+    const wikiDir = resolveWikiSource(input.stashDir, input.wikiName).path;
     const rawDir = path.join(wikiDir, RAW_SUBDIR);
     fs.mkdirSync(rawDir, { recursive: true });
     const baseSlug = slugifyForWiki(input.preferredName ?? deriveQueryFromSource(input.content) ?? "source");
@@ -598,10 +665,7 @@ export function stashRaw(input) {
  *   - `stale-index`: `index.md` mtime is older than the newest page mtime
  */
 export function lintWiki(stashDir, name) {
-    const wikiDir = resolveWikiDir(stashDir, name);
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}.`);
-    }
+    const wikiDir = resolveWikiSource(stashDir, name).path;
     const pages = listPages(stashDir, name);
     const { raws, pagesLastModifiedMs } = scanWikiFiles(wikiDir);
     const pageRefs = new Set(pages.map((p) => p.ref));
@@ -822,10 +886,7 @@ export function regenerateAllWikiIndexes(stashDir) {
  * a verb here and in the printer stays colocated.
  */
 export function buildIngestWorkflow(stashDir, name) {
-    const wikiDir = resolveWikiDir(stashDir, name);
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}. Run \`akm wiki create ${name}\` first.`);
-    }
+    const wikiDir = resolveWikiSource(stashDir, name).path;
     const schemaPath = path.join(wikiDir, SCHEMA_MD);
     const workflow = `# Ingest workflow for wiki:${name}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.5.0-rc2",
+  "version": "0.5.0-rc4",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [