akm-cli 0.8.0-rc2 → 0.8.1

package/{.github/CHANGELOG.md → CHANGELOG.md}

@@ -4,7 +4,242 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.8.1] - 2026-06-05
+
+### Added
+
+- **`graph-refresh` improve profile** — new built-in profile that runs a full-corpus
+  graph extraction pass across all stash files (all other improve processes disabled).
+  Use `akm improve --profile graph-refresh` for a weekly relationship rebuild.
+  Pairs with the new `graph-refresh-weekly` task template (`akm tasks add --template graph-refresh-weekly`).
+- **`session-extraction` health advisory** — new heuristic advisory backed by real
+  `akmExtract` outcomes: warns when the session-extraction process ran but produced
+  zero proposals across ≥ 5 sessions, or recorded warnings. Replaces the vestigial
+  `session-log-failures` warn signal.
+- **`improve.sessionExtraction` health metrics** — `sessionsScanned`, `sessionsExtracted`,
+  `sessionsSkipped`, `proposalsCreated`, `warnings`, `durationMs` now tracked and
+  visible in `akm health` reports.
+
+### Fixed
+
+- **`akm info` indexStats** — `readIndexStats` errors are now surfaced and the resolved
+  DB path is passed correctly; `entryCount`, `hasEmbeddings`, and related fields are
+  no longer silently empty (#510).
+- **Indexer timing fields** — `embedMs` and `ftsMs` in timing output had their
+  operands swapped, producing negative durations. Fixed (#516).
+- **Incremental consolidation gate** — the `volumeTriggered` path bypassed the
+  incremental gate introduced in 0.8.0, causing consolidation to run on chunks it
+  had already processed in the same run. Fixed.
+- **Improve budget exhaustion** — `improve.lock` was not released after budget
+  exhaustion, blocking subsequent runs until the lock TTL expired.
+- **Consolidation chunk retry** — failed chunks are now retried once with a 2 s
+  backoff before being recorded as lost, reducing transient LLM errors from
+  propagating to `chunksFailed`.
+- **`yieldRate` health metric** — `skippedAborted` refs were incorrectly counted in
+  `freshAttempts`, inflating the denominator and underreporting yield rate.
+- **`session-log-failures` advisory** — demoted from `warn` to always `pass`
+  (informational only); the advisory was a raw regex counter with no LLM signal,
+  producing false positives on normal session content.
+
+### Refactored
+
+- All runtime assets consolidated under `src/assets/` with `dist/assets/` mirroring
+  the layout exactly. Built-in improve profiles moved from in-source object literals
+  to embedded JSON files (`src/assets/profiles/*.json`). The `copy-assets.ts` build
+  step now uses a precise `src/assets/**/*` glob instead of a broad catch-all.
+- Vestigial Phase 0 (`getExecutionLogCandidates` / `ERROR_PATTERNS`) removed from
+  the improve pipeline. This regex scan collected a metric count but never fed an
+  LLM; `akmExtract` (Phase 0.4) is the real session extraction pipeline.
+
+## [0.8.0] - 2026-05-28
+
+### Performance
+
+- **`akm consolidate`**: all-hot chunk early-exit. When every memory in a chunk
+  is `captureMode: hot` (user-explicit), the only operations the LLM could ever
+  propose are deletes — all refused unconditionally by the downstream guard.
+  Such chunks now skip the model entirely and are counted as `judgedNoAction`
+  up front, instead of relying on a prompt-level hint and spending a wasted
+  request. Mixed chunks are unaffected.
+
+### Breaking changes (deprecation aliases, removed 0.9.0)
+
+The 0.8 line is the clean-break window for CLI ergonomics. Every rename below
+keeps the **old spelling working** as a deprecated alias that prints a stderr
+warning (never on stdout, so JSON consumers are unaffected) and delegates to the
+canonical form. **All of these deprecated aliases are removed in 0.9.0.** See
+[`docs/migration/v0.8-to-v0.9.md`](docs/migration/v0.8-to-v0.9.md) for the full
+old → new table.
+
+- **Proposal queue is now a noun group**: `akm proposal {list,show,diff,accept,reject,revert}`.
+  The flat verbs `akm proposals`, `akm show proposal <id>`, `akm accept`,
+  `akm reject`, `akm diff`, and `akm revert` are deprecated aliases.
+  Bare `akm proposal` behaves as `akm proposal list`.
+- **`--detail` is now verbosity only** (`brief|normal|full`). The output
+  *projection* moved to a new **`--shape`** flag (`human|agent|summary`).
+  `--detail summary` and `--detail agent` are deprecated aliases that map to
+  `--shape summary` / `--shape agent`.
+- **`--for-agent`** is a deprecated alias for `--shape agent`.
+- **`--generator`** replaces `--source` on `accept` / `reject` / `history`
+  (which generator produced the proposal/event). `--source` is a deprecated
+  alias on **those three commands only** — it is unchanged on
+  `search` / `curate` / `graph` / `remember`, where it means "read from here".
+- **`akm save` → `akm sync`** (commit + optional push; `sync` connotes push
+  better). `akm save` is a deprecated alias. `akm sync` adds `--no-push`.
+- **`akm enable` / `akm disable` → `akm config enable` / `akm config disable`**.
+  The top-level `enable` / `disable` are deprecated aliases.
+- **`akm events` → `akm log`**: `log` is an additive alias for the same
+  state.db stream in 0.8 and becomes primary in 0.9.0. (`akm history` remains the
+  asset-scoped, cross-source analytical trail — a different surface.)
+- **`akm wiki remove --force` → `-y` / `--yes`** for skipping the confirmation
+  prompt. `wiki remove` now also *prompts* interactively when a TTY is present;
+  `--force` is a deprecated alias for `-y`.
+- **`akm feedback --note` → `--reason`**: `--note` is a deprecated alias and
+  warns when used without `--reason`.
+- **`akm workflow next --dry-run` removed**: the flag is no longer declared, so
+  it no longer appears in `--help`. The explicit "next does not support
+  --dry-run" guard remains (read from argv) so existing callers still get a clear
+  message instead of silent acceptance.
+- **Singular aliases added** (additive, non-breaking): `akm task` for
+  `akm tasks`, `akm lesson` for `akm lessons`.
+
+### Safety
+
+Two destructive paths that previously acted with no confirmation now guard
+behind an interactive prompt (or `-y` / `--yes` in non-interactive use).
+**Scripts that ran these non-interactively must add `-y`.**
+
+- **`akm registry remove`** now confirms before splicing the registry out of the
+  config (`confirmDestructive`). Pass `-y` / `--yes` to skip the prompt;
+  non-interactive use without `-y` aborts.
+- **Bulk `akm proposal accept --generator <g>`** (the multi-proposal branch) now
+  confirms before promoting every matching proposal, mirroring the existing
+  guard on bulk `reject`. Single-id accept stays unguarded (it is revertable).
+
+### Fixed
+
+- **Consolidation `delete_failed` on stale index entries** — when consolidation
+  successfully deleted a memory file, the index DB was not re-indexed between
+  runs. Subsequent runs loaded the stale DB entry into their memory map, the LLM
+  re-proposed the deletion, and `deleteAssetFromSource` threw "not found in
+  source" — appearing as `delete_failed` in skipReasons. Fix: `loadMemoriesForSource`
+  now filters entries whose file no longer exists on disk before building chunks,
+  so phantom memories are never sent to the LLM. A secondary catch in the delete
+  handler emits `delete_already_gone` instead of `delete_failed` when the file
+  is confirmed absent.
+
+> **CI / Docker users:** the 0.8.0 storage split moved `akm.lock`, the event
+> database, and the registry cache out of `$XDG_CONFIG_HOME/akm/` into
+> `$XDG_DATA_HOME`, `$XDG_STATE_HOME`, and `$XDG_CACHE_HOME` respectively. If
+> you override any of `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_STATE_DIR`,
+> `AKM_CACHE_DIR` in CI to isolate per-job state, set **all four** (or none,
+> and rely on XDG defaults). Overriding only `AKM_CONFIG_DIR` will leave the
+> lock file / event DB pointing at the host's default `$XDG_DATA_HOME`,
+> causing lock contention and bleed between jobs.
+
+### Removed
+
+- **Install-time security audit (`security.installAudit`) and the `--trust`
+  flag**. The audit scanned incoming stash assets for risky patterns (e.g.
+  `curl ... | bash`, "ignore previous instructions") and blocked installs on
+  critical findings. In practice it produced too many false positives on
+  benign documentation strings and forced first-time users to pass `--trust`
+  or twiddle config just to install the official stash. The whole feature is
+  gone:
+  - `akm add` and `akm update` no longer scan synced content.
+  - The `--trust` flag is removed from `akm add` and `akm wiki register`.
+  - The `security.installAudit.*` config keys (`enabled`, `blockOnCritical`,
+    `registryAllowlist`, `registryWhitelist`, `blockUnlistedRegistries`,
+    `allowedFindings`) are no longer recognised; the entire `security` block
+    is removed from the config schema.
+  - The `akm config set security.installAudit.*` keys now error as unknown.
+  - `audit` fields are removed from `AddResponse.installed` and
+    `SourceInstallStatus`.
+
+### Breaking Changes
+
+- **Project-level `.akm/config.json` files are no longer merged**. The
+  multi-layer config discovery introduced in the 0.7 line was deprecated
+  in late-0.8.x with a warning; that warning is now backed by removal.
+  `loadConfig` walks cwd-ancestors only to emit a one-time deprecation
+  warning per discovered file. Move any needed settings to
+  `~/.config/akm/config.json`. `stashInheritance` (a multi-layer-only
+  field) is removed from the schema.
+
+- **`${VAR}` env-var expansion only resolves at the apiKey consumption
+  sites**. The recursive expansion walker that ran on the load path is
+  gone. Other config string values now round-trip verbatim: a literal
+  `${HOME}` in (say) `stashDir` is preserved as the literal `${HOME}`
+  on read. The new exported `resolveSecret(value)` helper is applied
+  only where authorization headers are built (`src/llm/client.ts`,
+  `src/llm/embedders/remote.ts`, `src/integrations/agent/sdk-runner.ts`).
+  Documented `${OPENAI_API_KEY}` recipes in `docs/configuration.md`
+  continue to work because expansion still happens at request time for
+  apiKey fields.
+
+- **`AKM_FORCE_DOWNGRADE_CONFIG` env var removed**. The newer-than-binary
+  read-only guard (`configReadOnlyReason`, `markConfigReadOnlyIfNewer`,
+  `getConfigReadOnlyReason`) is gone. Configs declaring a `configVersion`
+  newer than the running binary now save through silently — unknown
+  fields are stripped on save by `sanitizeConfigForWrite` plus the
+  strict-walled Zod schema. Users on 0.9.x configs should not open them
+  with a 0.8.x binary in writable workflows.
+
+### Changed
+
+- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Management** — `akm` stands for Agent Knowledge Management going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
+
+- **Config layer rewrite** — single-source-of-truth Zod schema in
+  `src/core/config-schema.ts` replaces the per-field parse switch AND
+  the per-shape load-time parser. Adding a new config field is now one
+  line of schema + zero lines of CLI code. `loadConfig` now consists of
+  parse-text → migrate (pure JSON transforms) → Zod safeParse → overlay
+  defaults — a ~30-line pipeline that absorbs ~900 LOC of legacy
+  per-shape parsers (`parseLlmConfig`, `parseEmbeddingConfig`,
+  `parseIndexConfig`, `parseSourceConfigEntry`, and ~20 more).
+  - **#454**: `akm config set llm.apiKey` / `embedding.apiKey` /
+    `profiles.llm.<name>.apiKey` now throws `UsageError` pointing at the
+    corresponding env var (`AKM_LLM_API_KEY`, `AKM_EMBED_API_KEY`,
+    `AKM_PROFILE_<NAME>_API_KEY`). Was previously a silent strip.
+  - **#455**: every schema-leaf key is now reachable via `akm config set`.
+    Includes previously hand-listed gaps: `defaults.agent`, `search.minScore`,
+    `improve.eventRetentionDays`, `embedding.provider`, `llm.temperature`,
+    `profiles.llm.<name>.*`, `profiles.agent.<name>.*`, etc.
+  - **#456**: `akm config validate` and `akm config migrate` are now real
+    registered subcommands. The orphan implementations in `config-validate.ts`
+    have been removed; the new entry points live in `src/cli/`.
+  - **#457**: project-level `.akm/config.json` files are now flagged with a
+    deprecation warning ("will be ignored in 0.9.0+"). The merge still
+    happens in 0.8.x — one release of grace.
+  - **#458**: malformed JSON or non-object root in the config file now raises
+    `ConfigError("INVALID_CONFIG_FILE")` with the underlying parse error.
+    Was previously a silent fallback to `DEFAULT_CONFIG`, which masked
+    corruption. File-not-existing remains the legitimate cold-start case.
+  - **#459**: `~/.cache/akm/config-backups/` is now bounded to the 5 most
+    recent timestamped backups. Pruning runs on each `saveConfig`.
+    `config.latest.json` is preserved separately.
+  - **#460**: `UNKNOWN_CONFIG_KEY_HINT` is now auto-generated from the
+    schema via `listTopLevelConfigKeys()`. No more stale hand-maintained string.
+  - **#461**: if the auto-migration disk-write fails, `loadConfig` now throws
+    a hard error instead of returning the in-memory migrated shape. Eliminates
+    the silent infinite re-migrate loop on every `akm` command.
+  - **#462**: nested registries[], sources[], profiles.* objects are
+    `.strict()` — unknown keys are rejected with a path-pointing error at
+    both set time and saveConfig time.
+  - **#463**: `schemas/akm-config.json` is now auto-generated from the Zod
+    source via `bun scripts/gen-config-schema.ts`. A drift test fails CI if
+    the committed file disagrees with the regeneration output.
+  - **#464.a**: `defaultWriteTarget` is validated via Zod `.refine()` against
+    `sources[].name`. With no sources configured, save-time validation
+    rejects instead of silently accepting (no implicit "first writable" fallback).
+  - **#464.b**: generic unset works on `semanticSearchMode` and every other
+    key via the dotted-path walker.
+  - **#464.c**: all write paths route through `writeFileAtomic`.
+  - **#464.d**: duplicate `mergeSecurityConfig` / `mergeInstallAuditConfig`
+    in `config-cli.ts` are deleted; merging happens via re-parse through the
+    Zod schema.
+
+See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 
 ## [0.7.5] - 2026-05-08
 
@@ -19,7 +254,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Workflow runs are now scoped to the current workspace** — ref-based workflow commands (`workflow next/status/list`) now resolve runs within the current project, worktree, or non-repo directory instead of sharing active-run state globally across the whole cache. Direct run-id commands still target the exact run.
 - **Help, hints, and workflow docs now explain run scoping** — CLI descriptions, embedded hints, operator docs, and workflow guides now describe the current-scope semantics so users understand how ref-based run resolution behaves across repos and local sandboxes.
 - **`akm show` auto-indexes stale state instead of falling back to raw filesystem reads** — show/search parity is tighter because stale index state now triggers refresh rather than silently drifting to a separate fallback path.
-- **Release metadata lookup follows the published `.github/CHANGELOG.md` layout** — migration-help, package publish metadata, and related docs now consistently reference the shipped changelog location.
+- **Release metadata lookup follows the published `CHANGELOG.md` layout** — migration-help, package publish metadata, and related docs now consistently reference the shipped changelog location at the package root.
 - **Documentation refresh across README and posts** — README positioning, command-tour docs, workflow examples, and dev.to post organization were refreshed to better match the current CLI surface.
 
 ### Fixed
@@ -80,7 +315,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
-- **Proposal queue (`akm proposal *`)** (#225, #226, #233) — durable queue for proposal-producing commands. New verbs `akm proposal {list, show, diff, accept, reject}`. Promotion runs full validation before routing through `writeAssetToSource()`. Multiple proposals for the same `ref` coexist without filesystem collisions. Auto-accept is gated per-source via `autoAcceptProposals: true` (default off; requires a writable source). See v1 spec §11.
+- **Proposal queue (`akm proposal *`)** (#225, #226, #233) — durable queue for proposal-producing commands. New verbs `akm proposal {list, show, diff, accept, reject, revert}`. Promotion runs full validation before routing through `writeAssetToSource()`. Multiple proposals for the same `ref` coexist without filesystem collisions. Auto-accept is gated per-source via `autoAcceptProposals: true` (default off; requires a writable source). See v1 spec §11.
 - **`akm reflect`, `akm propose`, `akm distill`** (#225, #226, #227) — three new commands that write **only** to the proposal queue. `reflect` and `propose` shell out via the agent CLI (`agent.*` config); `distill` is the canonical bounded in-tree LLM call gated behind `llm.features.feedback_distillation`. Usage events `reflect_invoked`, `propose_invoked`, `distill_invoked`.
 - **`lesson` asset type** (#227) — first-class well-known type with required frontmatter `description` and `when_to_use`, stored under `lessons/<name>.md`. Normally produced by `akm distill <ref>` as a `proposed`-quality proposal and promoted via `akm proposal accept`.
 - **`llm.features.*` map with mixed defaults** (#227, #284) — every bounded in-tree LLM call site is gated behind exactly one feature flag. Four keys ship: `curate_rerank`, `feedback_distillation`, `memory_inference`, `graph_extraction`. `memory_inference` and `graph_extraction` default to `true`; the others default to `false`. Wrapper `tryLlmFeature(feature, config, fn, fallback)` in `src/llm/feature-gate.ts` guarantees disabled/throw/timeout fall back without crashing the call site. See v1 spec §14.

package/README.md

@@ -1,23 +1,38 @@
-# akm -- Agent Kit Manager
+# akm -- Agent Knowledge Management
 
-> **akm** (Agent Kit Manager) -- A package manager for AI agent skills, commands, tools, and knowledge.
+> **akm** (Agent Knowledge Management) -- A package manager for AI agent skills, commands, tools, and knowledge.
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![npm downloads](https://img.shields.io/npm/dm/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![license](https://img.shields.io/github/license/itlackey/akm)](https://github.com/itlackey/akm/blob/main/LICENSE)
 
 `akm` is a package manager for AI agent capabilities -- scripts, skills, commands,
-agents, knowledge, and memories. It works with any AI coding assistant that can
-run shell commands, including [Claude Code](https://claude.ai/code),
+agents, knowledge, memories, workflows, wikis, vaults, lessons, and scheduled
+tasks. It works with any AI coding assistant that can run shell commands,
+including [Claude Code](https://claude.ai/code),
 [OpenCode](https://opencode.ai), [Cursor](https://cursor.com), and more.
 
 ## Install
 
+**Option 1 — Prebuilt binary (recommended, no runtime required):**
+
+```sh
+# Linux / macOS
+curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash
+
+# Windows (PowerShell)
+irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
+```
+
+**Option 2 — Bun (requires [Bun](https://bun.sh) >= 1.0):**
+
 ```sh
 bun install -g akm-cli
 ```
 
-Requires [Bun](https://bun.sh) runtime. Upgrade in place with `akm upgrade`.
+Upgrade in place with `akm upgrade`.
+
+> **AKM 0.8 requires the prebuilt binary or the Bun runtime. Node.js / npm / pnpm are not supported in 0.8.0** — running `npm install -g akm-cli` on a Node.js-only machine will print an error from the preinstall hook and exit without installing. Cross-runtime support (Node, npm, pnpm) is planned for 0.9.0.
 
 ## Quick Start
 
@@ -44,7 +59,8 @@ Add this to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 ## Resources & Capabilities
 
 You have access to a searchable library of scripts, skills, commands, agents,
-knowledge, and memories via the `akm` CLI. Use `akm -h` for details.
+knowledge, memories, workflows, wikis, vaults, lessons, and scheduled tasks
+via the `akm` CLI. Use `akm -h` for details.
 ```
 
 ## Install Stashes from Anywhere

package/SECURITY.md

@@ -0,0 +1,93 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made on the latest minor release line of `akm-cli`. The
+0.x line is pre-1.0 — please upgrade promptly when a fix lands.
+
+| Version | Supported |
+| --- | --- |
+| 0.8.x  | ✅ active |
+| 0.7.x  | ❌ no longer maintained |
+| < 0.7  | ❌ no longer maintained |
+
+## Reporting a vulnerability
+
+Please report security issues **privately** via GitHub Security Advisories:
+
+- https://github.com/itlackey/akm/security/advisories/new
+
+If GitHub Security Advisories is unavailable, email `itlackey@gmail.com`
+with the word `SECURITY` in the subject. Please include reproduction steps,
+the impacted akm version, and your operating environment.
+
+We will acknowledge receipt within 72 hours and aim to ship a fix or a
+mitigation guidance within two weeks, depending on severity.
+
+## Threat model
+
+`akm` is a local CLI that reads and writes user files, executes user-authored
+shell commands (via scripts, workflows, and agent dispatch), and talks to
+explicitly configured external services (LLM endpoints, git remotes, npm,
+HTTP sources). It does **not** ship telemetry, send data to anyone by
+default, or open network listeners. See
+[`docs/data-and-telemetry.md`](docs/data-and-telemetry.md) for the on-disk
+inventory.
+
+Several akm surfaces execute user-controlled code or data with the full
+permissions of the akm process. These are documented design decisions, not
+bugs, but you should be aware of them:
+
+### Workflows execute shell commands with full environment access
+
+Workflow steps run in your shell with your PATH and your environment
+variables — including any secrets you have exported or loaded via
+`akm vault load`. **Only add workflow sources you trust.** See
+[`docs/features/workflows.md` — "Security: workflow sources are executed
+code"](docs/features/workflows.md#security-workflow-sources-are-executed-code)
+for the full discussion.
+
+### Scripts execute shell commands
+
+`akm show script:<name>` returns a `run:` command line the user (or an
+integrating agent) then executes. The same trust model applies: scripts you
+install from third-party stashes are third-party code.
+
+### Agents and commands embed user-authored prompts
+
+`akm show agent:<name>` and `akm show command:<name>` return prompt
+templates and system prompts that an LLM will execute. A malicious stash
+maintainer could write a system prompt that instructs the LLM to read
+sensitive files in your working tree and exfiltrate them via the LLM
+response. Audit the prompt body the same way you'd audit a script.
+
+### Vaults are plaintext on disk
+
+`akm vault` files are `0o600`-permissioned plaintext at
+`<stash>/vaults/<name>.env`. They are protected against other local users
+by filesystem permissions but not encrypted at rest. Do not commit vault
+files to source control — they are `.gitignore`d in the default stash
+layout for that reason. The `akm vault show` / `akm vault list` commands
+never echo values; `akm vault load` produces shell-eval output meant to be
+piped to `eval`, never displayed.
+
+### Improve / propose / distill send asset content to the configured LLM
+
+`akm improve`, `akm propose`, `akm distill`, `akm reflect`, and `akm
+consolidate` send asset frontmatter and body to whatever LLM endpoint is
+configured in `~/.config/akm/config.json` (under `llm.endpoint`). If you
+have configured a third-party LLM, your asset content goes to that
+third-party. Use a local model (`http://localhost:11434` via Ollama, etc.)
+for assets containing secrets or private notes.
+
+## Known non-issues
+
+- **`akm` requires Bun or the prebuilt binary** — Node.js is not supported
+  in 0.8.0 because Bun-specific APIs are used in hot paths. This is a
+  compatibility limitation, not a security risk; the prebuilt binary is a
+  Bun-compiled standalone executable.
+- **Workflows can read any file the akm process can read.** This is not a
+  bug — see "Threat model" above.
+- **`bun install -g akm-cli` runs the preinstall hook.** The hook only
+  emits an error message and exits non-zero on Node.js; it does not phone
+  home or write outside the install directory.

package/dist/assets/help/help-accept.md

@@ -0,0 +1,12 @@
+Usage:
+  akm proposal accept <id>
+
+Description:
+  Accept a proposal and promote it into the stash.
+
+  (`akm accept` is a deprecated alias for `akm proposal accept`; it warns on
+  stderr and is removed in 0.9.0.)
+
+Examples:
+  akm proposal accept proposal_123
+  akm proposal accept proposal_123 --target team-stash

package/dist/assets/help/help-improve.md

@@ -0,0 +1,81 @@
+Usage:
+  akm improve
+  akm improve <type>
+  akm improve <ref>
+
+Description:
+  Analyze existing AKM assets and generate improvement proposals.
+
+Modes:
+  akm improve
+      Improve all eligible assets in the current scope.
+
+  akm improve <type>
+      Improve all assets of a given type.
+      Example: akm improve memory
+
+  akm improve <ref>
+      Improve one specific asset.
+      Example: akm improve workflow:release-checklist
+
+What it does:
+  - reviews feedback and recent history
+  - proposes edits to existing assets
+  - distills lessons where useful
+  - promotes durable skill lessons into skill reference-doc proposals when justified
+  - cleans and consolidates memories
+  - writes results to the proposal queue
+
+Options:
+  --task <text>        Add extra guidance for this improvement pass
+  --dry-run            Show planned actions without generating proposals
+  --target <source>    Override the write target for accepted proposals
+  --auto-accept[=<value>]
+                        Confidence threshold (0-100) for auto-accepting proposals.
+                        Default when flag is absent: ON at threshold 90 (all sub-processes).
+                        --auto-accept            same as --auto-accept=90
+                        --auto-accept=<N>        integer 0-100; accept proposals at or above N
+                        --auto-accept=safe       alias for 90 (back-compat, not deprecated)
+                        --auto-accept=false      disable auto-accept for all sub-processes;
+                                                 reflect/distill proposals go to the queue and
+                                                 consolidation will prompt interactively on HTTP paths
+                        Note: until proposals carry real confidence scores, any non-`false`
+                        value behaves like the legacy "safe" mode (whole-batch auto-accept).
+  --profile <name>     Improve profile to apply. Built-ins: default, quick,
+                        thorough, memory-focus. User-defined profiles under
+                        `profiles.improve.<name>` in config are also accepted.
+                        Profiles bundle process gating, type filters, and
+                        run-level autoAccept/limit defaults. Falls back to
+                        `defaults.improve` in config, then to "default".
+                        Unknown names fall back to default with a warning.
+                        Sync behavior by profile: default and thorough enable
+                        auto-commit + push; quick and memory-focus skip sync.
+  --sync               Commit (and optionally push) the git-backed primary
+                        stash when the run finishes. Use --no-sync to disable.
+                        Default: per profile config (enabled for default and
+                        thorough, disabled for quick and memory-focus).
+  --push               Push after the end-of-run sync commit when the stash
+                        is writable and has a remote configured. Use --no-push
+                        to commit only. Default: per profile config (true when
+                        sync is enabled).
+  --consolidate-recovery <mode>
+                        Recovery mode for stale consolidate journals: abort (default) or clean
+  --require-feedback-signal
+                        Only process refs with recent feedback signal events
+  --min-retrieval-count <n>
+                        Retrieval fallback threshold when no recent feedback exists (default: 5)
+  --json-to-stdout      Emit the full JSON result on stdout (legacy behaviour).
+                        (0.8.0+: full result is recorded in the improve_runs table of
+                        state.db and stdout is empty; use --json-to-stdout for the prior
+                        behaviour, e.g. `akm improve --json-to-stdout | jq`.)
+
+Examples:
+  akm improve
+  akm improve memory
+  akm improve skill
+  akm improve skill:code-review
+  akm improve workflow:incident-response --task "reduce duplication"
+  akm improve --profile quick
+  akm improve --profile memory-focus
+  akm improve --no-sync
+  akm improve --no-push

package/dist/{commands → assets}/help/help-proposals.md

@@ -1,15 +1,18 @@
 Usage:
-  akm proposals
+  akm proposal list
 
 Description:
   List proposal queue entries.
 
+  (`akm proposals` is a deprecated alias for `akm proposal list`; it warns on
+  stderr and is removed in 0.9.0.)
+
 Options:
   --status <status>    Filter by pending, accepted, or rejected
   --type <type>        Filter by asset type
   --ref <ref>          Filter by exact asset ref
 
 Examples:
-  akm proposals
-  akm proposals --status pending
-  akm proposals --type skill
+  akm proposal list
+  akm proposal list --status pending
+  akm proposal list --type skill

package/dist/assets/help/help-reject.md

@@ -0,0 +1,11 @@
+Usage:
+  akm proposal reject <id> --reason "..."
+
+Description:
+  Reject a proposal and record the reason.
+
+  (`akm reject` is a deprecated alias for `akm proposal reject`; it warns on
+  stderr and is removed in 0.9.0.)
+
+Examples:
+  akm proposal reject proposal_123 --reason "duplicates existing workflow"