akm-opencode 0.4.2 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # akm-opencode
 
-OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI. Registers tools that let your AI agent **search**, **show**, and **manage** extension assets from stash directories and registries — plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used, and harvest session memories so the stash improves with every session.
+OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI (v0.5.0+). Registers tools that let your AI agent **search**, **show**, and **manage** stash assets — skills, commands, agents, knowledge, memories, scripts, workflows, vaults, and wikis — plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used, and harvest session memories so the stash improves with every session.
 
 ## Installation
 
@@ -16,25 +16,30 @@ Add to your OpenCode config (`opencode.json`):
 
 | Tool | Description |
 |------|-------------|
-| `akm_search` | Search the local stash, the registry, or both for scripts, skills, commands, agents, and knowledge |
+| `akm_search` | Search the local stash, the registry, or both. Type filter accepts `skill`, `command`, `agent`, `knowledge`, `memory`, `script`, `workflow`, `vault`, `wiki`, `any` |
 | `akm_registry_search` | Search configured registries for installable kits and optional asset-level hits |
 | `akm_show` | Show a stash asset by its ref |
 | `akm_index` | Build or rebuild the search index |
 | `akm_agent` | Dispatch a stash `agent:*` into OpenCode using the stash prompt and metadata |
 | `akm_cmd` | Execute a stash `command:*` template in OpenCode via SDK session prompting |
-| `akm_add` | Install kits from npm, GitHub, git URLs, or local directories |
+| `akm_add` | Install kits or register external sources from npm, GitHub, git URLs, URLs, or local dirs (use `type: "wiki"` to register a wiki; `writable`, `trust`, `max_pages`, `max_depth`, `provider`, `options` also supported) |
 | `akm_list` | List configured AKM sources |
 | `akm_remove` | Remove a configured AKM source and reindex |
 | `akm_update` | Update one managed source or all managed sources |
 | `akm_clone` | Clone an asset into the working stash or a custom destination for editing |
 | `akm_remember` | Record a memory in the default stash |
-| `akm_feedback` | Record positive or negative feedback for a stash asset |
+| `akm_feedback` | Record positive or negative feedback for a stash asset (skipped automatically for `memory:` and `vault:` refs) |
 | `akm_config` | Get, set, unset, list, or inspect akm configuration (including `config path --all`) |
 | `akm_run` | Execute a stash script using its `run` field |
 | `akm_sources` | Backward-compatible alias that lists configured AKM sources |
 | `akm_upgrade` | Check for or install akm CLI updates |
 | `akm_curate` | Curate the stash for a task or topic and return ranked matches the agent can use |
 | `akm_evolve` | Dispatch the AKM curator agent to review recent session activity and propose stash improvements |
+| `akm_save` | Commit (and push, when writable) pending changes in a git-backed stash |
+| `akm_import` | Import a file (or stdin content) into the stash as a typed asset |
+| `akm_vault` | Manage vaults (`list`, `show`, `create`, `set`, `unset`, `shell_snippet`). **Values never surface** — `show`/`list` return key names only. `shell_snippet` returns opaque `eval` text |
+| `akm_wiki` | Manage wikis (`create`, `register`, `list`, `show`, `pages`, `search`, `stash`, `lint`, `ingest`, `remove`) |
+| `akm_workflow` | Drive workflow runs (`start`, `next`, `complete`, `status`, `list`, `create`, `template`, `resume`) |
 
 ## Compound-engineering hooks
 
@@ -142,9 +147,29 @@ stash/
 ├── skills/     # skill directories containing SKILL.md
 ├── commands/   # markdown files
 ├── agents/     # markdown files
-└── knowledge/  # markdown files
+├── knowledge/  # markdown files
+├── memories/   # markdown memory files (akm remember)
+├── workflows/  # multi-step procedures (workflow:<name>)
+├── vaults/     # .env secret stores (vault:<name>) — values never surface through structured output
+└── wikis/      # per-wiki directories <name>/{schema,index,log}.md + raw/ + pages
 ```
 
+## Vaults
+
+`akm_vault` is the one tool in this plugin with a hard contract on output. The
+AKM CLI itself guarantees vault values never appear in JSON, the search index,
+`.stash.json`, or any structured output channel. This plugin mirrors that:
+
+- `action: "list"` / `"show"` return key names and comments only.
+- `action: "set"` / `"unset"` never echo the value.
+- `action: "shell_snippet"` wraps `akm vault load` and returns the raw shell
+  text as-is. Treat it as opaque and hand it straight to a shell via
+  `eval "$(…)"` — do not log it, do not pass it through another tool, and do
+  not let the agent inspect it.
+
+Automatic feedback recording (`tool.execute.after`) skips `vault:*` refs so
+that usage signals can't leak which vault was touched.
+
 Assets are resolved from three source types: **working** (local stash), **search paths** (additional dirs via `searchPaths` config), and **installed** (registry kits via `akm add`).
 
 ## Docs

package/index.ts

@@ -29,7 +29,7 @@ const sessionBuffer = new Map<string, SessionBufferEntry[]>()
 const sessionMemoryCaptured = new Set<string>()
 
 // Asset-ref grammar matching the stash skill: [origin//]type:name
-const AKM_REF_PATTERN = /(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script):[A-Za-z0-9._/\-]+/g
+const AKM_REF_PATTERN = /(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script|workflow|vault|wiki):[A-Za-z0-9._/\-]+/g
 
 const CURATOR_AGENT_PROMPT = `You are the AKM curator — a compound-engineering agent that keeps the user's AKM stash improving every time the main agent finishes a task.
 
@@ -41,9 +41,12 @@ Inputs you should inspect:
 Signals to act on:
 - Hot refs: assets repeatedly appearing in positive tool outcomes. Call akm_feedback <ref> positive --note "curator: consistently useful" to reinforce.
 - Cold refs: assets tied to failures or user complaints. Record akm_feedback <ref> negative --note "<excerpt>" and open the asset for review.
-- Missing coverage: recurring user prompts with no matching asset. Draft a new skill, command, or knowledge doc in the working stash and reindex with akm_index.
+- Missing coverage: recurring user prompts with no matching asset. Draft a new skill, command, knowledge doc, wiki page, or workflow in the working stash and reindex with akm_index.
 - Duplicates / drift: near-identical descriptions or overlapping responsibilities. Propose a consolidation.
-- Stale memories: session summaries that never get recalled. Propose akm_remove memory:<name> once distilled into a durable knowledge doc.
+- Stale memories: session summaries that never get recalled. Propose akm_remove memory:<name> once distilled into a durable knowledge doc or wiki page.
+- Wiki hygiene: for each wiki returned by akm_wiki list, run akm_wiki lint <name> and report orphans, broken xrefs, uncited raws, and stale indexes as fix candidates.
+- Stuck workflows: run akm_workflow list --active and surface any runs in blocked or failed state with their step ids. Propose whether to resume or escalate.
+- Never touch vaults: do not call akm_vault show or shell_snippet unless the user explicitly asks. Vault values must never appear in reports.
 
 Rules of engagement:
 - Never apply destructive changes without explicit user approval.
@@ -66,6 +69,12 @@ Output shape: end every run with a markdown report that has these sections:
 ## Duplicates / drift
 - <ref a> vs <ref b> — consolidation proposal
 
+## Wiki health
+- <wiki> — lint findings (orphan, broken-xref, uncited-raw, stale-index) with suggested fix
+
+## Workflow health
+- <workflow|runId> — blocked/failed state — resume or escalate
+
 ## Housekeeping
 - stale memories, reindex needs, config tweaks
 `
@@ -92,6 +101,14 @@ type CliLogMeta = {
   sessionID?: string
 }
 
+type SessionPromptBody = {
+  agent: string
+  parts: Array<{ type: "text"; text: string }>
+  system?: string
+  model?: { providerID: string; modelID: string }
+  tools?: Record<string, boolean>
+}
+
 function formatCliError(error: unknown): string {
   if (error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "ENOENT") {
     return "The 'akm' CLI was not found on PATH. Install it first from https://github.com/itlackey/akm."
@@ -480,7 +497,29 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
 }
 
 type CliError = { ok: false; error: string }
-type AssetType = "agent" | "command" | "knowledge" | "memory" | "script" | "skill"
+type AssetType =
+  | "agent"
+  | "command"
+  | "knowledge"
+  | "memory"
+  | "script"
+  | "skill"
+  | "workflow"
+  | "vault"
+  | "wiki"
+
+const ASSET_TYPES = [
+  "agent",
+  "command",
+  "knowledge",
+  "memory",
+  "script",
+  "skill",
+  "workflow",
+  "vault",
+  "wiki",
+  "any",
+] as const
 
 type ShowAgentResponse = {
   type: "agent"
@@ -729,18 +768,111 @@ async function ensureTargetSessionID(input: {
   context: { sessionID: string; directory: string }
   title: string
   client: PluginClient
+  logClient: LogCapableClient
+  toolName: string
 }): Promise<{ ok: true; sessionID: string } | CliError> {
   if (!input.useSubtask) return { ok: true, sessionID: input.context.sessionID }
 
-  const created = await input.client.session.create({
-    query: { directory: input.context.directory },
-    body: { parentID: input.context.sessionID, title: input.title },
-  })
-  if (created.error || !created.data?.id) {
-    const reason = created.error ? JSON.stringify(created.error) : "missing child session id"
+  try {
+    const created = await input.client.session.create({
+      body: { parentID: input.context.sessionID, title: input.title },
+    })
+    if (created.error || !created.data?.id) {
+      const reason = created.error ? JSON.stringify(created.error) : "missing child session id"
+      await writePluginLog(input.logClient, "error", "AKM dispatch child session failed", {
+        subsystem: "dispatch",
+        toolName: input.toolName,
+        sessionID: input.context.sessionID,
+        directory: input.context.directory,
+        title: input.title,
+        error: reason,
+      })
+      return { ok: false, error: `Failed to create child session: ${reason}` }
+    }
+    await writePluginLog(input.logClient, "info", "AKM dispatch child session created", {
+      subsystem: "dispatch",
+      toolName: input.toolName,
+      sessionID: input.context.sessionID,
+      directory: input.context.directory,
+      childSessionID: created.data.id,
+      title: input.title,
+    })
+    return { ok: true, sessionID: created.data.id }
+  } catch (error: unknown) {
+    const reason = error instanceof Error ? error.message : String(error)
+    await writePluginLog(input.logClient, "error", "AKM dispatch child session threw", {
+      subsystem: "dispatch",
+      toolName: input.toolName,
+      sessionID: input.context.sessionID,
+      directory: input.context.directory,
+      title: input.title,
+      error: reason,
+    })
     return { ok: false, error: `Failed to create child session: ${reason}` }
   }
-  return { ok: true, sessionID: created.data.id }
+}
+
+async function promptTargetSession(input: {
+  client: PluginClient
+  logClient: LogCapableClient
+  toolName: string
+  context: { sessionID: string; directory: string }
+  targetSessionID: string
+  promptBody: SessionPromptBody
+  failureMessage: string
+  ref?: string
+}): Promise<{ ok: true; data: { parts?: unknown } } | CliError> {
+  try {
+    const promptResponse = await input.client.session.prompt({
+      path: { id: input.targetSessionID },
+      body: input.promptBody,
+    })
+
+    if (promptResponse.error || !promptResponse.data) {
+      const reason = promptResponse.error ? JSON.stringify(promptResponse.error) : "empty response"
+      await writePluginLog(input.logClient, "error", "AKM dispatch prompt failed", {
+        subsystem: "dispatch",
+        toolName: input.toolName,
+        sessionID: input.context.sessionID,
+        directory: input.context.directory,
+        targetSessionID: input.targetSessionID,
+        dispatchAgent: input.promptBody.agent,
+        ref: input.ref,
+        error: reason,
+      })
+      return {
+        ok: false,
+        error: `${input.failureMessage}: ${reason}`,
+      }
+    }
+
+    await writePluginLog(input.logClient, "info", "AKM dispatch prompt completed", {
+      subsystem: "dispatch",
+      toolName: input.toolName,
+      sessionID: input.context.sessionID,
+      directory: input.context.directory,
+      targetSessionID: input.targetSessionID,
+      dispatchAgent: input.promptBody.agent,
+      ref: input.ref,
+    })
+    return { ok: true, data: promptResponse.data }
+  } catch (error: unknown) {
+    const reason = error instanceof Error ? error.message : String(error)
+    await writePluginLog(input.logClient, "error", "AKM dispatch prompt threw", {
+      subsystem: "dispatch",
+      toolName: input.toolName,
+      sessionID: input.context.sessionID,
+      directory: input.context.directory,
+      targetSessionID: input.targetSessionID,
+      dispatchAgent: input.promptBody.agent,
+      ref: input.ref,
+      error: reason,
+    })
+    return {
+      ok: false,
+      error: `${input.failureMessage}: ${reason}`,
+    }
+  }
 }
 
 function splitArguments(raw: string): string[] {
@@ -767,7 +899,7 @@ function normalizeSearchSource(source: "local" | "stash" | "registry" | "both"):
 
 function createSearchArgs(input: {
   query: string
-  type?: AssetType | "any"
+  type?: AssetType | "any" | string
   limit?: number
   source?: "local" | "stash" | "registry" | "both"
   defaultSource?: "local" | "stash" | "registry" | "both"
@@ -787,19 +919,11 @@ function createSearchArgs(input: {
 type PluginClient = {
   session: {
     create: (input: {
-      query: { directory: string }
       body: { parentID: string; title: string }
     }) => Promise<{ data?: { id?: string }; error?: unknown }>
     prompt: (input: {
-      query: { directory: string }
       path: { id: string }
-      body: {
-        agent: string
-        parts: Array<{ type: "text"; text: string }>
-        system?: string
-        model?: { providerID: string; modelID: string }
-        tools?: Record<string, boolean>
-      }
+      body: SessionPromptBody
     }) => Promise<{ data?: { parts?: unknown }; error?: unknown }>
   }
 }
@@ -980,8 +1104,10 @@ export const AkmPlugin: Plugin = async ({ client }) => {
           ? `opencode auto: ${input.tool} succeeded`
           : `opencode auto: ${input.tool} failed`
         for (const ref of allRefs) {
-          // Memories do not accept feedback in the current CLI.
-          if (ref.startsWith("memory:")) continue
+          // Memories and vault refs are not first-class feedback targets —
+          // memories do not accept feedback, and vault values never surface in
+          // JSON so automatic usage signals would be misleading.
+          if (ref.startsWith("memory:") || ref.startsWith("vault:")) continue
           const ok = recordFeedbackSync(ref, feedback, note)
           if (!ok) break
         }
@@ -989,11 +1115,11 @@ export const AkmPlugin: Plugin = async ({ client }) => {
     },
     tool: {
     akm_search: tool({
-      description: "Search your stash or the akm registry for scripts, skills, commands, agents, knowledge, and memories. Use source='registry' or akm_registry_search for installable community kits.",
+      description: "Search your stash or the akm registry for scripts, skills, commands, agents, knowledge, memories, workflows, vaults, and wikis. Use source='registry' or akm_registry_search for installable community kits.",
       args: {
         query: tool.schema.string().describe("Case-insensitive substring search."),
         type: tool.schema
-          .enum(["agent", "command", "knowledge", "memory", "script", "skill", "any"])
+          .enum(ASSET_TYPES as unknown as [string, ...string[]])
           .optional()
           .describe("Optional type filter. Defaults to 'any'."),
         limit: tool.schema.number().optional().describe("Maximum number of hits to return. Defaults to 20."),
@@ -1011,7 +1137,7 @@ export const AkmPlugin: Plugin = async ({ client }) => {
       args: {
         query: tool.schema.string().describe("Search query for installable registry kits."),
         type: tool.schema
-          .enum(["agent", "command", "knowledge", "memory", "script", "skill", "any"])
+          .enum(ASSET_TYPES as unknown as [string, ...string[]])
           .optional()
           .describe("Optional asset type filter. Defaults to 'any'."),
         limit: tool.schema.number().optional().describe("Maximum number of registry hits to return. Defaults to 20."),
@@ -1077,12 +1203,29 @@ export const AkmPlugin: Plugin = async ({ client }) => {
       },
     }),
     akm_add: tool({
-      description: "Install a kit from npm, GitHub, another git host, or a local directory. Installed kits become searchable alongside local assets.",
+      description: "Install a kit or register an external source from npm, GitHub, another git host, a URL, or a local directory. Use type='wiki' to register a wiki source instead of a stash kit.",
       args: {
-        package_ref: tool.schema.string().describe("Package reference such as npm:@scope/kit, github:<owner>/<repo>, git+https://host/repo, or ./local/kit."),
+        package_ref: tool.schema.string().describe("Package reference such as npm:@scope/kit, github:<owner>/<repo>, git+https://host/repo, https://url, or ./local/kit."),
+        type: tool.schema.enum(["wiki"]).optional().describe("Route the add through a typed registrar. 'wiki' registers an external wiki source."),
+        name: tool.schema.string().optional().describe("Optional name to register the source under."),
+        writable: tool.schema.boolean().optional().describe("Mark a git-backed source as push-writable (used by akm save)."),
+        trust: tool.schema.boolean().optional().describe("Bypass install-audit blocking for this registration only."),
+        provider: tool.schema.string().optional().describe("Provider hint (required for raw URL refs, e.g. 'github', 'website')."),
+        options: tool.schema.string().optional().describe("JSON string of provider-specific options."),
+        max_pages: tool.schema.number().optional().describe("Cap for website crawlers (default 50)."),
+        max_depth: tool.schema.number().optional().describe("Depth cap for website crawlers (default 3)."),
       },
-      async execute({ package_ref }) {
-        return runCli(client as unknown as LogCapableClient, ["add", package_ref], { toolName: "akm_add" })
+      async execute({ package_ref, type, name, writable, trust, provider, options, max_pages, max_depth }) {
+        const args = ["add", package_ref]
+        if (type) args.push("--type", type)
+        if (name) args.push("--name", name)
+        if (writable) args.push("--writable")
+        if (trust) args.push("--trust")
+        if (provider) args.push("--provider", provider)
+        if (options) args.push("--options", options)
+        if (max_pages != null) args.push("--max-pages", String(max_pages))
+        if (max_depth != null) args.push("--max-depth", String(max_depth))
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_add" })
       },
     }),
     akm_list: tool({
@@ -1203,6 +1346,8 @@ export const AkmPlugin: Plugin = async ({ client }) => {
           context: { sessionID: context.sessionID, directory: context.directory },
           title: "akm:curator",
           client: client as unknown as PluginClient,
+          logClient,
+          toolName: "akm_evolve",
         })
         if (!targetSession.ok) return JSON.stringify(targetSession)
 
@@ -1210,23 +1355,20 @@ export const AkmPlugin: Plugin = async ({ client }) => {
           ? `Review recent AKM activity with an emphasis on: ${focus.trim()}. Produce the prioritized action list described in the system prompt.`
           : "Review recent AKM activity and produce the prioritized action list described in the system prompt."
 
-        const promptResponse = await client.session.prompt({
-          query: { directory: context.directory },
-          path: { id: targetSession.sessionID },
-          body: {
+        const promptResponse = await promptTargetSession({
+          client: client as unknown as PluginClient,
+          logClient,
+          toolName: "akm_evolve",
+          context: { sessionID: context.sessionID, directory: context.directory },
+          targetSessionID: targetSession.sessionID,
+          failureMessage: "Failed to dispatch curator",
+          promptBody: {
             agent: targetAgent,
             system: CURATOR_AGENT_PROMPT,
             parts: [{ type: "text", text: task }],
           },
         })
-
-        if (promptResponse.error || !promptResponse.data) {
-          const reason = promptResponse.error ? JSON.stringify(promptResponse.error) : "empty response"
-          return JSON.stringify({
-            ok: false,
-            error: `Failed to dispatch curator: ${reason}`,
-          })
-        }
+        if (!promptResponse.ok) return JSON.stringify(promptResponse)
 
         return JSON.stringify({
           ok: true,
@@ -1286,16 +1428,12 @@ export const AkmPlugin: Plugin = async ({ client }) => {
           context: { sessionID: context.sessionID, directory: context.directory },
           title: `akm:${shown.name}`,
           client: client as unknown as PluginClient,
+          logClient,
+          toolName: "akm_agent",
         })
         if (!targetSession.ok) return JSON.stringify(targetSession)
 
-        const promptBody: {
-          agent: string
-          system: string
-          parts: Array<{ type: "text"; text: string }>
-          model?: { providerID: string; modelID: string }
-          tools?: Record<string, boolean>
-        } = {
+        const promptBody: SessionPromptBody = {
           agent: targetAgent,
           system: shown.prompt,
           parts: [{ type: "text", text: task_prompt }],
@@ -1303,19 +1441,17 @@ export const AkmPlugin: Plugin = async ({ client }) => {
         if (model) promptBody.model = model
         if (tools) promptBody.tools = tools
 
-        const promptResponse = await client.session.prompt({
-          query: { directory: context.directory },
-          path: { id: targetSession.sessionID },
-          body: promptBody,
+        const promptResponse = await promptTargetSession({
+          client: client as unknown as PluginClient,
+          logClient,
+          toolName: "akm_agent",
+          context: { sessionID: context.sessionID, directory: context.directory },
+          targetSessionID: targetSession.sessionID,
+          promptBody,
+          failureMessage: `Failed to dispatch prompt for ${resolved.ref}`,
+          ref: resolved.ref,
         })
-
-        if (promptResponse.error || !promptResponse.data) {
-          const reason = promptResponse.error ? JSON.stringify(promptResponse.error) : "empty response"
-          return JSON.stringify({
-            ok: false,
-            error: `Failed to dispatch prompt for ${resolved.ref}: ${reason}`,
-          })
-        }
+        if (!promptResponse.ok) return JSON.stringify(promptResponse)
 
         return JSON.stringify({
           ok: true,
@@ -1370,25 +1506,25 @@ export const AkmPlugin: Plugin = async ({ client }) => {
           context: { sessionID: context.sessionID, directory: context.directory },
           title: `akm:cmd:${shown.name}`,
           client: client as unknown as PluginClient,
+          logClient,
+          toolName: "akm_cmd",
         })
         if (!targetSession.ok) return JSON.stringify(targetSession)
 
-        const promptResponse = await client.session.prompt({
-          query: { directory: context.directory },
-          path: { id: targetSession.sessionID },
-          body: {
+        const promptResponse = await promptTargetSession({
+          client: client as unknown as PluginClient,
+          logClient,
+          toolName: "akm_cmd",
+          context: { sessionID: context.sessionID, directory: context.directory },
+          targetSessionID: targetSession.sessionID,
+          failureMessage: `Failed to execute command ${resolved.ref}`,
+          ref: resolved.ref,
+          promptBody: {
             agent: targetAgent,
             parts: [{ type: "text", text: rendered }],
           },
         })
-
-        if (promptResponse.error || !promptResponse.data) {
-          const reason = promptResponse.error ? JSON.stringify(promptResponse.error) : "empty response"
-          return JSON.stringify({
-            ok: false,
-            error: `Failed to execute command ${resolved.ref}: ${reason}`,
-          })
-        }
+        if (!promptResponse.ok) return JSON.stringify(promptResponse)
 
         return JSON.stringify({
           ok: true,
@@ -1481,6 +1617,324 @@ export const AkmPlugin: Plugin = async ({ client }) => {
         return runCli(client as unknown as LogCapableClient, ["list"], { toolName: "akm_sources" })
       },
     }),
+    akm_save: tool({
+      description: "Commit (and push, when writable) pending changes in a git-backed stash. No-op for non-git stashes.",
+      args: {
+        name: tool.schema.string().optional().describe("Optional stash source name. Defaults to the primary stash."),
+        message: tool.schema.string().optional().describe("Commit message. Defaults to an auto-generated summary."),
+      },
+      async execute({ name, message }) {
+        const args = ["save"]
+        if (name) args.push(name)
+        if (message) args.push("-m", message)
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_save" })
+      },
+    }),
+    akm_import: tool({
+      description: "Import a file (or stdin) into the stash as a typed asset. Pass '-' as source to read from a string via content.",
+      args: {
+        source: tool.schema.string().describe("Path to the source file, or '-' to read from stdin (use 'content' to provide it)."),
+        name: tool.schema.string().optional().describe("Optional asset name override."),
+        force: tool.schema.boolean().optional().describe("Overwrite an existing asset with the same name."),
+        content: tool.schema.string().optional().describe("Raw content to feed on stdin when source is '-'."),
+      },
+      async execute({ source, name, force, content }) {
+        const args = ["import", source]
+        if (name) args.push("--name", name)
+        if (force) args.push("--force")
+        const command = resolveAkmCommand()
+        if (typeof command !== "string") return JSON.stringify(command)
+        if (source === "-" && content) {
+          try {
+            const stdout = execFileSync(command, [...args, "--format", "json"], {
+              encoding: "utf8",
+              timeout: 60_000,
+              input: content,
+            })
+            return stdout
+          } catch (error: unknown) {
+            return JSON.stringify({ ok: false, error: formatCliError(error) })
+          }
+        }
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_import" })
+      },
+    }),
+    akm_vault: tool({
+      description: "Manage encrypted-at-rest vaults of KEY=VALUE pairs. Values never surface in any output channel — 'show'/'list' return key names only, 'set'/'unset' never echo the value. Use 'shell_snippet' to get a shell-eval snippet that loads values into the process.",
+      args: {
+        action: tool.schema.enum(["list", "show", "create", "set", "unset", "shell_snippet"]).describe("Vault subcommand. 'shell_snippet' wraps 'vault load' — treat its output as opaque shell text meant for eval."),
+        ref: tool.schema.string().optional().describe("Vault ref such as vault:prod or vault:team/prod. Required for show/set/unset/shell_snippet; optional for list."),
+        name: tool.schema.string().optional().describe("Vault name when action is 'create' (e.g. 'prod' → vaults/prod.env)."),
+        key: tool.schema.string().optional().describe("Variable name for set/unset. May include '=' to pass KEY=VALUE in one field when value is omitted."),
+        value: tool.schema.string().optional().describe("Value to store. Never echoed back."),
+        comment: tool.schema.string().optional().describe("Optional inline '# comment' written above the key for 'set'."),
+      },
+      async execute({ action, ref, name, key, value, comment }) {
+        const logMeta = { toolName: "akm_vault" }
+        switch (action) {
+          case "list": {
+            const args = ["vault", "list"]
+            if (ref) args.push(ref)
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "show": {
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='show'." })
+            return runCli(client as unknown as LogCapableClient, ["vault", "show", ref], logMeta)
+          }
+          case "create": {
+            if (!name) return JSON.stringify({ ok: false, error: "'name' is required for action='create'." })
+            return runCli(client as unknown as LogCapableClient, ["vault", "create", name], logMeta)
+          }
+          case "set": {
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='set'." })
+            if (!key) return JSON.stringify({ ok: false, error: "'key' is required for action='set'." })
+            const args = ["vault", "set", ref, key]
+            if (value != null) args.push(value)
+            if (comment) args.push("--comment", comment)
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "unset": {
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='unset'." })
+            if (!key) return JSON.stringify({ ok: false, error: "'key' is required for action='unset'." })
+            return runCli(client as unknown as LogCapableClient, ["vault", "unset", ref, key], logMeta)
+          }
+          case "shell_snippet": {
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='shell_snippet'." })
+            // `vault load` emits raw shell — not JSON. Return the snippet verbatim
+            // so the caller can hand it to a shell via eval. Never parse values.
+            const command = resolveAkmCommand()
+            if (typeof command !== "string") return JSON.stringify(command)
+            try {
+              const stdout = execFileSync(command, ["vault", "load", ref], {
+                encoding: "utf8",
+                timeout: 30_000,
+              })
+              return JSON.stringify({ ok: true, ref, shell: stdout.trim() })
+            } catch (error: unknown) {
+              return JSON.stringify({ ok: false, error: formatCliError(error) })
+            }
+          }
+        }
+      },
+    }),
+    akm_wiki: tool({
+      description: "Manage AKM wikis — multi-wiki knowledge bases under <stashDir>/wikis/<name>/. Supports scaffolding, registering external sources, listing pages, scoped search, stashing raw sources, lint, and ingest workflow.",
+      args: {
+        action: tool.schema.enum([
+          "create",
+          "register",
+          "list",
+          "show",
+          "remove",
+          "pages",
+          "search",
+          "stash",
+          "lint",
+          "ingest",
+        ]).describe("Wiki subcommand."),
+        name: tool.schema.string().optional().describe("Wiki name (required for every action except 'list')."),
+        source_ref: tool.schema.string().optional().describe("Source ref to register (required for action='register'). Accepts directory paths, git URLs, github owner/repo, or https:// website roots."),
+        writable: tool.schema.boolean().optional().describe("When registering a git-backed source, mark it as push-writable (used by akm_save)."),
+        trust: tool.schema.boolean().optional().describe("Bypass install-audit blocking for this registration only."),
+        max_pages: tool.schema.number().optional().describe("Crawler page cap when registering a website (default 50)."),
+        max_depth: tool.schema.number().optional().describe("Crawler depth cap when registering a website (default 3)."),
+        query: tool.schema.string().optional().describe("Query string for action='search'."),
+        limit: tool.schema.number().optional().describe("Result cap for action='search'."),
+        source: tool.schema.string().optional().describe("Source path (or '-' for stdin) for action='stash'."),
+        as_slug: tool.schema.string().optional().describe("Explicit slug for action='stash' (defaults to derived from source)."),
+        content: tool.schema.string().optional().describe("Raw content to feed stdin when stashing with source='-'."),
+        force: tool.schema.boolean().optional().describe("Required for action='remove'."),
+        with_sources: tool.schema.boolean().optional().describe("When removing, also delete the raw/ sources (default false)."),
+      },
+      async execute({ action, name, source_ref, writable, trust, max_pages, max_depth, query, limit, source, as_slug, content, force, with_sources }) {
+        const logMeta = { toolName: "akm_wiki" }
+        const requireName = () => {
+          if (!name) return JSON.stringify({ ok: false, error: `'name' is required for action='${action}'.` })
+          return null
+        }
+        switch (action) {
+          case "list":
+            return runCli(client as unknown as LogCapableClient, ["wiki", "list"], logMeta)
+          case "create": {
+            const err = requireName(); if (err) return err
+            return runCli(client as unknown as LogCapableClient, ["wiki", "create", name!], logMeta)
+          }
+          case "show": {
+            const err = requireName(); if (err) return err
+            return runCli(client as unknown as LogCapableClient, ["wiki", "show", name!], logMeta)
+          }
+          case "pages": {
+            const err = requireName(); if (err) return err
+            return runCli(client as unknown as LogCapableClient, ["wiki", "pages", name!], logMeta)
+          }
+          case "ingest": {
+            const err = requireName(); if (err) return err
+            return runCli(client as unknown as LogCapableClient, ["wiki", "ingest", name!], logMeta)
+          }
+          case "lint": {
+            const err = requireName(); if (err) return err
+            // `wiki lint` exits 1 when findings exist, which runCli surfaces as
+            // an error envelope. That is still useful output — the JSON body is
+            // the lint report. Pass through either way.
+            return runCli(client as unknown as LogCapableClient, ["wiki", "lint", name!], logMeta)
+          }
+          case "register": {
+            const err = requireName(); if (err) return err
+            if (!source_ref) return JSON.stringify({ ok: false, error: "'source_ref' is required for action='register'." })
+            const args = ["wiki", "register", name!, source_ref]
+            if (writable) args.push("--writable")
+            if (trust) args.push("--trust")
+            if (max_pages != null) args.push("--max-pages", String(max_pages))
+            if (max_depth != null) args.push("--max-depth", String(max_depth))
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "remove": {
+            const err = requireName(); if (err) return err
+            if (!force) return JSON.stringify({ ok: false, error: "'force' must be true to remove a wiki." })
+            const args = ["wiki", "remove", name!, "--force"]
+            if (with_sources) args.push("--with-sources")
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "search": {
+            const err = requireName(); if (err) return err
+            if (!query) return JSON.stringify({ ok: false, error: "'query' is required for action='search'." })
+            const args = ["wiki", "search", name!, query]
+            if (limit != null) args.push("--limit", String(limit))
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "stash": {
+            const err = requireName(); if (err) return err
+            if (!source) return JSON.stringify({ ok: false, error: "'source' is required for action='stash'." })
+            const args = ["wiki", "stash", name!, source]
+            if (as_slug) args.push("--as", as_slug)
+            if (source === "-" && content) {
+              const command = resolveAkmCommand()
+              if (typeof command !== "string") return JSON.stringify(command)
+              try {
+                const stdout = execFileSync(command, [...args, "--format", "json"], {
+                  encoding: "utf8",
+                  timeout: 60_000,
+                  input: content,
+                })
+                return stdout
+              } catch (error: unknown) {
+                return JSON.stringify({ ok: false, error: formatCliError(error) })
+              }
+            }
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+        }
+      },
+    }),
+    akm_workflow: tool({
+      description: "Manage AKM workflow runs — stateful multi-step procedures defined as workflow:<name> assets. Use start/next/complete/resume to drive a run, status/list to inspect, create/template to author.",
+      args: {
+        action: tool.schema.enum([
+          "start",
+          "next",
+          "complete",
+          "status",
+          "list",
+          "create",
+          "template",
+          "resume",
+        ]).describe("Workflow subcommand."),
+        ref: tool.schema.string().optional().describe("Workflow ref (e.g. workflow:release). Required for start; accepted by next/status as a target."),
+        target: tool.schema.string().optional().describe("Run id or workflow ref for next/status. When a workflow ref is passed to 'next', a new run is auto-started."),
+        run_id: tool.schema.string().optional().describe("Workflow run id. Required for complete and resume."),
+        params: tool.schema.string().optional().describe("JSON object string of parameters for start/next."),
+        step: tool.schema.string().optional().describe("Step id to transition (required for action='complete')."),
+        state: tool.schema.enum(["completed", "blocked", "failed", "skipped"]).optional().describe("Step state for 'complete'. Defaults to 'completed'."),
+        notes: tool.schema.string().optional().describe("Freeform notes attached to the step transition."),
+        evidence: tool.schema.string().optional().describe("JSON object string of evidence attached to the step transition."),
+        name: tool.schema.string().optional().describe("Workflow name for action='create'."),
+        from: tool.schema.string().optional().describe("Path to a markdown template for action='create'."),
+        force: tool.schema.boolean().optional().describe("Overwrite an existing workflow on create (requires --from or --reset)."),
+        reset: tool.schema.boolean().optional().describe("Reset to the built-in template for action='create'."),
+        filter_ref: tool.schema.string().optional().describe("Restrict action='list' to runs of this workflow ref."),
+        active_only: tool.schema.boolean().optional().describe("Restrict action='list' to active (non-terminal) runs."),
+      },
+      async execute({
+        action,
+        ref,
+        target,
+        run_id,
+        params,
+        step,
+        state,
+        notes,
+        evidence,
+        name,
+        from,
+        force,
+        reset,
+        filter_ref,
+        active_only,
+      }) {
+        const logMeta = { toolName: "akm_workflow" }
+        switch (action) {
+          case "start": {
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='start'." })
+            const args = ["workflow", "start", ref]
+            if (params) args.push("--params", params)
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "next": {
+            const picked = target ?? run_id ?? ref
+            if (!picked) return JSON.stringify({ ok: false, error: "'target', 'run_id', or 'ref' is required for action='next'." })
+            const args = ["workflow", "next", picked]
+            if (params) args.push("--params", params)
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "complete": {
+            if (!run_id) return JSON.stringify({ ok: false, error: "'run_id' is required for action='complete'." })
+            if (!step) return JSON.stringify({ ok: false, error: "'step' is required for action='complete'." })
+            const args = ["workflow", "complete", run_id, "--step", step]
+            if (state) args.push("--state", state)
+            if (notes) args.push("--notes", notes)
+            if (evidence) args.push("--evidence", evidence)
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "status": {
+            const picked = target ?? run_id ?? ref
+            if (!picked) return JSON.stringify({ ok: false, error: "'target', 'run_id', or 'ref' is required for action='status'." })
+            return runCli(client as unknown as LogCapableClient, ["workflow", "status", picked], logMeta)
+          }
+          case "list": {
+            const args = ["workflow", "list"]
+            if (filter_ref) args.push("--ref", filter_ref)
+            if (active_only) args.push("--active")
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "create": {
+            if (!name) return JSON.stringify({ ok: false, error: "'name' is required for action='create'." })
+            const args = ["workflow", "create", name]
+            if (from) args.push("--from", from)
+            if (force) args.push("--force")
+            if (reset) args.push("--reset")
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "template": {
+            // The workflow template is emitted as raw markdown, not JSON.
+            const command = resolveAkmCommand()
+            if (typeof command !== "string") return JSON.stringify(command)
+            try {
+              const stdout = execFileSync(command, ["workflow", "template"], {
+                encoding: "utf8",
+                timeout: 30_000,
+              })
+              return JSON.stringify({ ok: true, template: stdout })
+            } catch (error: unknown) {
+              return JSON.stringify({ ok: false, error: formatCliError(error) })
+            }
+          }
+          case "resume": {
+            if (!run_id) return JSON.stringify({ ok: false, error: "'run_id' is required for action='resume'." })
+            return runCli(client as unknown as LogCapableClient, ["workflow", "resume", run_id], logMeta)
+          }
+        }
+      },
+    }),
     akm_upgrade: tool({
       description: "Check for or install akm CLI updates.",
       args: {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "akm-opencode",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
-  "description": "OpenCode plugin for AKM - search, show, and manage extension assets via the akm CLI, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
+  "description": "OpenCode plugin for AKM - search, show, and manage extension assets via the akm CLI, including v0.5.0 vaults, wikis, and workflows, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
   "keywords": [
     "opencode",
     "opencode-ai",