akm-cli 0.4.1 → 0.5.0-rc1

package/dist/matchers.js

@@ -1,7 +1,7 @@
 /**
  * Built-in asset matchers for the akm file classification system.
  *
- * Four matchers are registered at module load time, each at a different
+ * Five matchers are registered at module load time, each at a different
  * specificity level. Extension and content determine type; directories are
  * optional specificity boosts, not requirements.
  *
@@ -15,6 +15,8 @@
  *   and body content for agent/command signals; falls back to "knowledge"
  *   at specificity 5 when no signals are found. Command signals (`agent`
  *   frontmatter, `$ARGUMENTS`/`$1`-`$3` placeholders) return 18.
+ * - `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 { registerMatcher } from "./file-context";
@@ -32,7 +34,9 @@ import { registerMatcher } from "./file-context";
 export function extensionMatcher(ctx) {
     // SKILL.md is a skill regardless of location — high specificity beats
     // smartMdMatcher's knowledge fallback and all directory-based matchers.
-    if (ctx.fileName === "SKILL.md") {
+    // Exception: files under wikis/<name>/… are always wiki pages; the wiki
+    // directory is an authoritative signal that outranks the filename.
+    if (ctx.fileName === "SKILL.md" && !ctx.ancestorDirs.includes("wikis")) {
         return { type: "skill", specificity: 25, renderer: "skill-md" };
     }
     // Known script extensions (excluding .md, handled by smartMdMatcher)
@@ -68,9 +72,15 @@ export function directoryMatcher(ctx) {
         if (dir === "knowledge" && ext === ".md") {
             return { type: "knowledge", specificity: 10, renderer: "knowledge-md" };
         }
+        if (dir === "workflows" && ext === ".md") {
+            return { type: "workflow", specificity: 10, renderer: "workflow-md" };
+        }
         if (dir === "memories" && ext === ".md") {
             return { type: "memory", specificity: 10, renderer: "memory-md" };
         }
+        if (dir === "vaults" && (ctx.fileName === ".env" || ctx.fileName.endsWith(".env"))) {
+            return { type: "vault", specificity: 10, renderer: "vault-env" };
+        }
     }
     return null;
 }
@@ -98,9 +108,15 @@ export function parentDirHintMatcher(ctx) {
     if (parentDir === "knowledge" && ext === ".md") {
         return { type: "knowledge", specificity: 15, renderer: "knowledge-md" };
     }
+    if (parentDir === "workflows" && ext === ".md") {
+        return { type: "workflow", specificity: 15, renderer: "workflow-md" };
+    }
     if (parentDir === "memories" && ext === ".md") {
         return { type: "memory", specificity: 15, renderer: "memory-md" };
     }
+    if (parentDir === "vaults" && (fileName === ".env" || fileName.endsWith(".env"))) {
+        return { type: "vault", specificity: 15, renderer: "vault-env" };
+    }
     return null;
 }
 // ── smartMdMatcher (specificity: 20 / 18 / 8 / 5) ──────────────────────────
@@ -123,6 +139,14 @@ const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
 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) {
+        return { type: "workflow", specificity: 19, renderer: "workflow-md" };
+    }
     const fm = ctx.frontmatter();
     if (fm) {
         // Agent-exclusive indicators: toolPolicy or tools
@@ -138,7 +162,6 @@ export function smartMdMatcher(ctx) {
     }
     // Command signal: body contains $ARGUMENTS or $1/$2/$3 placeholders.
     // These are definitively command template patterns (OpenCode convention).
-    const body = ctx.content();
     if (COMMAND_PLACEHOLDER_RE.test(body)) {
         return { type: "command", specificity: 18, renderer: "command-md" };
     }
@@ -154,9 +177,38 @@ export function smartMdMatcher(ctx) {
     // Weak fallback: any .md file is assumed to be knowledge
     return { type: "knowledge", specificity: 5, renderer: "knowledge-md" };
 }
+// ── wikiMatcher (specificity: 20) ──────────────────────────────────────────
+/**
+ * Classify any `.md` file that lives under `wikis/<name>/…` as `wiki`.
+ *
+ * Registered AFTER `smartMdMatcher` so the registered-later-wins tiebreaker
+ * puts wiki ahead of agent at specificity 20. That means a wiki page with
+ * agent-style frontmatter (e.g. `tools:`) still classifies as a wiki page,
+ * not an agent. That's intentional — the directory is the authoritative
+ * signal: files under `wikis/` are wiki content.
+ *
+ * Requires at least one path segment after `wikis/` (the wiki name) — a
+ * stray `.md` at the bare `wikis/` root is not a wiki page.
+ */
+export function wikiMatcher(ctx) {
+    if (ctx.ext !== ".md")
+        return null;
+    const idx = ctx.ancestorDirs.indexOf("wikis");
+    if (idx < 0)
+        return null;
+    if (idx + 1 >= ctx.ancestorDirs.length)
+        return null;
+    return { type: "wiki", specificity: 20, renderer: "wiki-md" };
+}
 // ── Registration ────────────────────────────────────────────────────────────
 /** All built-in matchers in registration order (later wins ties). */
-const builtinMatchers = [extensionMatcher, directoryMatcher, parentDirHintMatcher, smartMdMatcher];
+const builtinMatchers = [
+    extensionMatcher,
+    directoryMatcher,
+    parentDirHintMatcher,
+    smartMdMatcher,
+    wikiMatcher,
+];
 /**
  * Register all built-in matchers with the file-context registry.
  * Called once from the CLI entry point (or ensureBuiltinsRegistered).

package/dist/metadata.js

@@ -133,6 +133,30 @@ export function validateStashEntry(entry) {
         result.cwd = e.cwd.trim();
     if (typeof e.fileSize === "number" && Number.isFinite(e.fileSize) && e.fileSize >= 0)
         result.fileSize = e.fileSize;
+    if (e.wikiRole === "schema" ||
+        e.wikiRole === "index" ||
+        e.wikiRole === "log" ||
+        e.wikiRole === "raw" ||
+        e.wikiRole === "page") {
+        result.wikiRole = e.wikiRole;
+    }
+    if (typeof e.pageKind === "string" && e.pageKind.trim().length > 0) {
+        result.pageKind = e.pageKind.trim();
+    }
+    if (Array.isArray(e.xrefs)) {
+        const filtered = e.xrefs
+            .filter((x) => typeof x === "string" && x.trim().length > 0)
+            .map((x) => x.trim());
+        if (filtered.length > 0)
+            result.xrefs = filtered;
+    }
+    if (Array.isArray(e.sources)) {
+        const filtered = e.sources
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .map((s) => s.trim());
+        if (filtered.length > 0)
+            result.sources = filtered;
+    }
     if (Array.isArray(e.parameters)) {
         const validated = e.parameters
             .filter((p) => {
@@ -196,6 +220,36 @@ export function extractCommandParameters(template) {
     }
     return params.length > 0 ? params : undefined;
 }
+/**
+ * Extract wiki frontmatter fields (wikiRole, pageKind, xrefs, sources) from a parsed
+ * frontmatter block and apply them to the entry. Tolerates missing or malformed values.
+ */
+export function applyWikiFrontmatter(entry, fmData) {
+    const role = fmData.wikiRole;
+    if (role === "schema" || role === "index" || role === "log" || role === "raw" || role === "page") {
+        entry.wikiRole = role;
+    }
+    const pageKind = fmData.pageKind;
+    if (typeof pageKind === "string" && pageKind.trim().length > 0) {
+        entry.pageKind = pageKind.trim();
+    }
+    const xrefs = fmData.xrefs;
+    if (Array.isArray(xrefs)) {
+        const filtered = xrefs
+            .filter((x) => typeof x === "string" && x.trim().length > 0)
+            .map((x) => x.trim());
+        if (filtered.length > 0)
+            entry.xrefs = filtered;
+    }
+    const sources = fmData.sources;
+    if (Array.isArray(sources)) {
+        const filtered = sources
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .map((s) => s.trim());
+        if (filtered.length > 0)
+            entry.sources = filtered;
+    }
+}
 /**
  * Extract `@param` JSDoc tags from a script file's leading comment block.
  *
@@ -316,6 +370,8 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
             const fmParams = extractFrontmatterParameters(parsed.data);
             if (fmParams)
                 entry.parameters = fmParams;
+            // Pass wiki-pattern frontmatter through onto the entry
+            applyWikiFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -324,8 +380,11 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
                 }
             }
         }
-        // Extract @param from script files
-        if (ext !== ".md") {
+        // Extract @param from script files.
+        // Vault files (.env) are deliberately excluded — their contents are secrets
+        // and must never be parsed for @param or any other metadata that could
+        // embed a value into the entry.
+        if (ext !== ".md" && assetType !== "vault") {
             const scriptParams = extractScriptParameters(file);
             if (scriptParams)
                 entry.parameters = scriptParams;
@@ -418,6 +477,8 @@ export async function generateMetadataFlat(stashRoot, files) {
             const fmParams = extractFrontmatterParameters(parsed.data);
             if (fmParams)
                 entry.parameters = fmParams;
+            // Pass wiki-pattern frontmatter through onto the entry
+            applyWikiFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -426,8 +487,11 @@ export async function generateMetadataFlat(stashRoot, files) {
                 }
             }
         }
-        // Extract @param from script files
-        if (ext !== ".md") {
+        // Extract @param from script files.
+        // Vault files (.env) are deliberately excluded — their contents are secrets
+        // and must never be parsed for @param or any other metadata that could
+        // embed a value into the entry.
+        if (ext !== ".md" && assetType !== "vault") {
             const scriptParams = extractScriptParameters(file, ctx.content());
             if (scriptParams)
                 entry.parameters = scriptParams;

package/dist/paths.js

@@ -68,6 +68,9 @@ export function getCacheDir() {
 export function getDbPath() {
     return path.join(getCacheDir(), "index.db");
 }
+export function getWorkflowDbPath() {
+    return path.join(getCacheDir(), "workflow.db");
+}
 export function getSemanticStatusPath() {
     return path.join(getCacheDir(), "semantic-status.json");
 }

package/dist/registry-install.js

@@ -20,6 +20,9 @@ export async function installRegistryRef(ref, options) {
     if (parsed.source === "git") {
         return installGitRegistryRef(parsed, config, options);
     }
+    if (parsed.source === "github") {
+        return installGithubRegistryRef(parsed, config, options);
+    }
     const resolved = await resolveRegistryArtifact(parsed);
     const registryLabels = deriveRegistryLabels({
         source: resolved.source,
@@ -38,7 +41,7 @@ export async function installRegistryRef(ref, options) {
             const cachedStashRoot = detectStashRoot(extractedDir);
             if (cachedStashRoot) {
                 const integrity = fs.existsSync(archivePath) ? await computeFileHash(archivePath) : undefined;
-                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
                 return {
                     id: resolved.id,
                     source: resolved.source,
@@ -51,6 +54,7 @@ export async function installRegistryRef(ref, options) {
                     extractedDir,
                     stashRoot: cachedStashRoot,
                     integrity,
+                    writable: options?.writable,
                     audit,
                 };
             }
@@ -70,7 +74,7 @@ export async function installRegistryRef(ref, options) {
         verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
         integrity = await computeFileHash(archivePath);
         extractTarGzSecure(archivePath, extractedDir);
-        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
         provisionalKitRoot = detectStashRoot(extractedDir);
         installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
@@ -98,9 +102,24 @@ export async function installRegistryRef(ref, options) {
         extractedDir,
         stashRoot,
         integrity,
+        writable: options?.writable,
         audit,
     };
 }
+async function installGithubRegistryRef(parsed, config, options) {
+    const gitParsed = {
+        source: "git",
+        ref: parsed.ref,
+        id: parsed.id,
+        url: `https://github.com/${parsed.owner}/${parsed.repo}.git`,
+        requestedRef: parsed.requestedRef,
+    };
+    const installed = await installGitRegistryRef(gitParsed, config, options);
+    return {
+        ...installed,
+        source: "github",
+    };
+}
 async function installLocalRegistryRef(parsed, config, options) {
     const resolved = await resolveRegistryArtifact(parsed);
     const installedAt = (options?.now ?? new Date()).toISOString();
@@ -109,7 +128,7 @@ async function installLocalRegistryRef(parsed, config, options) {
         ref: resolved.ref,
         artifactUrl: resolved.artifactUrl,
     });
-    const audit = runInstallAuditOrThrow(parsed.sourcePath, resolved.source, resolved.ref, registryLabels, config);
+    const audit = runInstallAuditOrThrow(parsed.sourcePath, resolved.source, resolved.ref, registryLabels, config, options);
     // For local directories, detect the stash root within the source path.
     // If no nested stash is found, the source path itself is used.
     const stashRoot = detectStashRoot(parsed.sourcePath);
@@ -124,6 +143,7 @@ async function installLocalRegistryRef(parsed, config, options) {
         cacheDir: parsed.sourcePath,
         extractedDir: parsed.sourcePath,
         stashRoot,
+        writable: options?.writable,
         audit,
     };
 }
@@ -148,7 +168,7 @@ async function installGitRegistryRef(parsed, config, options) {
             const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
             const stashRoot = detectStashRoot(installRoot);
             if (stashRoot) {
-                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+                const audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
                 return {
                     id: resolved.id,
                     source: resolved.source,
@@ -160,6 +180,7 @@ async function installGitRegistryRef(parsed, config, options) {
                     cacheDir,
                     extractedDir,
                     stashRoot,
+                    writable: options?.writable,
                     audit,
                 };
             }
@@ -193,7 +214,7 @@ async function installGitRegistryRef(parsed, config, options) {
         copyDirectoryContents(cloneDir, extractedDir);
         // Clean up the clone dir
         fs.rmSync(cloneDir, { recursive: true, force: true });
-        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config);
+        audit = runInstallAuditOrThrow(extractedDir, resolved.source, resolved.ref, registryLabels, config, options);
         provisionalKitRoot = detectStashRoot(extractedDir);
         installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
@@ -220,6 +241,7 @@ async function installGitRegistryRef(parsed, config, options) {
         cacheDir,
         extractedDir,
         stashRoot,
+        writable: options?.writable,
         audit,
     };
 }
@@ -494,8 +516,15 @@ async function computeFileHash(filePath) {
     const hash = createHash("sha256").update(data).digest("hex");
     return `sha256:${hash}`;
 }
-function runInstallAuditOrThrow(rootDir, source, ref, registryLabels, config) {
-    const audit = auditInstallCandidate({ rootDir, source, ref, registryLabels, config });
+function runInstallAuditOrThrow(rootDir, source, ref, registryLabels, config, options) {
+    const audit = auditInstallCandidate({
+        rootDir,
+        source,
+        ref,
+        registryLabels,
+        config,
+        trustThisInstall: options?.trustThisInstall,
+    });
     if (audit.blocked) {
         throw new Error(formatInstallAuditFailure(ref, audit));
     }

package/dist/registry-resolve.js

@@ -273,6 +273,20 @@ async function resolveNpmArtifact(parsed) {
     };
 }
 async function resolveGithubArtifact(parsed) {
+    const gitUrl = `https://github.com/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}.git`;
+    // Prefer git-backed installs so private GitHub repos work with the user's
+    // normal git credential helper rather than requiring API-specific auth.
+    const gitResolvedRevision = resolveGitRevisionFromRemote(gitUrl, parsed.requestedRef);
+    if (gitResolvedRevision) {
+        return {
+            id: parsed.id,
+            source: parsed.source,
+            ref: parsed.ref,
+            artifactUrl: gitUrl,
+            resolvedVersion: parsed.requestedRef,
+            resolvedRevision: gitResolvedRevision,
+        };
+    }
     const headers = githubHeaders();
     if (parsed.requestedRef) {
         const commit = await tryFetchJson(`${GITHUB_API_BASE}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/commits/${encodeURIComponent(parsed.requestedRef)}`, headers);
@@ -315,6 +329,17 @@ async function resolveGithubArtifact(parsed) {
         resolvedRevision: asString(commit?.sha) ?? defaultBranch,
     };
 }
+function resolveGitRevisionFromRemote(url, requestedRef) {
+    validateGitUrl(url);
+    const ref = requestedRef ?? "HEAD";
+    if (requestedRef)
+        validateGitRef(requestedRef);
+    const result = spawnSync("git", ["ls-remote", url, ref], { encoding: "utf8", timeout: 30_000 });
+    if (result.status !== 0)
+        return undefined;
+    const firstLine = result.stdout.trim().split(/\r?\n/)[0];
+    return firstLine?.split(/\s/)[0] || undefined;
+}
 async function resolveGitArtifact(parsed) {
     validateGitUrl(parsed.url);
     const ref = parsed.requestedRef ?? "HEAD";

package/dist/renderers.js

@@ -9,10 +9,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { hasErrnoCode } from "./common";
+import { UsageError } from "./errors";
 import { registerRenderer } from "./file-context";
 import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
 import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc } from "./markdown";
 import { extractDescriptionFromComments, loadStashFile } from "./metadata";
+import { makeAssetRef } from "./stash-ref";
+import { listKeys as listVaultKeys } from "./vault";
+import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
 // ── Interpreter auto-detection map ───────────────────────────────────────────
 const INTERPRETER_MAP = {
     ".sh": "bash",
@@ -149,6 +153,12 @@ function deriveName(ctx) {
     const ext = path.extname(ctx.relPath);
     return ext ? ctx.relPath.slice(0, -ext.length) : ctx.relPath;
 }
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function buildWorkflowAction(ref) {
+    return `Resume the active run or start a new run with \`akm workflow next ${shellQuote(ref)}\`.`;
+}
 /**
  * Load the matching StashEntry for a file path from the directory's .stash.json.
  */
@@ -309,6 +319,85 @@ const knowledgeMdRenderer = {
         }
     },
 };
+// ── 4b. wiki-md ──────────────────────────────────────────────────────────────
+const WIKI_PAGE_ACTION = "Wiki page — read below. Use 'toc' to scan, 'section <heading>' for depth.";
+const wikiMdRenderer = {
+    name: "wiki-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const v = ctx.matchResult.meta?.view ?? { mode: "full" };
+        const content = ctx.content();
+        switch (v.mode) {
+            case "toc": {
+                const toc = parseMarkdownToc(content);
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: formatToc(toc),
+                };
+            }
+            case "frontmatter": {
+                const fm = extractFrontmatterOnly(content);
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: fm ?? "(no frontmatter)",
+                };
+            }
+            case "section": {
+                const section = extractSection(content, v.heading);
+                if (!section) {
+                    return {
+                        type: "wiki",
+                        name,
+                        path: ctx.absPath,
+                        action: WIKI_PAGE_ACTION,
+                        content: `Section "${v.heading}" not found in ${name}. Try \`akm show wiki:${name} toc\` to discover available headings.`,
+                    };
+                }
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: section.content,
+                };
+            }
+            case "lines": {
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content: extractLineRange(content, v.start, v.end),
+                };
+            }
+            default: {
+                return {
+                    type: "wiki",
+                    name,
+                    path: ctx.absPath,
+                    action: WIKI_PAGE_ACTION,
+                    content,
+                };
+            }
+        }
+    },
+    extractMetadata(entry, ctx) {
+        try {
+            const toc = parseMarkdownToc(ctx.content());
+            if (toc.headings.length > 0)
+                entry.toc = toc.headings;
+        }
+        catch {
+            // Non-fatal: skip TOC if file can't be read
+        }
+    },
+};
 // ── 5. memory-md ─────────────────────────────────────────────────────────────
 const memoryMdRenderer = {
     name: "memory-md",
@@ -323,7 +412,58 @@ const memoryMdRenderer = {
         };
     },
 };
-// ── 6. script-source ─────────────────────────────────────────────────────────
+// ── 6. workflow-md ───────────────────────────────────────────────────────────
+const workflowMdRenderer = {
+    name: "workflow-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const workflow = parseWorkflowForRendering(ctx.content());
+        const ref = makeAssetRef("workflow", name, ctx.origin);
+        return {
+            type: "workflow",
+            name,
+            path: ctx.absPath,
+            action: buildWorkflowAction(ref),
+            description: workflow.description,
+            workflowTitle: workflow.title,
+            parameters: workflow.parameters?.map((parameter) => parameter.name),
+            workflowParameters: workflow.parameters,
+            steps: workflow.steps,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        const workflow = parseWorkflowForRendering(ctx.content());
+        const hints = new Set(entry.searchHints ?? []);
+        hints.add(workflow.title);
+        for (const step of workflow.steps) {
+            hints.add(step.title);
+            hints.add(step.id);
+            hints.add(step.instructions);
+            for (const criterion of step.completionCriteria ?? []) {
+                hints.add(criterion);
+            }
+        }
+        entry.searchHints = Array.from(hints).filter(Boolean);
+        if (workflow.parameters?.length) {
+            entry.parameters = workflow.parameters.map((parameter) => ({
+                name: parameter.name,
+                ...(parameter.description ? { description: parameter.description } : {}),
+            }));
+        }
+    },
+};
+function parseWorkflowForRendering(content) {
+    try {
+        return parseWorkflowMarkdown(content);
+    }
+    catch (error) {
+        if (error instanceof WorkflowValidationError) {
+            throw new UsageError(error.message);
+        }
+        throw error;
+    }
+}
+// ── 7. script-source ─────────────────────────────────────────────────────────
 const scriptSourceRenderer = {
     name: "script-source",
     buildShowResponse(ctx) {
@@ -379,6 +519,43 @@ const scriptSourceRenderer = {
         }
     },
 };
+// ── 8. vault-env ─────────────────────────────────────────────────────────────
+/**
+ * Vault renderer. Returns ONLY key names and start-of-line comments — never
+ * values. Deliberately omits content/template/prompt so vault values cannot
+ * leak through `akm show`.
+ */
+const vaultEnvRenderer = {
+    name: "vault-env",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const { keys, comments } = listVaultKeys(ctx.absPath);
+        return {
+            type: "vault",
+            name,
+            path: ctx.absPath,
+            action: 'Vault — keys + comments only. Use `eval "$(akm vault load <ref>)"` to load values into the current shell. Values stay on disk and are never written to akm\'s stdout.',
+            description: comments.length > 0 ? comments.join("\n") : undefined,
+            keys,
+            comments,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        // Re-derive from the file directly to guarantee no value ever transits
+        // through any other code path. Caller already short-circuits in
+        // generateMetadata{,Flat}, but this is defense in depth.
+        const { keys, comments } = listVaultKeys(ctx.absPath);
+        if (comments.length > 0 && !entry.description) {
+            entry.description = comments.join(" ").slice(0, 500);
+            entry.source = "comments";
+            entry.confidence = 0.7;
+        }
+        if (keys.length > 0) {
+            entry.searchHints = keys;
+        }
+        entry.tags = Array.from(new Set([...(entry.tags ?? []), "vault", "secrets"]));
+    },
+};
 // ── Registration ─────────────────────────────────────────────────────────────
 /** All built-in renderers. */
 const builtinRenderers = [
@@ -386,8 +563,11 @@ const builtinRenderers = [
     commandMdRenderer,
     agentMdRenderer,
     knowledgeMdRenderer,
+    wikiMdRenderer,
     memoryMdRenderer,
+    workflowMdRenderer,
     scriptSourceRenderer,
+    vaultEnvRenderer,
 ];
 /**
  * Register all built-in renderers with the file-context registry.
@@ -399,4 +579,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, vaultEnvRenderer, wikiMdRenderer, workflowMdRenderer, };

package/dist/search-fields.js

@@ -41,6 +41,10 @@ export function buildSearchFields(entry) {
         if (entry.intent.output)
             hintParts.push(entry.intent.output);
     }
+    if (entry.xrefs)
+        hintParts.push(entry.xrefs.join(" "));
+    if (entry.pageKind)
+        hintParts.push(entry.pageKind);
     const hints = hintParts.join(" ").toLowerCase();
     const contentParts = [];
     if (entry.toc) {