akm 0.5.0: Wikis, Workflows, Vaults, and a Writable Stash

akm 0.5.0 is out. This release adds three new asset types — wikis, workflows, and vaults are now first-class citizens — plus writable git stash support so your stash can sync back to a remote. It also upgrades the self-update path to cover npm, bun, pnpm, and binary installs, and ships a new akm help migrate command for release-to-release guidance. There is one breaking change for anyone who was using the single-wiki LLM POC from 0.4.x.

TL;DR

• akm wiki create|register|list|show|remove|pages|search|stash|lint|ingest — multi-wiki support, no LLM required
• akm workflow template|create|start|next|complete|status|list|resume — multi-step agent procedures in the stash
• akm vault list|show|create|set|unset|load — .env-backed secrets that never appear in structured output
• akm add <source> --writable + akm save — push your stash changes back to a remote git repo
• akm add <source> --trust — bypass the install audit for a single install
• akm add --type wiki --name <name> <source> / akm wiki register — register an existing directory or repo as a first-class wiki
• akm upgrade now covers npm, bun, pnpm, and standalone-binary installs
• akm help migrate <version> prints release notes and migration guidance for any shipped release
• Breaking: the single-wiki LLM POC is removed; migrate to akm wiki …

Multi-wiki support

The biggest addition in 0.5.0 is a proper wiki asset type. A wiki is a structured knowledge base living at <stashDir>/wikis/<name>/ with a defined layout: schema.md describes what goes in it, index.md is auto-generated by akm index, log.md tracks change history, raw/ holds unprocessed source material, and the rest are agent-authored pages.

# Create a new wiki
akm wiki create architecture

# List all wikis
akm wiki list

# See what pages a wiki has
akm wiki pages architecture

# Search within a wiki
akm wiki search architecture "deployment"

# Lint a wiki for structural problems
akm wiki lint architecture

# Ingest raw content into raw/
akm wiki stash architecture ./notes/adr-001.md

# Print the ingest workflow for the wiki
akm wiki ingest architecture

Wiki pages are indexed by akm index and show up in stash-wide akm search, so you do not need to remember which wiki a page lives in. Raw sources under raw/ plus the wiki root infrastructure files schema.md, index.md, and log.md are intentionally excluded from indexing and search results. Running akm index also regenerates each wiki's index.md as a side effect.

The design principle is akm surfaces, the agent writes. akm makes no LLM calls. It owns only the operations where correctness is structural and deterministic: lifecycle management, raw-slug uniqueness, lint checks, index regeneration. The agent owns page content. This keeps the CLI fast and predictable — a wiki command always completes in milliseconds, and you can run it in any environment without model configuration.

The 10-verb surface (create, register, list, show, remove, pages, search, stash, lint, ingest) covers the full lifecycle from creation to indexing to removal.

If you already have a wiki-shaped directory or repo you want to adopt without copying it, use akm wiki register:

# Register a local directory as a first-class wiki
akm wiki register notes ~/team/notes

# Or via the unified add command
akm add --type wiki --name notes ~/team/notes

# Registered external wikis show up in both `akm list` and `akm wiki list`

Registration refreshes source state and wiki search hits immediately, and the indexer normalizes external wiki refs on subsequent runs.

Workflow asset type

Workflows are multi-step procedures stored in the stash. An agent running a complex process — a release checklist, an onboarding sequence, a debugging runbook — can use akm workflow next to step through it deterministically rather than relying on its context window to track state.

# Author a workflow
akm workflow create release-checklist

# Start an instance
akm workflow start workflow:release-checklist

# Advance to the next step
akm workflow next workflow:release-checklist

# Check where you are
akm workflow status workflow:release-checklist

# Mark a specific step done (defaults to --state completed)
akm workflow complete <run-id> --step validate --notes "Inputs verified"

# List all workflow runs
akm workflow list

# Print a starter workflow you can adapt
akm workflow template

Workflows live in the stash like any other asset, so akm search workflow:… finds them and akm show workflow:release-checklist renders the current step. They can be shared in a stash and versioned in a git stash.

Vault asset type

Vaults store secrets and environment configuration. Each vault is a .env file in the stash. The key constraint: vault values never appear in structured output. akm show vault:<name> and akm vault list display key names and metadata, but not the values themselves.

# List vaults
akm vault list

# Show keys in a vault (no values)
akm show vault:prod-secrets

# Create a new empty vault
akm vault create prod-secrets

# Set a key (three-positional form or combined KEY=VALUE form)
akm vault set vault:prod-secrets API_KEY abc123
akm vault set vault:prod-secrets API_KEY=abc123 --comment "Rotate every 90 days"

# Remove a key
akm vault unset vault:prod-secrets API_KEY

# Print the vault file path for current-shell loading
source "$(akm vault path vault:prod-secrets)"

# Run one command with the vault injected
akm vault run vault:prod-secrets -- env

akm vault path is the current-shell loading path and akm vault run is the one-shot command execution path. Values never appear in structured output; vault run passes them directly to the child process environment.

This is a deliberate tradeoff: vaults are not a full secrets manager. They are a thin, auditable layer that keeps your .env files alongside your other agent assets and prevents accidental leakage through akm show or akm search results.

Writable git stash and akm save

Until now, git-backed stashes were read-only: akm add github:owner/repo would clone the repo, but you could not push changes back. 0.5.0 changes that.

# Clone a git stash and opt it into push-on-save
akm add github:your-org/your-stash --writable

# Make some changes — add a skill, author a wiki page, record a memory
akm remember "Production DB is read-only on Sundays"

# Commit and push
akm save -m "add production DB note"

If the stash has a remote configured and --writable was used on install, akm save runs git commit and git push. Without --writable (or without a remote), it commits locally only.

The default stash is now auto-initialized as a git repo on akm setup, so akm save works out of the box even before you wire up a remote.

The git stash provider also switches from HTTP tarball download to git clone, which means you get proper git history and the ability to git pull manually if you prefer.

--trust flag for installs

akm 0.4.0 added a pre-install audit that scans stash contents for dangerous patterns. By default, installs from unrecognized sources require confirmation. For sources you know and trust, you can skip the audit entirely:

akm add github:your-org/internal-stash --trust

--trust is a one-off bypass — it does not add the source to any persistent allowlist. Use it when you control the source and do not want to step through the audit prompt in a non-interactive context (a CI script, an automated agent workflow, a container build).

When a blocked install error occurs, the error message includes a hint field referencing --trust as a remediation option.

Breaking change: single-wiki LLM POC removed

If you were using the wiki functionality introduced in 0.4.1, you will need to migrate. The following have been removed:

• akm lint command
• akm import --llm and akm import --dry-run flags
• knowledge.pageKinds config key
• The ingestKnowledgeSource and lintKnowledge LLM prompts

Migration path:

1. Create a wiki for your content: akm wiki create <name>
2. Move raw source files into wikis/<name>/raw/: akm wiki stash <name> <file>
3. Have your agent author wiki pages from the raw content
4. Run akm index to regenerate the wiki index

The new surface is more capable — 10 verbs vs the old 2, proper multi-wiki support, structural lint, and page search — and it does not require an LLM to be configured for any of the CLI operations.

Broader akm upgrade coverage

akm upgrade used to assume a standalone-binary install. 0.5.0 detects how akm was installed (npm, bun, pnpm, or binary) and runs the right self-update path for each. The same command now works whether you bootstrapped from the install script or from a package manager, and the internal runtime-asset coverage was expanded so newly shipped asset types stay up to date after an upgrade.

akm upgrade              # Works for binary, npm, bun, and pnpm installs
akm upgrade --check      # Report whether an update is available, without installing

akm help migrate <version> — release notes at the CLI

Release notes belong where you're actually working. akm help migrate prints the relevant CHANGELOG section plus embedded migration guidance for a given version, so you can review what changed (and what to do about it) without leaving the terminal.

akm help migrate 0.5.0     # or v0.5.0
akm help migrate latest    # resolve against the most recent CHANGELOG entry

It favors the bundled CHANGELOG section when it exists and falls back to an embedded summary and a link to the full changelog otherwise.

Upgrade

akm upgrade

Or reinstall from scratch:

curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash

Full changelog at CHANGELOG.md.

Note (2026-04-23): This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a kit and the Kit Maker's Guide; those terms have been renamed to stash and Stash Maker's Guide throughout. The pre-rename text is preserved in this repository's git history.