akm-cli 0.4.1 → 0.5.0-rc2

package/dist/cli.js

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
-import { resolveAssetPathFromName } from "./asset-spec";
+import { deriveCanonicalAssetName, resolveAssetPathFromName } from "./asset-spec";
 import { isWithin, resolveStashDir } from "./common";
 import { generateBashCompletions, installBashCompletions } from "./completions";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, saveConfig } from "./config";
@@ -14,18 +14,24 @@ import { assembleInfo } from "./info";
 import { akmInit } from "./init";
 import { formatInstallAuditSummary } from "./install-audit";
 import { akmListSources, akmRemove, akmUpdate } from "./installed-kits";
+import { renderMigrationHelp } from "./migration-help";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
 import { buildRegistryIndex, writeRegistryIndex } from "./registry-build-index";
 import { searchRegistry } from "./registry-search";
 import { checkForUpdate, performUpgrade } from "./self-update";
 import { akmAdd } from "./stash-add";
 import { akmClone } from "./stash-clone";
+import { saveGitStash } from "./stash-providers/git";
+import { parseAssetRef } from "./stash-ref";
 import { akmSearch, parseSearchSource } from "./stash-search";
 import { akmShowUnified } from "./stash-show";
 import { addStash } from "./stash-source-manage";
 import { insertUsageEvent } from "./usage-events";
 import { pkgVersion } from "./version";
 import { setQuiet, warn } from "./warn";
+import { createWorkflowAsset, getWorkflowTemplate } from "./workflow-authoring";
+import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "./workflow-cli";
+import { completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "./workflow-runs";
 const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl"];
 const DETAIL_LEVELS = ["brief", "normal", "full", "summary"];
 const NORMAL_DESCRIPTION_LIMIT = 250;
@@ -235,10 +241,27 @@ function shapeShowOutput(result, detail, forAgent = false) {
             "modelHint",
             "agent",
             "parameters",
+            "workflowTitle",
+            "workflowParameters",
+            "steps",
+            "keys",
+            "comments",
         ]);
     }
     if (detail === "summary") {
-        return pickFields(result, ["type", "name", "description", "tags", "parameters", "action", "run", "origin"]);
+        return pickFields(result, [
+            "type",
+            "name",
+            "description",
+            "tags",
+            "parameters",
+            "workflowTitle",
+            "action",
+            "run",
+            "origin",
+            "keys",
+            "comments",
+        ]);
     }
     const base = pickFields(result, [
         "type",
@@ -254,9 +277,14 @@ function shapeShowOutput(result, detail, forAgent = false) {
         "modelHint",
         "agent",
         "parameters",
+        "workflowTitle",
+        "workflowParameters",
+        "steps",
         "run",
         "setup",
         "cwd",
+        "keys",
+        "comments",
     ]);
     if (detail !== "full") {
         return base;
@@ -309,10 +337,22 @@ function formatPlain(command, result, detail) {
                 lines.push(`# ${String(r.action)}`);
             if (r.description)
                 lines.push(`description: ${String(r.description)}`);
+            if (r.workflowTitle)
+                lines.push(`workflowTitle: ${String(r.workflowTitle)}`);
             if (r.agent)
                 lines.push(`agent: ${String(r.agent)}`);
             if (Array.isArray(r.parameters) && r.parameters.length > 0)
                 lines.push(`parameters: ${r.parameters.join(", ")}`);
+            if (Array.isArray(r.workflowParameters) && r.workflowParameters.length > 0) {
+                lines.push("workflowParameters:");
+                for (const parameter of r.workflowParameters) {
+                    const name = typeof parameter.name === "string" ? parameter.name : "unknown";
+                    const description = typeof parameter.description === "string" && parameter.description.trim()
+                        ? `: ${parameter.description}`
+                        : "";
+                    lines.push(`  - ${name}${description}`);
+                }
+            }
             if (r.modelHint != null)
                 lines.push(`modelHint: ${String(r.modelHint)}`);
             if (r.toolPolicy != null)
@@ -334,6 +374,25 @@ function formatPlain(command, result, detail) {
                     lines.push(`schemaVersion: ${String(r.schemaVersion)}`);
             }
             const payloads = [r.content, r.template, r.prompt].filter((value) => value != null).map(String);
+            if (Array.isArray(r.steps) && r.steps.length > 0) {
+                if (lines.length > 0)
+                    lines.push("");
+                lines.push("steps:");
+                for (const [index, step] of r.steps.entries()) {
+                    const title = typeof step.title === "string" ? step.title : "Untitled step";
+                    const id = typeof step.id === "string" ? step.id : "unknown";
+                    lines.push(`  ${index + 1}. ${title} [${id}]`);
+                    if (typeof step.instructions === "string" && step.instructions.trim()) {
+                        lines.push(`     instructions: ${step.instructions.replace(/\n+/g, " ").trim()}`);
+                    }
+                    if (Array.isArray(step.completionCriteria) && step.completionCriteria.length > 0) {
+                        lines.push("     completion:");
+                        for (const criterion of step.completionCriteria) {
+                            lines.push(`       - ${String(criterion)}`);
+                        }
+                    }
+                }
+            }
             if (payloads.length > 0) {
                 if (lines.length > 0)
                     lines.push("");
@@ -347,6 +406,47 @@ function formatPlain(command, result, detail) {
         case "curate": {
             return formatCuratePlain(r, detail);
         }
+        case "wiki-list": {
+            return formatWikiListPlain(r);
+        }
+        case "wiki-show": {
+            return formatWikiShowPlain(r);
+        }
+        case "wiki-create": {
+            return formatWikiCreatePlain(r);
+        }
+        case "wiki-remove": {
+            return formatWikiRemovePlain(r);
+        }
+        case "wiki-pages": {
+            return formatWikiPagesPlain(r);
+        }
+        case "wiki-stash": {
+            return formatWikiStashPlain(r);
+        }
+        case "wiki-lint": {
+            return formatWikiLintPlain(r);
+        }
+        case "wiki-ingest": {
+            return formatWikiIngestPlain(r);
+        }
+        case "workflow-start":
+        case "workflow-status":
+        case "workflow-complete": {
+            return formatWorkflowStatusPlain(r);
+        }
+        case "workflow-next": {
+            return formatWorkflowNextPlain(r);
+        }
+        case "workflow-list": {
+            return formatWorkflowListPlain(r);
+        }
+        case "workflow-create": {
+            if (r.ref && r.path) {
+                return `Created ${String(r.ref)} at ${String(r.path)}`;
+            }
+            return null;
+        }
         case "list": {
             const sources = Array.isArray(r.sources) ? r.sources : [];
             if (sources.length === 0)
@@ -357,7 +457,13 @@ function formatPlain(command, result, detail) {
                 const name = typeof src.name === "string" ? src.name : "unnamed";
                 const ver = typeof src.version === "string" ? ` v${src.version}` : "";
                 const prov = typeof src.provider === "string" ? ` (${src.provider})` : "";
-                lines.push(`[${kind}] ${name}${ver}${prov}`);
+                const flags = [];
+                if (src.updatable === true)
+                    flags.push("updatable");
+                if (src.writable === true)
+                    flags.push("writable");
+                const flagText = flags.length > 0 ? ` [${flags.join(", ")}]` : "";
+                lines.push(`[${kind}] ${name}${ver}${prov}${flagText}`);
             }
             return lines.join("\n");
         }
@@ -419,6 +525,69 @@ function formatPlain(command, result, detail) {
             return null; // fall through to YAML
     }
 }
+function formatWorkflowListPlain(result) {
+    const runs = Array.isArray(result.runs) ? result.runs : [];
+    if (runs.length === 0)
+        return "No workflow runs found.";
+    return runs
+        .map((run) => {
+        const id = typeof run.id === "string" ? run.id : "unknown";
+        const ref = typeof run.workflowRef === "string" ? run.workflowRef : "workflow:unknown";
+        const status = typeof run.status === "string" ? run.status : "unknown";
+        const currentStep = typeof run.currentStepId === "string" ? ` (current: ${run.currentStepId})` : "";
+        return `${id} ${ref} [${status}]${currentStep}`;
+    })
+        .join("\n");
+}
+function formatWorkflowStatusPlain(result) {
+    const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
+    const workflow = typeof result.workflow === "object" && result.workflow !== null
+        ? result.workflow
+        : undefined;
+    if (!run || !workflow)
+        return null;
+    const lines = [
+        `workflow: ${String(workflow.ref ?? "workflow:unknown")}`,
+        `run: ${String(run.id ?? "unknown")}`,
+        `title: ${String(run.workflowTitle ?? workflow.title ?? "Workflow")}`,
+        `status: ${String(run.status ?? "unknown")}`,
+    ];
+    if (run.currentStepId)
+        lines.push(`currentStep: ${String(run.currentStepId)}`);
+    const steps = Array.isArray(workflow.steps) ? workflow.steps : [];
+    if (steps.length > 0) {
+        lines.push("steps:");
+        for (const step of steps) {
+            const title = typeof step.title === "string" ? step.title : "Untitled step";
+            const id = typeof step.id === "string" ? step.id : "unknown";
+            const status = typeof step.status === "string" ? step.status : "unknown";
+            lines.push(`  - ${title} [${id}] (${status})`);
+            if (typeof step.notes === "string" && step.notes.trim()) {
+                lines.push(`    notes: ${step.notes}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+function formatWorkflowNextPlain(result) {
+    const base = formatWorkflowStatusPlain(result);
+    const step = typeof result.step === "object" && result.step !== null ? result.step : undefined;
+    if (!step)
+        return base;
+    const lines = base ? [base, "", "next:"] : ["next:"];
+    lines.push(`  ${String(step.title ?? "Untitled step")} [${String(step.id ?? "unknown")}]`);
+    if (typeof step.instructions === "string" && step.instructions.trim()) {
+        lines.push(`  instructions: ${step.instructions.replace(/\n+/g, " ").trim()}`);
+    }
+    const completion = Array.isArray(step.completionCriteria) ? step.completionCriteria : [];
+    if (completion.length > 0) {
+        lines.push("  completion:");
+        for (const criterion of completion) {
+            lines.push(`    - ${String(criterion)}`);
+        }
+    }
+    return lines.join("\n");
+}
 function formatSearchPlain(r, detail) {
     const hits = r.hits ?? [];
     const registryHits = r.registryHits ?? [];
@@ -479,6 +648,98 @@ function formatSearchPlain(r, detail) {
     }
     return lines.join("\n").trimEnd();
 }
+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>`.";
+    const lines = ["NAME\tPAGES\tRAWS\tLAST-MODIFIED"];
+    for (const w of wikis) {
+        const name = typeof w.name === "string" ? w.name : "?";
+        const pages = typeof w.pages === "number" ? w.pages : 0;
+        const raws = typeof w.raws === "number" ? w.raws : 0;
+        const modified = typeof w.lastModified === "string" ? w.lastModified : "-";
+        lines.push(`${name}\t${pages}\t${raws}\t${modified}`);
+    }
+    return lines.join("\n");
+}
+function formatWikiShowPlain(r) {
+    const lines = [];
+    if (r.name)
+        lines.push(`# wiki: ${String(r.name)}`);
+    if (r.path)
+        lines.push(`path: ${String(r.path)}`);
+    if (r.description)
+        lines.push(`description: ${String(r.description)}`);
+    if (typeof r.pages === "number")
+        lines.push(`pages: ${r.pages}`);
+    if (typeof r.raws === "number")
+        lines.push(`raws: ${r.raws}`);
+    if (r.lastModified)
+        lines.push(`lastModified: ${String(r.lastModified)}`);
+    const recentLog = Array.isArray(r.recentLog) ? r.recentLog : [];
+    if (recentLog.length > 0) {
+        lines.push("", "recent log:");
+        for (const entry of recentLog) {
+            lines.push(entry);
+            lines.push("");
+        }
+    }
+    return lines.join("\n").trimEnd();
+}
+function formatWikiCreatePlain(r) {
+    const created = Array.isArray(r.created) ? r.created : [];
+    const skipped = Array.isArray(r.skipped) ? r.skipped : [];
+    const lines = [`Created wiki ${String(r.ref ?? r.name)} at ${String(r.path ?? "?")}`];
+    if (created.length > 0)
+        lines.push(`  created: ${created.length} file(s)`);
+    if (skipped.length > 0)
+        lines.push(`  skipped: ${skipped.length} existing file(s)`);
+    return lines.join("\n");
+}
+function formatWikiRemovePlain(r) {
+    const preserved = r.preservedRaw === true;
+    const removed = Array.isArray(r.removed) ? r.removed.length : 0;
+    const base = `Removed wiki ${String(r.name ?? "?")} (${removed} path(s))`;
+    return preserved ? `${base}; preserved ${String(r.rawPath ?? "raw/")}` : base;
+}
+function formatWikiPagesPlain(r) {
+    const pages = Array.isArray(r.pages) ? r.pages : [];
+    if (pages.length === 0)
+        return `No pages in wiki:${String(r.wiki ?? "?")}.`;
+    const lines = [];
+    for (const p of pages) {
+        const ref = String(p.ref ?? "?");
+        const kind = typeof p.pageKind === "string" ? ` [${p.pageKind}]` : "";
+        const desc = typeof p.description === "string" && p.description ? ` — ${p.description}` : "";
+        lines.push(`${ref}${kind}${desc}`);
+    }
+    return lines.join("\n");
+}
+function formatWikiStashPlain(r) {
+    const slug = String(r.slug ?? "?");
+    const pathValue = String(r.path ?? "?");
+    return `Stashed ${slug} → ${pathValue}`;
+}
+function formatWikiLintPlain(r) {
+    const findings = Array.isArray(r.findings) ? r.findings : [];
+    const pagesScanned = typeof r.pagesScanned === "number" ? r.pagesScanned : 0;
+    const rawsScanned = typeof r.rawsScanned === "number" ? r.rawsScanned : 0;
+    const header = `${findings.length} finding(s) in wiki:${String(r.wiki ?? "?")} (${pagesScanned} page(s), ${rawsScanned} raw(s))`;
+    if (findings.length === 0)
+        return `${header} — clean.`;
+    const lines = [header];
+    for (const f of findings) {
+        const kind = String(f.kind ?? "?");
+        const message = String(f.message ?? "");
+        lines.push(`- [${kind}] ${message}`);
+    }
+    return lines.join("\n");
+}
+function formatWikiIngestPlain(r) {
+    if (typeof r.workflow === "string")
+        return r.workflow;
+    return JSON.stringify(r, null, 2);
+}
 function formatCuratePlain(r, detail) {
     const query = typeof r.query === "string" ? r.query : "";
     const summary = typeof r.summary === "string" ? r.summary : "";
@@ -813,7 +1074,7 @@ const searchCommand = defineCommand({
         query: { type: "positional", description: "Search query (omit to list all assets)", required: false, default: "" },
         type: {
             type: "string",
-            description: "Asset type filter (e.g. skill, command, agent, knowledge, script, memory, or any).",
+            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, vault, wiki, or any). Use workflow to find step-by-step task assets.",
         },
         limit: { type: "string", description: "Maximum number of results" },
         source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
@@ -840,7 +1101,7 @@ const curateCommand = defineCommand({
         query: { type: "positional", description: "Task or prompt to curate assets for", required: true },
         type: {
             type: "string",
-            description: "Asset type filter (e.g. skill, command, agent, knowledge, script, memory, or any).",
+            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, vault, wiki, or any). Use workflow to curate step-by-step task assets.",
         },
         limit: { type: "string", description: "Maximum number of curated results", default: "4" },
         source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
@@ -881,6 +1142,20 @@ const addCommand = defineCommand({
         provider: { type: "string", description: "Provider type (e.g. openviking). Required for URL sources." },
         options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
         name: { type: "string", description: "Human-friendly name for the source" },
+        writable: {
+            type: "boolean",
+            description: "Mark a git stash as writable so changes can be pushed back",
+            default: false,
+        },
+        trust: {
+            type: "boolean",
+            description: "Bypass install-audit blocking for this add invocation only",
+            default: false,
+        },
+        type: {
+            type: "string",
+            description: "Override asset type for all files in this stash (currently supports: wiki)",
+        },
         "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)" },
     },
@@ -891,7 +1166,7 @@ const addCommand = defineCommand({
             if (ref === CONTEXT_HUB_ALIAS_REF) {
                 const result = addStash({
                     target: CONTEXT_HUB_ALIAS_URL,
-                    providerType: "context-hub",
+                    providerType: "git",
                     name: "context-hub",
                 });
                 output("stash-add", result);
@@ -922,6 +1197,7 @@ const addCommand = defineCommand({
                     name: args.name,
                     providerType: args.provider,
                     options: parsedOptions,
+                    writable: args.writable,
                 });
                 output("stash-add", result);
                 return;
@@ -937,7 +1213,10 @@ const addCommand = defineCommand({
             const result = await akmAdd({
                 ref,
                 name: args.name,
+                overrideType: args.type,
                 options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
+                trustThisInstall: args.trust,
+                writable: args.writable,
             });
             output("add", result);
         });
@@ -1175,6 +1454,91 @@ const configCommand = defineCommand({
         });
     },
 });
+const saveCommand = defineCommand({
+    meta: {
+        name: "save",
+        description: "Save changes in a git-backed stash: commits (and pushes when writable + remote is configured). No-op for non-git stashes.",
+    },
+    args: {
+        name: {
+            type: "positional",
+            description: "Name of the git stash to save (default: primary stash directory)",
+            required: false,
+        },
+        message: {
+            type: "string",
+            alias: "m",
+            description: "Commit message (default: timestamp)",
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            // Fix: citty can consume `--format json` (space-separated) as the
+            // positional `name` argument (e.g. `akm save --format json` parses
+            // name="json"). Detect the mis-parse by checking argv order — only
+            // treat the positional as consumed by --format when --format appears
+            // before any standalone occurrence of the same value in the save
+            // subcommand's argv slice. This preserves legitimate invocations
+            // like `akm save json --format json`.
+            const parsedFormat = parseFlagValue("--format");
+            const effectiveName = args.name !== undefined &&
+                parsedFormat !== undefined &&
+                args.name === parsedFormat &&
+                wasFormatValueConsumedAsName(args.name, parsedFormat)
+                ? undefined
+                : args.name;
+            let writable;
+            if (!effectiveName) {
+                // Primary stash — honour the root-level writable flag from config.
+                const cfg = loadConfig();
+                writable = cfg.writable === true ? true : undefined;
+            }
+            const result = saveGitStash(effectiveName, args.message, writable);
+            output("save", result);
+        });
+    },
+});
+/**
+ * Detect whether `--format <value>` was consumed by citty as the optional
+ * `name` positional of `akm save`. Returns true only when `--format` appears
+ * in the save subcommand's argv slice AND the candidate name does NOT
+ * appear as a standalone positional elsewhere (before or after the flag).
+ *
+ * This keeps `akm save json --format json` routing `json` as the stash name,
+ * while `akm save --format json` (no separate positional) is treated as a
+ * primary-stash save.
+ */
+function wasFormatValueConsumedAsName(name, formatValue) {
+    const argv = process.argv.slice(2);
+    const saveIndex = argv.indexOf("save");
+    const tokens = saveIndex >= 0 ? argv.slice(saveIndex + 1) : argv;
+    let formatIndex = -1;
+    let formatConsumesNextToken = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "--format") {
+            formatIndex = i;
+            formatConsumesNextToken = true;
+            break;
+        }
+        if (token === `--format=${formatValue}`) {
+            formatIndex = i;
+            break;
+        }
+    }
+    if (formatIndex === -1)
+        return false;
+    // If the name appears as a standalone token before --format, it's the
+    // real positional and --format did not consume it.
+    if (tokens.slice(0, formatIndex).includes(name))
+        return false;
+    // If --format has a space-separated value, skip past the value token
+    // when scanning after the flag; otherwise start right after the flag.
+    const firstTokenAfterFormat = formatIndex + (formatConsumesNextToken ? 2 : 1);
+    if (tokens.slice(firstTokenAfterFormat).includes(name))
+        return false;
+    return true;
+}
 const cloneCommand = defineCommand({
     meta: {
         name: "clone",
@@ -1449,6 +1813,206 @@ function writeMarkdownAsset(options) {
         stashDir,
     };
 }
+const workflowStartCommand = defineCommand({
+    meta: {
+        name: "start",
+        description: "Start a new workflow run",
+    },
+    args: {
+        ref: { type: "positional", description: "Workflow ref (workflow:<name>)", required: true },
+        params: { type: "string", description: "Workflow parameters as a JSON object" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = await startWorkflowRun(args.ref, parseWorkflowJsonObject(args.params, "--params"));
+            output("workflow-start", result);
+        });
+    },
+});
+const workflowNextCommand = defineCommand({
+    meta: {
+        name: "next",
+        description: "Show the next actionable workflow step, auto-starting a run when passed a workflow ref",
+    },
+    args: {
+        target: { type: "positional", description: "Workflow run id or workflow ref", required: true },
+        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const parsedParams = args.params ? parseWorkflowJsonObject(args.params, "--params") : undefined;
+            const result = await getNextWorkflowStep(args.target, parsedParams);
+            output("workflow-next", result);
+        });
+    },
+});
+const workflowCompleteCommand = defineCommand({
+    meta: {
+        name: "complete",
+        description: "Update a workflow step state and persist notes/evidence",
+    },
+    args: {
+        runId: { type: "positional", description: "Workflow run id", required: true },
+        step: { type: "string", description: "Workflow step id", required: true },
+        state: {
+            type: "string",
+            description: `Step state (default: completed). One of: ${WORKFLOW_STEP_STATES.join(", ")}.`,
+        },
+        notes: { type: "string", description: "Notes for the completed step" },
+        evidence: { type: "string", description: "Evidence JSON object for the step" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = completeWorkflowStep({
+                runId: args.runId,
+                stepId: args.step,
+                status: parseWorkflowStepState(args.state),
+                notes: args.notes,
+                evidence: args.evidence ? parseWorkflowJsonObject(args.evidence, "--evidence") : undefined,
+            });
+            output("workflow-complete", result);
+        });
+    },
+});
+const workflowStatusCommand = defineCommand({
+    meta: {
+        name: "status",
+        description: "Show full workflow run state for review or resume",
+    },
+    args: {
+        target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const target = args.target;
+            // Check if target looks like a workflow ref
+            const parsed = (() => {
+                try {
+                    return parseAssetRef(target);
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (parsed?.type === "workflow") {
+                const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
+                const { runs } = listWorkflowRuns({ workflowRef: ref });
+                if (runs.length === 0) {
+                    throw new NotFoundError(`No workflow runs found for ${ref}`);
+                }
+                const mostRecent = runs[0];
+                if (!mostRecent)
+                    throw new NotFoundError(`No workflow runs found for ${ref}`);
+                const result = getWorkflowStatus(mostRecent.id);
+                output("workflow-status", result);
+            }
+            else {
+                const result = getWorkflowStatus(target);
+                output("workflow-status", result);
+            }
+        });
+    },
+});
+const workflowListCommand = defineCommand({
+    meta: {
+        name: "list",
+        description: "List workflow runs",
+    },
+    args: {
+        ref: { type: "string", description: "Filter to one workflow ref" },
+        active: { type: "boolean", description: "Only show active runs", default: false },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = listWorkflowRuns({ workflowRef: args.ref, activeOnly: args.active });
+            output("workflow-list", result);
+        });
+    },
+});
+const workflowCreateCommand = defineCommand({
+    meta: {
+        name: "create",
+        description: "Create a workflow markdown document in the working stash",
+    },
+    args: {
+        name: { type: "positional", description: "Workflow name", required: true },
+        from: { type: "string", description: "Import and validate markdown from an existing file" },
+        force: {
+            type: "boolean",
+            description: "Overwrite an existing workflow (requires --from or --reset)",
+            default: false,
+        },
+        reset: {
+            type: "boolean",
+            description: "Explicitly replace an existing workflow with a fresh template (use with --force)",
+            default: false,
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const namePattern = /^[a-z0-9][a-z0-9._/-]*$/;
+            if (!namePattern.test(args.name)) {
+                throw new UsageError("Workflow name must start with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, dots, underscores, and slashes.");
+            }
+            if (args.force && !args.from && !args.reset) {
+                throw new UsageError("Refusing to overwrite with template: pass --from <file> to replace content, or --reset to explicitly replace with a fresh template.");
+            }
+            const result = createWorkflowAsset({
+                name: args.name,
+                from: args.from,
+                force: args.force,
+            });
+            output("workflow-create", { ok: true, ...result });
+        });
+    },
+});
+const workflowTemplateCommand = defineCommand({
+    meta: {
+        name: "template",
+        description: "Print a valid workflow markdown template",
+    },
+    run() {
+        process.stdout.write(getWorkflowTemplate());
+    },
+});
+const workflowResumeCommand = defineCommand({
+    meta: {
+        name: "resume",
+        description: "Resume a blocked or failed workflow run, flipping it back to active",
+    },
+    args: {
+        runId: { type: "positional", description: "Workflow run id", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = resumeWorkflowRun(args.runId);
+            output("workflow-run", result);
+        });
+    },
+});
+const workflowCommand = defineCommand({
+    meta: {
+        name: "workflow",
+        description: "Author, inspect, and execute step-by-step workflow assets",
+    },
+    subCommands: {
+        start: workflowStartCommand,
+        next: workflowNextCommand,
+        complete: workflowCompleteCommand,
+        status: workflowStatusCommand,
+        list: workflowListCommand,
+        create: workflowCreateCommand,
+        template: workflowTemplateCommand,
+        resume: workflowResumeCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            if (hasWorkflowSubcommand(args))
+                return;
+            output("workflow-list", listWorkflowRuns({ activeOnly: true }));
+        });
+    },
+});
 const rememberCommand = defineCommand({
     meta: {
         name: "remember",
@@ -1504,8 +2068,8 @@ const importKnowledgeCommand = defineCommand({
             default: false,
         },
     },
-    run({ args }) {
-        return runWithJsonErrors(() => {
+    async run({ args }) {
+        return runWithJsonErrors(async () => {
             const { content, preferredName } = readKnowledgeContent(args.source);
             const result = writeMarkdownAsset({
                 type: "knowledge",
@@ -1532,6 +2096,30 @@ const hintsCommand = defineCommand({
         process.stdout.write(loadHints(detail));
     },
 });
+const helpCommand = defineCommand({
+    meta: {
+        name: "help",
+        description: "Print focused help topics such as migration guidance for a release",
+    },
+    subCommands: {
+        migrate: defineCommand({
+            meta: {
+                name: "migrate",
+                description: "Print release notes and migration guidance for a version",
+            },
+            args: {
+                version: {
+                    type: "positional",
+                    description: "Version to review (for example 0.5.0, v0.5.0, or latest)",
+                    required: true,
+                },
+            },
+            run({ args }) {
+                process.stdout.write(renderMigrationHelp(args.version));
+            },
+        }),
+    },
+});
 const completionsCommand = defineCommand({
     meta: {
         name: "completions",
@@ -1641,6 +2229,429 @@ const disableCommand = defineCommand({
         });
     },
 });
+// ── vault ───────────────────────────────────────────────────────────────────
+//
+// `akm vault` manages secrets stored in `.env` files under the vaults/
+// asset directory. Values are NEVER written to stdout. `vault load` is
+// the only value-emitting path: it parses the vault with dotenv, writes
+// a safely-escaped shell script to a mode-0600 temp file, and emits only
+// `. <temp>; rm -f <temp>` on stdout for `eval`. The shell reads values
+// from the temp file — they never transit through akm's stdout.
+function resolveVaultPath(ref) {
+    const stashDir = resolveStashDir({ readOnly: true });
+    const parsed = parseAssetRef(ref.includes(":") ? ref : `vault:${ref}`);
+    if (parsed.type !== "vault") {
+        throw new UsageError(`Expected a vault ref (vault:<name>); got "${ref}".`);
+    }
+    const typeRoot = path.join(stashDir, "vaults");
+    const absPath = resolveAssetPathFromName("vault", typeRoot, parsed.name);
+    return { name: parsed.name, absPath };
+}
+/**
+ * Walk `vaults/` recursively and return one entry per `.env` file, using the
+ * vault asset spec's canonical-name logic so listing matches what the
+ * matcher/asset-spec actually resolves (e.g. `vaults/team/prod.env` →
+ * `vault:team/prod`, `vaults/team/.env` → `vault:team/default`).
+ */
+function listVaultsRecursive(listKeysFn) {
+    const stashDir = resolveStashDir({ readOnly: true });
+    const vaultsDir = path.join(stashDir, "vaults");
+    const result = [];
+    if (!fs.existsSync(vaultsDir))
+        return result;
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (entry.name !== ".env" && !entry.name.endsWith(".env"))
+                continue;
+            const canonical = deriveCanonicalAssetName("vault", vaultsDir, full);
+            if (!canonical)
+                continue;
+            const { keys } = listKeysFn(full);
+            result.push({ ref: `vault:${canonical}`, path: full, keyCount: keys.length });
+        }
+    };
+    walk(vaultsDir);
+    return result;
+}
+const vaultListCommand = defineCommand({
+    meta: { name: "list", description: "List vaults, or list keys (no values) inside one vault" },
+    args: {
+        ref: { type: "positional", description: "Optional vault ref (e.g. vault:prod or just prod)", required: false },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { listKeys } = await import("./vault.js");
+            if (args.ref) {
+                const { name, absPath } = resolveVaultPath(args.ref);
+                if (!fs.existsSync(absPath)) {
+                    throw new NotFoundError(`Vault not found: vault:${name}`);
+                }
+                const { keys, comments } = listKeys(absPath);
+                output("vault-list", { ref: `vault:${name}`, path: absPath, keys, comments });
+                return;
+            }
+            const vaults = listVaultsRecursive(listKeys);
+            output("vault-list", { vaults });
+        });
+    },
+});
+const vaultCreateCommand = defineCommand({
+    meta: { name: "create", description: "Create an empty vault file (no-op if it already exists)" },
+    args: {
+        name: { type: "positional", description: "Vault name (e.g. prod) — file becomes <name>.env", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { createVault } = await import("./vault.js");
+            const { name, absPath } = resolveVaultPath(args.name);
+            createVault(absPath);
+            output("vault-create", { ref: `vault:${name}`, path: absPath });
+        });
+    },
+});
+const vaultSetCommand = defineCommand({
+    meta: {
+        name: "set",
+        description: 'Set a key in a vault. Value is written to disk and never echoed back. Accepts KEY=VALUE combined form or separate KEY VALUE args. Optionally attach a comment with --comment "description".',
+    },
+    args: {
+        ref: { type: "positional", description: "Vault ref (e.g. vault:prod or just prod)", required: true },
+        key: { type: "positional", description: "Key name (e.g. DB_URL) or KEY=VALUE combined form", required: true },
+        value: {
+            type: "positional",
+            description: "Value to store (omit when using KEY=VALUE combined form)",
+            required: false,
+        },
+        comment: { type: "string", description: "Optional comment written above the key line", required: false },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { setKey } = await import("./vault.js");
+            const { name, absPath } = resolveVaultPath(args.ref);
+            let realKey;
+            let realValue;
+            if ((args.value === undefined || args.value === "") && args.key.includes("=")) {
+                const eqIdx = args.key.indexOf("=");
+                realKey = args.key.slice(0, eqIdx);
+                realValue = args.key.slice(eqIdx + 1);
+            }
+            else {
+                realKey = args.key;
+                realValue = args.value ?? "";
+            }
+            setKey(absPath, realKey, realValue, args.comment);
+            output("vault-set", { ref: `vault:${name}`, key: realKey, path: absPath });
+        });
+    },
+});
+const vaultUnsetCommand = defineCommand({
+    meta: { name: "unset", description: "Remove a key from a vault" },
+    args: {
+        ref: { type: "positional", description: "Vault ref", required: true },
+        key: { type: "positional", description: "Key name to remove", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { unsetKey } = await import("./vault.js");
+            const { name, absPath } = resolveVaultPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Vault not found: vault:${name}`);
+            }
+            const removed = unsetKey(absPath, args.key);
+            output("vault-unset", { ref: `vault:${name}`, key: args.key, removed, path: absPath });
+        });
+    },
+});
+const vaultLoadCommand = defineCommand({
+    meta: {
+        name: "load",
+        description: 'Emit a shell snippet that loads vault values into the current shell. Use: eval "$(akm vault load vault:<name>)". Values are parsed by dotenv, written to a mode-0600 temp file with safe single-quote escaping, then sourced and removed. No values appear on akm\'s stdout, and no shell expansion happens on raw vault content.',
+    },
+    args: {
+        ref: { type: "positional", description: "Vault ref", required: true },
+    },
+    async run({ args }) {
+        return runWithJsonErrors(async () => {
+            // This command deliberately bypasses output()/JSON shaping. Its stdout
+            // is a shell snippet intended for `eval`, not structured output.
+            const { name, absPath } = resolveVaultPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Vault not found: vault:${name}`);
+            }
+            const { buildShellExportScript } = await import("./vault.js");
+            const crypto = await import("node:crypto");
+            const os = await import("node:os");
+            // Parse via dotenv (no expansion, no code execution) and build a
+            // script of literal `export KEY='value'` lines with `'\''` escaping.
+            // Sourcing this is safe even if the raw vault file contained shell
+            // metacharacters like $, backticks, or $(...).
+            const script = buildShellExportScript(absPath);
+            // Write to a mode-0600 temp file the shell can source.
+            const tmpPath = path.join(os.tmpdir(), `akm-vault-${crypto.randomBytes(12).toString("hex")}.sh`);
+            fs.writeFileSync(tmpPath, script, { mode: 0o600, encoding: "utf8" });
+            try {
+                fs.chmodSync(tmpPath, 0o600);
+            }
+            catch {
+                /* best-effort on platforms without chmod */
+            }
+            const quotedTmp = `'${tmpPath.replace(/'/g, "'\\''")}'`;
+            // Emit: source the temp file, then remove it — values reach bash only
+            // via the temp file (mode 0600), never via akm's stdout.
+            process.stdout.write(`. ${quotedTmp}; rm -f ${quotedTmp}\n`);
+        });
+    },
+});
+const vaultShowCommand = defineCommand({
+    meta: { name: "show", description: "Show keys (no values) inside a vault — alias for `vault list <ref>`" },
+    args: {
+        ref: { type: "positional", description: "Vault ref (e.g. vault:prod or just prod)", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { listKeys } = await import("./vault.js");
+            const { name, absPath } = resolveVaultPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Vault not found: vault:${name}`);
+            }
+            const { keys, comments } = listKeys(absPath);
+            output("vault-list", { ref: `vault:${name}`, path: absPath, keys, comments });
+        });
+    },
+});
+const vaultCommand = defineCommand({
+    meta: {
+        name: "vault",
+        description: "Manage secret vaults (.env files). Lists keys + comments only — values never returned in structured output.",
+    },
+    subCommands: {
+        list: vaultListCommand,
+        show: vaultShowCommand,
+        create: vaultCreateCommand,
+        set: vaultSetCommand,
+        unset: vaultUnsetCommand,
+        load: vaultLoadCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasVaultSubcommand(args))
+                return;
+            // Default action: list all vaults
+            const { listKeys } = await import("./vault.js");
+            output("vault-list", { vaults: listVaultsRecursive(listKeys) });
+        });
+    },
+});
+// ── Wiki subcommands ─────────────────────────────────────────────────────────
+const wikiCreateCommand = defineCommand({
+    meta: { name: "create", description: "Scaffold a new wiki under <stashDir>/wikis/<name>/" },
+    args: {
+        name: { type: "positional", description: "Wiki name (lowercase, digits, hyphens)", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { createWiki } = await import("./wiki.js");
+            const stashDir = resolveStashDir();
+            const result = createWiki(stashDir, args.name);
+            output("wiki-create", result);
+        });
+    },
+});
+const wikiListCommand = defineCommand({
+    meta: { name: "list", description: "List wikis with page/raw counts and last-modified timestamps" },
+    run() {
+        return runWithJsonErrors(async () => {
+            const { listWikis } = await import("./wiki.js");
+            const stashDir = resolveStashDir();
+            const wikis = listWikis(stashDir);
+            output("wiki-list", { wikis });
+        });
+    },
+});
+const wikiShowCommand = defineCommand({
+    meta: { name: "show", description: "Show a wiki's path, description, counts, and last 3 log entries" },
+    args: {
+        name: { type: "positional", description: "Wiki name", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { showWiki } = await import("./wiki.js");
+            const stashDir = resolveStashDir();
+            const result = showWiki(stashDir, args.name);
+            output("wiki-show", result);
+        });
+    },
+});
+const wikiRemoveCommand = defineCommand({
+    meta: {
+        name: "remove",
+        description: "Remove a wiki. Preserves raw/ by default; pass --with-sources to also delete raw/",
+    },
+    args: {
+        name: { type: "positional", description: "Wiki name", required: true },
+        force: {
+            type: "boolean",
+            description: "Remove without prompting (required in non-interactive shells)",
+            default: false,
+        },
+        "with-sources": {
+            type: "boolean",
+            description: "Also delete the raw/ directory (immutable ingested sources)",
+            default: false,
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (!args.force) {
+                throw new UsageError("Refusing to remove without --force. Pass `--force` to confirm.");
+            }
+            const withSources = Boolean(args["with-sources"]);
+            const { removeWiki } = await import("./wiki.js");
+            const stashDir = resolveStashDir();
+            const result = removeWiki(stashDir, args.name, { withSources });
+            output("wiki-remove", result);
+        });
+    },
+});
+const wikiPagesCommand = defineCommand({
+    meta: {
+        name: "pages",
+        description: "List wiki pages (ref + frontmatter description), excluding schema/index/log/raw",
+    },
+    args: {
+        name: { type: "positional", description: "Wiki name", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { listPages } = await import("./wiki.js");
+            const stashDir = resolveStashDir();
+            const pages = listPages(stashDir, args.name);
+            output("wiki-pages", { wiki: args.name, pages });
+        });
+    },
+});
+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)",
+    },
+    args: {
+        name: { type: "positional", description: "Wiki name", required: true },
+        query: { type: "positional", description: "Search query", required: true },
+        limit: { type: "string", description: "Max hits (default 20)", required: false },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { 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}`);
+            }
+            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 });
+            output("search", response);
+        });
+    },
+});
+const wikiStashCommand = defineCommand({
+    meta: {
+        name: "stash",
+        description: "Copy a source into wikis/<name>/raw/<slug>.md with frontmatter. Source may be a file path or '-' for stdin.",
+    },
+    args: {
+        name: { type: "positional", description: "Wiki name", required: true },
+        source: { type: "positional", description: "Source file path, or '-' to read from stdin", required: true },
+        as: { type: "string", description: "Preferred slug base (defaults to source filename or first-line slug)" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { stashRaw } = await import("./wiki.js");
+            const { content, preferredName } = readKnowledgeContent(args.source);
+            const stashDir = resolveStashDir();
+            const result = stashRaw({
+                stashDir,
+                wikiName: args.name,
+                content,
+                preferredName: args.as ?? preferredName,
+                explicitSlug: args.as !== undefined,
+            });
+            output("wiki-stash", { ok: true, wiki: args.name, source: args.source, ...result });
+        });
+    },
+});
+const wikiLintCommand = defineCommand({
+    meta: {
+        name: "lint",
+        description: "Structural lint for a wiki: orphans, broken xrefs, missing descriptions, uncited raws, stale index",
+    },
+    args: {
+        name: { type: "positional", description: "Wiki name", required: true },
+    },
+    async run({ args }) {
+        let findingCount = 0;
+        await runWithJsonErrors(async () => {
+            const { lintWiki } = await import("./wiki.js");
+            const stashDir = resolveStashDir();
+            const report = lintWiki(stashDir, args.name);
+            output("wiki-lint", report);
+            findingCount = report.findings.length;
+        });
+        if (findingCount > 0)
+            process.exit(1); // EXIT_GENERAL
+    },
+});
+const wikiIngestCommand = defineCommand({
+    meta: {
+        name: "ingest",
+        description: "Print the ingest workflow for this wiki. Does not perform the ingest; instructs the agent to.",
+    },
+    args: {
+        name: { type: "positional", description: "Wiki name", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { buildIngestWorkflow } = await import("./wiki.js");
+            const stashDir = resolveStashDir();
+            const result = buildIngestWorkflow(stashDir, args.name);
+            output("wiki-ingest", result);
+        });
+    },
+});
+const wikiCommand = defineCommand({
+    meta: {
+        name: "wiki",
+        description: "Manage multiple markdown wikis (Karpathy-style). akm surfaces (lifecycle, raw/, lint, index); the agent writes pages.",
+    },
+    subCommands: {
+        create: wikiCreateCommand,
+        list: wikiListCommand,
+        show: wikiShowCommand,
+        remove: wikiRemoveCommand,
+        pages: wikiPagesCommand,
+        search: wikiSearchCommand,
+        stash: wikiStashCommand,
+        lint: wikiLintCommand,
+        ingest: wikiIngestCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasWikiSubcommand(args))
+                return;
+            // Default action: list wikis
+            const { listWikis } = await import("./wiki.js");
+            output("wiki-list", { wikis: listWikis(resolveStashDir()) });
+        });
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -1648,8 +2659,8 @@ const main = defineCommand({
         description: "Agent Kit Manager — search, show, and manage assets from your stash.",
     },
     args: {
-        format: { type: "string", description: "Output format (json|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full|summary)" },
         quiet: { type: "boolean", alias: "q", description: "Suppress stderr warnings", default: false },
     },
     subCommands: {
@@ -1665,19 +2676,26 @@ const main = defineCommand({
         search: searchCommand,
         curate: curateCommand,
         show: showCommand,
+        workflow: workflowCommand,
         remember: rememberCommand,
         import: importKnowledgeCommand,
+        save: saveCommand,
         clone: cloneCommand,
         registry: registryCommand,
         config: configCommand,
         enable: enableCommand,
         disable: disableCommand,
         feedback: feedbackCommand,
+        help: helpCommand,
         hints: hintsCommand,
         completions: completionsCommand,
+        vault: vaultCommand,
+        wiki: wikiCommand,
     },
 });
 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 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.
@@ -1738,6 +2756,14 @@ function hasConfigSubcommand(args) {
     const command = Array.isArray(args._) ? args._[0] : undefined;
     return typeof command === "string" && CONFIG_SUBCOMMAND_SET.has(command);
 }
+function hasVaultSubcommand(args) {
+    const command = Array.isArray(args._) ? args._[0] : undefined;
+    return typeof command === "string" && VAULT_SUBCOMMAND_SET.has(command);
+}
+function hasWikiSubcommand(args) {
+    const command = Array.isArray(args._) ? args._[0] : undefined;
+    return typeof command === "string" && WIKI_SUBCOMMAND_SET.has(command);
+}
 /**
  * Normalize argv so positional view-mode arguments after the asset ref
  * are rewritten into internal flags that citty can parse.
@@ -1813,7 +2839,7 @@ function loadHints(detail = "normal") {
     const fallback = detail === "full" ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
     // Try reading from the docs/ directory (works in dev and when installed via npm)
     try {
-        const docsPath = path.resolve(import.meta.dir ?? __dirname, `../docs/${filename}`);
+        const docsPath = path.resolve(import.meta.dir ?? __dirname, `../docs/agents/${filename}`);
         if (fs.existsSync(docsPath)) {
             return fs.readFileSync(docsPath, "utf8");
         }
@@ -1826,21 +2852,25 @@ function loadHints(detail = "normal") {
 }
 const EMBEDDED_HINTS = `# akm CLI
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your sources first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, wikis, and memories via \`akm\`. Search your sources first before writing something from scratch.
 
 ## Quick Reference
 
 \`\`\`sh
 akm search "<query>"                          # Search all sources
 akm curate "<task>"                          # Curate the best matches for a task
-akm search "<query>" --type skill             # Filter by type
+akm search "<query>" --type workflow          # Filter to workflow assets
 akm search "<query>" --source both            # Also search registries
 akm show <ref>                                # View asset details
+akm workflow next <ref>                       # Start or resume a workflow
 akm remember "Deployment needs VPN access"    # Record a memory in your stash
 akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
+akm wiki list                                 # List available wikis
+akm wiki ingest <name>                        # Print the ingest workflow for a wiki
 akm feedback <ref> --positive|--negative      # Record whether an asset helped
 akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
+akm save                                      # Commit (and push if writable remote) changes in the primary stash
 akm registry search "<query>"                 # Search all registries
 \`\`\`
 
@@ -1853,7 +2883,10 @@ akm registry search "<query>"                 # Search all registries
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
 | knowledge | A reference doc (use \`toc\` or \`section "..."\` to navigate) |
+| workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
+| vault | Key names only; use vault commands to inspect or load values safely |
+| wiki | A page in a multi-wiki knowledge base. For any wiki task, start with \`akm wiki list\`, then \`akm wiki ingest <name>\` for the workflow. Run \`akm wiki -h\` for the full surface. |
 
 When an asset meaningfully helps or fails, record that with \`akm feedback\` so
 future search ranking can learn from real usage.
@@ -1862,14 +2895,14 @@ Run \`akm -h\` for the full command reference.
 `;
 const EMBEDDED_HINTS_FULL = `# akm CLI — Full Reference
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your sources first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, wikis, and memories via \`akm\`. Search your sources first before writing something from scratch.
 
 ## Search
 
 \`\`\`sh
 akm search "<query>"                          # Search all sources
 akm curate "<task>"                          # Curate the best matches for a task
-akm search "<query>" --type skill             # Filter by asset type
+akm search "<query>" --type workflow          # Filter by asset type
 akm search "<query>" --source both            # Also search registries
 akm search "<query>" --source registry        # Search registries only
 akm search "<query>" --limit 10               # Limit results
@@ -1878,7 +2911,7 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 
 | Flag | Values | Default |
 | --- | --- | --- |
-| \`--type\` | \`skill\`, \`command\`, \`agent\`, \`knowledge\`, \`script\`, \`memory\`, \`any\` | \`any\` |
+| \`--type\` | \`skill\`, \`command\`, \`agent\`, \`knowledge\`, \`workflow\`, \`script\`, \`memory\`, \`vault\`, \`wiki\`, \`any\` | \`any\` |
 | \`--source\` | \`stash\`, \`registry\`, \`both\` | \`stash\` |
 | \`--limit\` | number | \`20\` |
 | \`--format\` | \`json\`, \`jsonl\`, \`text\`, \`yaml\` | \`json\` |
@@ -1892,7 +2925,7 @@ Combine search + follow-up hints into a dense summary for a task or prompt.
 \`\`\`sh
 akm curate "plan a release"                   # Pick top matches across asset types
 akm curate "deploy a Bun app" --limit 3       # Keep the summary shorter
-akm curate "review architecture" --type skill # Restrict to one asset type
+akm curate "review architecture" --type workflow # Restrict to one asset type
 \`\`\`
 
 ## Show
@@ -1904,6 +2937,7 @@ akm show script:deploy.sh                     # Show script (returns run command
 akm show skill:code-review                    # Show skill (returns full content)
 akm show command:release                      # Show command (returns template)
 akm show agent:architect                      # Show agent (returns system prompt)
+akm show workflow:ship-release                # Show parsed workflow steps
 akm show knowledge:guide toc                  # Table of contents
 akm show knowledge:guide section "Auth"       # Specific section
 akm show knowledge:guide lines 10 30          # Line range
@@ -1917,7 +2951,10 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | command | \`template\`, \`description\`, \`parameters\` |
 | agent | \`prompt\`, \`description\`, \`modelHint\`, \`toolPolicy\` |
 | knowledge | \`content\` (with view modes: \`full\`, \`toc\`, \`frontmatter\`, \`section\`, \`lines\`) |
+| workflow | \`workflowTitle\`, \`workflowParameters\`, \`steps\` |
 | memory | \`content\` (recalled context) |
+| vault | \`keys\`, \`comments\` |
+| wiki | \`content\` (same view modes as knowledge). For any wiki task, run \`akm wiki list\` then \`akm wiki ingest <name>\` for the workflow. |
 
 ## Capture Knowledge While You Work
 
@@ -1926,6 +2963,8 @@ akm remember "Deployment needs VPN access"     # Record a memory in your stash
 akm remember --name release-retro < notes.md   # Save multiline memory from stdin
 akm import ./docs/auth-flow.md                 # Import a file as knowledge
 akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
+akm workflow create ship-release               # Create a workflow asset in the stash
+akm workflow next workflow:ship-release        # Start or resume the next workflow step
 akm feedback skill:code-review --positive      # Record that an asset helped
 akm feedback agent:reviewer --negative         # Record that an asset missed the mark
 \`\`\`
@@ -1933,22 +2972,62 @@ akm feedback agent:reviewer --negative         # Record that an asset missed the
 Use \`akm feedback\` whenever an asset materially helps or fails so future search
 ranking can learn from actual usage.
 
-## Add & Manage Sources
+## 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.
 
 \`\`\`sh
-akm add <ref>                                 # Add a source
-akm add @scope/kit                            # From npm (managed)
-akm add owner/repo                            # From GitHub (managed)
-akm add ./path/to/local/kit                   # Local directory
-akm enable skills.sh                          # Enable the skills.sh registry
-akm disable skills.sh                         # Disable the skills.sh registry
-akm enable context-hub                        # Add/enable the context-hub source
-akm disable context-hub                       # Disable the context-hub source
-akm list                                      # List all sources
-akm list --kind managed                       # List managed sources only
-akm remove <target>                           # Remove by id, ref, path, or name
-akm update --all                              # Update all managed sources
-akm update <target> --force                   # Force re-download
+akm wiki list                                  # List wikis (name, pages, raws, last-modified)
+akm wiki create research                       # Scaffold a new 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)
+akm wiki stash research ./paper.md             # Copy source into raw/<slug>.md (never overwrites)
+echo "..." | akm wiki stash research -         # stdin form
+akm wiki lint research                         # Structural checks: orphans, broken xrefs, uncited raws, stale index
+akm wiki ingest research                       # Print the ingest workflow for this wiki (no action)
+akm wiki remove research --force               # Delete pages/schema/index/log; preserves raw/
+akm wiki remove research --force --with-sources # Full nuke, including raw/
+\`\`\`
+
+**For any wiki task, start with \`akm wiki list\`, then \`akm wiki ingest <name>\`
+to get the step-by-step workflow.** Wiki pages are also addressable as
+\`wiki:<name>/<page-path>\` and show up in stash-wide \`akm search\` as
+\`type: wiki\`. Files under \`raw/\` and the wiki root infrastructure files
+\`schema.md\`, \`index.md\`, and \`log.md\` are not indexed and do not appear in
+search results. No \`--llm\` anywhere — akm never reasons about page content.
+
+## Vaults
+
+Encrypted-at-rest key/value stores for secrets. Each vault is a \`.env\`-format
+file at \`<stashDir>/vaults/<name>.env\`.
+
+\`\`\`sh
+akm vault create prod                         # Create a new vault
+akm vault set prod DB_URL postgres://...      # Set a key (or KEY=VALUE combined form)
+akm vault set prod DB_URL=postgres://...      # Combined KEY=VALUE form also works
+akm vault unset prod DB_URL                   # Remove a key
+akm vault list vault:prod                     # List key names (no values)
+akm vault show vault:prod                     # Same as list (alias)
+akm vault load vault:prod                     # Print export statements to source
+\`\`\`
+
+## Workflows
+
+Step-based workflows stored as \`<stashDir>/workflows/<name>.md\`.
+
+\`\`\`sh
+akm workflow template                         # Print a starter workflow template
+akm workflow create ship-release             # Scaffold a new workflow asset
+akm workflow start workflow:ship-release     # Start a new run
+akm workflow next workflow:ship-release      # Advance to the next step (or auto-start)
+akm workflow complete <run-id>               # Mark a step complete and advance
+akm workflow status <run-id>                 # Show current run status
+akm workflow resume <run-id>                 # Resume a blocked or failed run
+akm workflow list                            # List all workflow runs
 \`\`\`
 
 ## Clone
@@ -1965,6 +3044,47 @@ akm clone "npm:@scope/pkg//script:deploy.sh"  # Clone from remote package
 
 When \`--dest\` is provided, \`akm init\` is not required first.
 
+## Save
+
+Commit local changes in a git-backed stash. Behaviour adapts automatically:
+
+- **Not a git repo** — no-op (silent skip)
+- **Git repo, no remote** — stage and commit only (the default stash always falls here)
+- **Git repo, has remote, not writable** — stage and commit only
+- **Git repo, has remote, \`writable: true\`** — stage, commit, and push
+
+\`\`\`sh
+akm save                                      # Save primary stash (timestamp message)
+akm save -m "Add deploy skill"               # Save with explicit message
+akm save my-skills                            # Save a named writable git stash
+akm save my-skills -m "Update patterns"      # Save named stash with message
+\`\`\`
+
+The \`--writable\` flag on \`akm add\` opts a remote git stash into push-on-save:
+
+\`\`\`sh
+akm add git@github.com:org/skills.git --provider git --name my-skills --writable
+\`\`\`
+
+## Add & Manage Sources
+
+\`\`\`sh
+akm add <ref>                                 # Add a source
+akm add @scope/kit                            # From npm (managed)
+akm add owner/repo                            # From GitHub (managed)
+akm add ./path/to/local/kit                   # Local directory
+akm add git@github.com:org/repo.git --provider git --name my-skills --writable
+akm enable skills.sh                          # Enable the skills.sh registry
+akm disable skills.sh                         # Disable the skills.sh registry
+akm enable context-hub                        # Add/enable the context-hub source
+akm disable context-hub                       # Disable the context-hub source
+akm list                                      # List all sources
+akm list --kind managed                       # List managed sources only
+akm remove <target>                           # Remove by id, ref, path, or name
+akm update --all                              # Update all managed sources
+akm update <target> --force                   # Force re-download
+\`\`\`
+
 ## Registries
 
 \`\`\`sh
@@ -1996,8 +3116,9 @@ akm init                                      # Initialize working stash
 akm index                                     # Rebuild search index
 akm index --full                              # Full reindex
 akm list                                      # List all sources
-akm upgrade                                   # Upgrade akm binary
+akm upgrade                                   # Upgrade akm using its install method
 akm upgrade --check                           # Check for updates
+akm help migrate 0.5.0                        # Print migration notes for a release
 akm hints                                     # Print this reference
 akm completions                               # Print bash completion script
 akm completions --install                     # Install completions