akm-cli 0.9.30 → 0.9.32

package/docs/posts/proposal-safety-net-15.md

@@ -0,0 +1,112 @@
+---
+title: The Proposal Queue Safety Net
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: 'akm''s proposal queue separates agent-generated suggestions from your live stash. Here is the full review workflow, the 0.8.0 guardrails that prevent bulk mistakes, and a daily habit that keeps the queue clean.'
+tags:
+  - ai
+  - agents
+  - memory
+  - cli
+published: true
+id: 3814548
+date: '2026-06-04T00:32:02Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+This is part fifteen in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. [Part ten](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d) introduced the improve pipeline and how it generates proposals. [Part twelve](https://dev.to/itlackey/belief-aware-memory-teaching-your-agent-when-not-to-write-4egi) covered belief-aware memory, which feeds directly into the confidence scores covered here.
+
+The fundamental problem with agent-generated stash updates is trust. You want to capture what the agent learned — the debugging insight from last Tuesday's session, the architectural pattern it derived from reviewing twenty PRs — without blindly writing unreviewed content into the knowledge base your other agents depend on. One bad promotion and you've contaminated search results with a hallucinated fact that will keep showing up until someone notices.
+
+akm's proposal queue is the answer to that problem. Introduced in 0.7.0 and extended in 0.8.0, it separates generation from promotion. Every agent-driven change writes to a durable queue first. Nothing reaches your live stash until you explicitly accept it. The queue is the safety net.
+
+## How the Queue Works
+
+When `akm improve` or `akm proposal new` runs, the output goes to the proposal queue — not to your stash. Proposals live outside the asset tree. They never appear in `akm search` results and never get indexed alongside your real assets. The `quality: "proposed"` marker ensures this at the database level: proposed assets are excluded from default search and only surface through the `akm proposal *` commands or an explicit `--include-proposed` flag.
+
+This means an agent can generate dozens of proposals in a single `akm improve` run and none of them affect your live stash until you decide they should. Multiple proposals for the same ref coexist without filesystem collisions. You can review them at your own pace, reject the bad ones, and accept the rest in whatever order makes sense.
+
+The complete review workflow:
+
+```sh
+akm proposal list                        # see what's pending
+akm proposal show <id>                   # render the full proposal content
+akm proposal diff <id>                   # diff vs. the live version of that ref
+akm proposal accept <id>                 # validate, then promote to stash
+akm proposal reject <id> --reason "…"   # archive with a reason
+```
+
+`akm proposal accept` does not just write the file. It runs full validation and routes the write through the same `writeAssetToSource()` path used by `akm remember` and `akm import`. There is no bypass path. A proposal that fails validation does not get promoted.
+
+## The 0.8.0 Additions
+
+0.8.0 reorganized the proposal commands under the `akm proposal` subcommand (the old flat verbs — `akm proposals`, `akm accept`, `akm reject`, etc. — still work as deprecated aliases until 0.9.0) and added three features that change how you interact with the queue at scale: confidence scores, expiration, and per-proposal revert.
+
+**Confidence scores.** Each proposal now carries an optional `confidence` field (a value from 0 to 1) set by the pipeline that generated it. `akm proposal show <id>` includes this field in its JSON output. A high-confidence proposal is one the pipeline assessed as a strong, well-supported improvement. A low-confidence one is speculative or weakly supported. The score is not a gate — you still decide — but it gives you signal for triage. When you have thirty proposals and limited review time, work high-confidence proposals first. (The belief model that drives these scores is covered in [Belief-Aware Memory](https://dev.to/itlackey/belief-aware-memory-teaching-your-agent-when-not-to-write-4egi).)
+
+**Expiration.** Proposals expire after a configurable number of days. Set `improve.archiveRetentionDays` in your akm config to control the window (default: 30 days). Stale proposals that you never got around to reviewing are automatically archived rather than accumulating indefinitely. Anything that mattered enough to act on should have been reviewed before it aged out; the archive preserves the full audit trail if you need to look back.
+
+**Per-proposal revert.** After you accept a proposal, `akm proposal revert <id>` restores the backup of the previous version. This is not a bulk operation and it is not reversible in batch. You revert one proposal at a time, by ID:
+
+```sh
+akm proposal revert <id>    # restore the backup for a specific accepted proposal
+```
+
+The no-batch-revert constraint is intentional. Bulk accept without bulk revert is the guardrail that forces deliberate review. If you accept fifty proposals in a single command and three of them are bad, you revert those three individually. The discipline is the point — if you were going to bulk-revert, it means you bulk-accepted without reviewing, and the queue exists precisely to prevent that pattern.
+
+## Bulk Accept Guardrails
+
+For cases where you want to process more than one proposal at a time without bypassing judgment entirely, 0.8.0 extended `akm proposal accept` with generator-scoped batch flags.
+
+**`akm proposal accept`** supports generator-scoped bulk operations. When you want to accept all pending proposals from a specific generator, pass `--generator` without a positional id. Bulk accept requires `-y`/`--yes`:
+
+```sh
+akm proposal accept --generator reflect --yes        # accept all reflect proposals
+akm proposal accept --generator distill --yes        # accept all distill proposals
+```
+
+The `--yes` flag removes the interactive confirmation prompt required in non-interactive shells. Use it only after you have already reviewed the queue via `akm proposal list` and `akm proposal diff`. Bulk accept without prior review is exactly the pattern the queue exists to prevent.
+
+## Auto-Accept for Trusted Sources
+
+If you have a source you fully trust — a well-constrained task asset running against a curated input set, or a distill job that only ever touches a specific category — you can set a high `autoAccept` threshold in that improve profile. Proposals whose confidence meets or exceeds the threshold are promoted directly to the stash without manual review.
+
+This is off by default and should stay off for most sources. The value of the queue is exactly that it sits between agent output and your live stash. Auto-accept makes sense only when the source is trusted, the scope is narrow, and you are comfortable with the output quality from experience rather than assumption.
+
+## A Daily Review Habit
+
+The proposal queue only helps if you actually review it. Left unattended, it either accumulates into a backlog that's too large to meaningfully triage, or proposals expire before you get to them. A brief daily review pass keeps it manageable.
+
+The workflow that works:
+
+```sh
+# Start with the full pending list
+akm proposal list
+
+# For each proposal worth reading, diff it against the live ref
+akm proposal diff <id>
+
+# Accept the ones that look right
+akm proposal accept <id>
+
+# Reject the ones that don't, with a reason you'll understand later
+akm proposal reject <id> --reason "hallucinated — no source for this claim"
+```
+
+The diff is the most useful step. `akm proposal diff <id>` shows you the delta between the proposal and whatever currently exists for that ref in your live stash. A proposal that adds accurate new context to a ref you already maintain is easy to accept. A proposal that rewrites a ref you know well with confident-sounding but unverifiable claims is easy to reject. The diff makes the difference visible.
+
+If the queue is empty, the daily review takes thirty seconds. If `akm improve` ran overnight and produced twenty proposals, budget ten minutes. The point is not to process every proposal — it is to stay close enough to the queue that nothing accumulates into a block of work large enough to skip.
+
+For teams running `akm improve` on a schedule, the confidence scores make triage faster. High-confidence proposals need a quick diff and a decision. Low-confidence proposals need closer reading or an outright reject. Over time, the pattern of what the pipeline marks as high-confidence and what actually turns out to be good teaches you where to focus attention.
+
+## The Shape of Safe Agent Memory
+
+The proposal queue is not a bureaucratic checkpoint. It is the mechanism that makes it safe to run `akm improve` continuously, trust agent-driven reflection passes, and still maintain a knowledge base where you know what is in it and why.
+
+Without the queue, you are choosing between running the improve pipeline (accepting everything it produces) or not running it (getting nothing it produces). The queue is the third option: run it continuously, review the output deliberately, promote what earned it. The 0.8.0 guardrails — confidence scores, expiration, per-proposal revert, and generator-scoped bulk accept — are the tools that make that third option practical at the scale continuous operation produces.
+
+---
+
+The proposal queue is available as of akm 0.7.0. The 0.8.0 additions — confidence scores, expiration, `akm proposal revert`, and generator-scoped bulk accept — require 0.8.0 or later. Full reference at [CLI reference](../reference/cli.md#proposal) and the [configuration reference](../reference/configuration.md).

package/docs/posts/release-0.5.0.md

@@ -0,0 +1,247 @@
+---
+title: 'akm 0.5.0: Wikis, Workflows, Vaults, and a Writable Stash'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-releases
+description: 'akm 0.5.0 ships multi-wiki support, workflow and vault asset types, writable git stash sync, and a one-off --trust install bypass.'
+tags:
+  - ai
+  - agents
+  - cli
+  - release
+published: true
+date: '2026-04-24T05:18:44Z'
+id: 3539588
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+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.
+
+```sh
+# Create a new wiki
+akm wiki create architecture  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+
+# List all wikis
+akm wiki list  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+
+# See what pages a wiki has
+akm wiki pages architecture  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+
+# Search within a wiki
+akm wiki search architecture "deployment"  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+
+# Lint a wiki for structural problems
+akm wiki lint architecture  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+
+# Ingest raw content into raw/
+akm wiki stash architecture ./notes/adr-001.md  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+
+# Print the ingest workflow for the wiki
+akm wiki ingest architecture  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+```
+
+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`:
+
+```sh
+# Register a local directory as a first-class wiki
+akm wiki register notes ~/team/notes  # doclint:ignore (historical — akm 0.5.0 release announcement; `wiki` family removed in 0.9.0)
+
+# Or via the unified add command
+akm add --type wiki --name notes ~/team/notes  # doclint:ignore (historical — akm 0.5.0 release announcement; `--type` removed from `add` in the 0.9.0 bundle-adapter refactor)
+
+# 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.
+
+```sh
+# Author a workflow
+akm workflow create release-checklist
+
+# Start an instance
+akm workflow start workflow:release-checklist # doclint:ignore (historical 0.5.0 workflow lifecycle removed in 0.9)
+
+# Advance to the next step
+akm workflow next workflow:release-checklist # doclint:ignore (historical 0.5.0 workflow lifecycle removed in 0.9)
+
+# 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" # doclint:ignore (historical 0.5.0 workflow lifecycle removed in 0.9)
+
+# List all workflow runs
+akm workflow list
+
+# Print a starter workflow you can adapt
+akm workflow template  # doclint:ignore (historical — akm 0.5.0 release announcement; `template` folded into `workflow create --print` in the 0.9.0 CLI overhaul)
+```
+
+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.
+
+```sh
+# List vaults
+akm vault list  # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
+
+# Show keys in a vault (no values)
+akm show vault:prod-secrets
+
+# Create a new empty vault
+akm vault create prod-secrets  # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
+
+# Set a key (three-positional form or combined KEY=VALUE form)
+akm vault set vault:prod-secrets API_KEY abc123  # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
+akm vault set vault:prod-secrets API_KEY=abc123 --comment "Rotate every 90 days"  # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
+
+# Remove a key
+akm vault unset vault:prod-secrets API_KEY  # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
+
+# 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  # doclint:ignore (historical — akm 0.5.0 release announcement; `vault` type removed in 0.9.0, see `env`/`secret`)
+```
+
+`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.
+
+```sh
+# Clone a git stash and opt it into push-on-save
+akm add github:your-org/your-stash --writable  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# 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"  # doclint:ignore (historical — akm 0.5.0 release announcement; `save` renamed `sync` in 0.9.0, `-m` survives as `sync`'s own alias)
+```
+
+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:
+
+```sh
+akm add github:your-org/internal-stash --trust  # doclint:ignore (historical — akm 0.5.0 release announcement; `--trust` no longer a flag on current `add`)
+```
+
+`--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.
+
+```sh
+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.
+
+```sh
+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
+
+```sh
+akm upgrade
+```
+
+Or reinstall from scratch:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
+```
+
+Full changelog at [CHANGELOG.md](https://github.com/itlackey/akm/blob/main/.github/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.

package/docs/posts/release-0.6.0.md

@@ -0,0 +1,117 @@
+---
+title: 'akm 0.6.0: Clean Break to Stash, Quieter CLI, Easier Migration'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-releases
+description: 'akm 0.6.0 simplifies stash terminology, lockfile naming, and wire format before v1.'
+tags:
+  - ai
+  - agents
+  - cli
+  - release
+published: true
+id: 3611982
+date: '2026-05-05T02:19:46Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+akm 0.6.0 is out. This one is deliberately boring: a stabilization release that takes a clean break from pre-v1 terminology so the surface area we carry into v1 is honest. The domain model now has one noun for "a source of content" (stash) and one noun for "a service that helps discover them" (registry). The parallel vocabulary that accreted during earlier experiments — "kit", "source", hand-special-cased provider types — is gone. A handful of additive quality-of-life improvements ship alongside, but the headline story is fewer concepts, not more.
+
+If you are on 0.5.x, read [the v0.5 → v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) before upgrading. Most projects will work without edits thanks to automatic on-disk migrations; a small number of config fields and CLI flags need explicit updates.
+
+## TL;DR
+
+- **One domain noun**: `kits` / `sources` → `stash` everywhere. Wire format, config, CLI help, and docs all use the same word.
+- **Schema v3** for the registry index: `stashes[]` replaces `kits[]`. Pre-0.6.0 indexes are no longer read.
+- **`akm.lock`** replaces `stash.lock`; auto-copied on first run, no action needed.
+- **`stashInheritance: "merge" | "replace"`** replaces the boolean `disableGlobalStashes`.
+- **`primary: true`** on a stash entry replaces the top-level `stashDir` field.
+- **`--detail=agent`** is the preferred spelling; `--for-agent` stays as a deprecated alias.
+- **`akm enable context-hub` / `akm disable context-hub`** are gone — add context-hub as a regular git stash.
+- **Discovery**: registry indexes only packages/repos tagged `akm-stash`. The pre-0.6.0 `akm-kit` / `agentikit` keywords/topics are not honored as fallbacks.
+
+Full details — including before/after code for every item — live in the migration guide.
+
+---
+
+## What "clean break" means
+
+This is a simplification, not a rebrand. Through the pre-v1 releases, akm accumulated three overlapping nouns for the same concept:
+
+- "source" — the config field users saw
+- "kit" — the packaging / publishing story
+- "stash" — the runtime/storage layer
+
+Three words for one thing made every doc page ambiguous and every new feature pick a side. 0.6.0 collapses the three into **stash** at every layer — config, wire format, CLI text, docs, error messages. "Agent Kit Manager" stays as the project tagline and `akm-cli` stays as the package name, because those are *product* names, not data-model terms. Everything below the product surface is stash.
+
+The registry wire format follows the same logic. Schema v3 drops `kits[]` and parses only `stashes[]`. Pre-v1 is the right time to do this: there is no installed base we need to keep parsing legacy wire formats for, and holding onto `kits[]` just to be polite would trap the v1 contract in historical cruft.
+
+## Breaking changes at a glance
+
+Each bullet below links to its section in the migration guide, which has the exact before/after code or config diff.
+
+- [`stash.lock` → `akm.lock`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#1-stashlock--akmlock) — auto-copied on first run.
+- [`installed[]` → `stashes[]` + `akm.lock`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#2-installed--stashes--akmlock) — config cleanup happens on next write.
+- [`stashDir` → `primary: true`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#3-stashdir--primary-true) — automatic.
+- [`disableGlobalStashes` → `stashInheritance`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#1-replace-disableglobalstashes) — **manual**, one-line config edit.
+- [`--for-agent` → `--detail=agent`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#2-replace---for-agent-with---detailagent) — old flag still works as a deprecated alias for one release cycle.
+- [`akm enable/disable context-hub` removed](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#3-replace-akm-enable-context-hub--akm-disable-context-hub) — add it as a regular git stash.
+- [Wire format `kits[]` → `stashes[]`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#wire-format-change-kits--stashes) — registry publishers must regenerate.
+- [Discovery keyword / topic `akm-kit` → `akm-stash`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#publisher--kit-maker-changes) — publishers must re-tag.
+
+If you consume only the public registry and do not maintain your own, the publisher changes do not apply to you.
+
+## What's new (low-key)
+
+A few additive improvements rode along with the cleanup.
+
+- **`akm workflow validate <ref|path>`** — new subcommand for validating a workflow markdown file or ref; lists every error in one pass (without running a full reindex). A workflow debugging tool to surface issues before they bite at run time.
+- **Memory frontmatter on `akm remember`** — `--tag` (repeatable), `--expires 30d`, `--source <any-string>`, plus opt-in `--auto` (heuristics) and `--enrich` (LLM) for deriving tags from the body. Zero-flag `akm remember "body"` still writes a flat memory, so existing agent scripts are unchanged. Issue [#169](https://github.com/itlackey/akm/issues/169).
+
+  ```sh
+  akm remember "VPN required for staging deploys" \
+    --tag ops --tag networking --expires 90d --source "skill:deploy"
+  ```
+
+- **Workflow parser accepts intro prose** — you can now put a short advisory paragraph between `# Workflow:` and the first `## Step:` without tripping a validation error. Issue [#158](https://github.com/itlackey/akm/issues/158).
+- **Workflow resume reclassifies blocked steps** — `akm workflow resume <id>` now re-opens the currently-blocked step so you can mark it `completed`, `failed`, or `skipped` after resolving the blocker. Issue [#156](https://github.com/itlackey/akm/issues/156).
+- **Workflow create works in clean stashes** — `akm workflow create <name>` (and `--from <file>`) no longer false-positive on a path escape when any ancestor of the stash is a symlink. Issue [#157](https://github.com/itlackey/akm/issues/157).
+- **Registry search drops empty hit objects** — providers returning partial records no longer surface as `{}` in JSON output; dropped counts appear in `warnings` so the upstream bug stays visible. Issue [#159](https://github.com/itlackey/akm/issues/159).
+- **Isolated sandbox recipe** — [Getting Started](../guides/getting-started.md#isolated-sandbox-workflow) now includes the one-terminal recipe for a throwaway `HOME` + `XDG_*` + `AKM_STASH_DIR` sandbox. Handy for agent testing, CI, and issue reproduction. Issue [#160](https://github.com/itlackey/akm/issues/160).
+
+None of these require migration action; they are upgrades-by-default once you install 0.6.0.
+
+## Migration
+
+Install:
+
+```sh
+npm install -g akm-cli@0.6.0
+# or
+bun install -g akm-cli@0.6.0
+# or from an existing install
+akm upgrade
+```
+
+Read:
+
+- [v0.5 → v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) — every breaking change with before/after code; publisher checklist if you maintain a registry or an npm/GitHub stash.
+
+Verify:
+
+```sh
+akm info --format text            # version 0.6.x, no context-hub provider
+akm config list                   # stashes[] populated, no installed[]
+akm list                          # your sources resolve cleanly  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+If something looks wrong after upgrade, the guide has a [troubleshooting section](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#troubleshooting) covering the common pitfalls (stale context-hub entries, v2 registry URLs, empty `stashes[]` after a read-only upgrade path).
+
+## What's next
+
+0.6.0 is a punctuation mark, not a destination. The next moves are narrower scope and fewer concepts, in that order. Expect the 0.6.x series to pick up whatever friction falls out of this rename; 0.7 starts shaping the contract we intend to freeze at v1.
+
+Thank you to everyone who stayed on pre-v1 through the terminology churn. The point of doing this now — while the installed base is small enough to move together — is that we only do it once. The v1 surface begins here.
+
+Full changelog at [CHANGELOG.md](https://github.com/itlackey/akm/blob/main/.github/CHANGELOG.md).

package/docs/posts/release-0.7.0.md

@@ -0,0 +1,159 @@
+---
+title: 'akm 0.7.0: Proposal Queue, Reflection Commands, Lessons, and akm-bench'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-releases
+description: 'akm 0.7.0 adds the proposal queue, reflection commands, lessons, and akm-bench.'
+tags:
+  - ai
+  - agents
+  - cli
+  - release
+published: true
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+akm 0.7.0 is out. This is the last pre-1.0 ship in the v1 cycle. The headline features are a durable proposal queue that routes all agent-suggested changes through a single reviewable path, three new CLI surfaces (`reflect`, `propose`, `distill`) that write into that queue, a `lesson` asset type for synthesized knowledge, per-call-site LLM feature gates that are all off by default, and a paired-run benchmarking framework (`akm-bench`) for measuring whether your stash actually improves agent outcomes. A batch of security, UX, and hygiene hardening rounds out the release.
+
+If you are on 0.6.x, the v1 migration guide covers the per-surface delta. The upgrade is opt-in — everything new requires explicit configuration or a new command invocation.
+
+## TL;DR
+
+- **Proposal queue** (`akm proposal list/show/diff/accept/reject`) — all agent-generated changes flow through a durable queue before touching your stash.
+- **`akm reflect`, `akm propose`, `akm distill`** — three new commands that produce proposals without mutating live stash content.
+- **`lesson` asset type** — first-class synthesized knowledge, produced by `akm distill` and promoted via `akm proposal accept`.
+- **`llm.features.*` map** — seven opt-in gates (all `false` by default) for bounded in-tree LLM call sites.
+- **`quality: "proposed"`** — proposed assets are excluded from default search; surface them via `--include-proposed` or `akm proposal *`.
+- **`akm-bench` v1** — paired noakm/akm runs, per-ref attribution, delta reporting.
+- **Security hardening** — git message sanitization, bench env isolation, LLM body redaction, npm tarball host validation.
+
+---
+
+## Proposal queue (`akm proposal *`)
+
+The fundamental problem with agent-generated suggestions is trust: you want to capture what the agent learned without blindly writing unreviewed content into your stash. The proposal queue solves this by separating generation from promotion.
+
+All proposal-producing commands write to a durable queue that lives outside the asset tree. Unaccepted drafts never appear in search results or get committed. When you're ready to accept a proposal, `akm proposal accept` runs full validation and then routes the write through the same `writeAssetToSource()` path used by `akm remember` and `akm import` — no special handling, no bypass.
+
+```sh
+akm proposal list                       # list pending proposals
+akm proposal show <id>                  # render one proposal
+akm proposal diff <id>                  # diff vs. the live ref
+akm proposal accept <id>                # validate, then promote to stash
+akm proposal reject <id> --reason "…"  # archive with reason
+```
+
+Multiple proposals for the same ref coexist without filesystem collisions. Auto-accept can be enabled per-source via `autoAcceptProposals: true` in your stash config (requires a writable source, defaults off).
+
+## Three new commands: `reflect`, `propose`, `distill`
+
+These three commands are the primary way to generate proposals.
+
+```sh
+akm reflect [ref] [--task ...]        # reflect on an asset and propose improvements — doclint:ignore (historical — akm 0.7.0 release announcement; folded into `akm improve` later)
+akm propose <type> <name> --task "…"  # generate a new asset as a proposal — doclint:ignore (historical — akm 0.7.0 release announcement; moved to `akm proposal new` in 0.9.0)
+akm distill <ref>                     # synthesize a lesson from an asset — doclint:ignore (historical — akm 0.7.0 release announcement; folded into `akm improve` later)
+```
+
+`reflect` and `propose` shell out to your configured agent CLI and write only to the proposal queue — they never mutate live stash content. `distill` is a bounded in-tree LLM call, gated behind `llm.features.feedback_distillation`, that produces a `lesson`-type proposal from an existing asset.
+
+All three emit usage events so you can track which workflows you're actually using.
+
+## `lesson` asset type
+
+`lesson` is a new first-class asset type designed for synthesized knowledge — the kind your agent derives from experience rather than imports from a source. Lessons are stored under `lessons/<name>.md` in your working stash, parallel to `memories/`. Required frontmatter: `description` and `when_to_use`.
+
+The canonical workflow: `akm distill <ref>` produces a lesson proposal → `akm proposal list` shows it → `akm proposal accept <id>` promotes it to your stash. Direct authoring via `akm import` or `akm remember`-style flows is also supported if you want to write lessons manually.
+
+## `llm.features.*` — opt-in LLM gates
+
+Every bounded in-tree LLM call site is now gated behind exactly one feature flag. All defaults are `false`, so enabling the schema has no effect until you opt in. Seven flags ship in 0.7.0:
+
+| Key | What it enables |
+| --- | --- |
+| `curate_rerank` | LLM rerank in `akm curate` |
+| `tag_dedup` | LLM tag dedup during indexer enrichment |
+| `memory_consolidation` | `akm remember --enrich` consolidation |
+| `feedback_distillation` | `akm distill <ref>` |
+| `embedding_fallback_score` | Scorer fallback when embeddings unavailable |
+| `memory_inference` | Indexer split of pending memories into atomic facts |
+| `graph_extraction` | Indexer entity/relation extraction → SQLite graph tables |
+
+Turn on what you want:
+
+```sh
+akm config set llm.features.feedback_distillation true
+akm config set llm.features.memory_consolidation true
+```
+
+Every gated call site uses the `tryLlmFeature()` wrapper from `src/llm/feature-gate.ts`, which guarantees: disabled → fallback returned without ever calling the LLM; throw → error swallowed, fallback returned; timeout → 30-second hard limit, fallback returned.
+
+## `quality: "proposed"` and `--include-proposed`
+
+`SearchHit.quality` now has three well-known values: `"generated"`, `"curated"`, and `"proposed"`. The first two appear in default search. Proposed assets are **excluded by default** — they only surface via `akm search ... --include-proposed` or via the `akm proposal *` commands. Unknown quality values parse-warn-include so plugin authors can extend the set without breaking the indexer.
+
+## `akm-bench` v1
+
+Bench grows from a smoke test into a paired-utility framework:
+
+- **Track A — paired noakm/akm runs.** For each task, bench runs your agent CLI twice (without and with akm available), captures per-tool-call utility, and emits a comparable score pair.
+- **Track B — registry attribution.** Utility deltas are mapped back to specific `[origin//]type:name` refs so you can see which assets in your stash actually contributed to the improvement.
+- **`akm-bench compare`** — aggregates paired runs into a delta report.
+- **`akm-bench attribute`** — surfaces the per-ref attribution report.
+
+```sh
+akm-bench compare results/noakm results/akm
+akm-bench attribute results/akm
+```
+
+The technical reference for `akm-bench` now lives in the standalone [itlackey/akm-bench](https://github.com/itlackey/akm-bench) repo.
+
+## Security hardening (PR #275)
+
+Five security, UX, and hygiene issues landed together in the pre-prod hardening batch:
+
+**Security:**
+- **#270 — git message sanitization.** Commit messages and remote URLs written by akm are sanitized to prevent shell-substitution and control-character injection through user-supplied content.
+- **#271 — bench env isolation.** Each agent invocation in `akm-bench` runs in a scrubbed environment so host secrets don't leak into bench transcripts.
+- **#272 — LLM body redact + npm tarball host validation.** Outbound LLM request/response bodies are redacted in error reporting before surfacing to stderr. `akm add npm:…` now validates the tarball download host against your configured npm registry instead of blindly following arbitrary `dist.tarball` URLs.
+
+**UX:**
+- **#273 — workflow noise gate, stashes deprecation warn, setup `--help`.** `akm workflow next/complete/status` no longer print spurious progress noise on quiet runs. Configs using the legacy `stashes[]` key now emit a single deprecation warning per process (was: per call site). `akm setup --help` renders the full help block.
+
+**Hygiene:**
+- **#274 — tsconfig + HF pin + shapes throw.** `tsconfig.json` now covers `tests/` so `bunx tsc --noEmit` catches test-file errors. The HF embeddings model is pinned to a specific revision. The output-shape registry now throws on a missing shape rather than silently falling back to `JSON.stringify`.
+- **#276 — bench tmp redirect.** `akm-bench` no longer writes scratch state under `/tmp`; everything lands under `~/.cache/akm/bench/`.
+
+## Upgrade
+
+```sh
+npm install -g akm-cli@0.7.0
+# or
+bun install -g akm-cli@0.7.0
+# or from an existing install
+akm upgrade
+```
+
+**Verify:**
+
+```sh
+akm info --format text     # version 0.7.x
+akm proposal list          # queue starts empty — that's expected
+```
+
+**Try the new surfaces:**
+
+```sh
+akm setup                                            # detects installed agent CLIs
+akm config set llm.features.feedback_distillation true
+akm distill memory:my-debugging-notes               # produces a lesson proposal — doclint:ignore (historical — akm 0.7.0 release announcement; `distill` command + ref grammar both retired later)
+akm proposal list
+akm proposal accept <id>
+```
+
+No manual migration is required for users on 0.6.x with no `agent` or `llm.features` blocks configured. Everything new is opt-in.
+
+Full historical details are in the [pre-1.0 migration plan](https://github.com/itlackey/akm/blob/b507e3d29b173b7e5d3a70cfa06265436cd94e50/docs/archive/pre-1.0-migration.md) (pinned to its last commit before the doc was retired) and the [0.7.0 release notes](https://github.com/itlackey/akm/blob/main/docs/migration/release-notes/0.7.0.md).
+
+Full changelog at [CHANGELOG.md](https://github.com/itlackey/akm/blob/main/.github/CHANGELOG.md).