akm-opencode 0.8.0-rc.8 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # akm-opencode
 
-OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI (v0.7.0+). Registers tools that let your AI agent **search**, **show**, and **manage** stash assets — skills, commands, agents, knowledge, memories, lessons, scripts, workflows, vaults, and wikis — **operate the v0.7.0 proposal queue** and **distill lessons** through dedicated tools, plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used (skipping proposed-quality drafts), and harvest session memories so the stash improves with every session.
+OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI (v0.8.0+). Registers tools that let your AI agent **search**, **show**, and **manage** stash assets — skills, commands, agents, knowledge, memories, lessons, tasks, scripts, workflows, vaults, secrets, and wikis — **operate the v0.8.0 proposal queue** and **improve assets** through dedicated tools, plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used (skipping proposed-quality drafts), and harvest session memories so the stash improves with every session.
 
 ## Installation
 
@@ -14,28 +14,28 @@ Add to your OpenCode config (`opencode.json`):
 
 ## Tools
 
-The plugin exposes **20 high-value tools**. Long-tail verbs (`add`, `save`, `import`, `clone`, `update`, `remove`, `list`-sources, `registry-search`, `index`-reindex, `config`, `upgrade`, ad-hoc `run`, raw `agent`) are reachable via `akm_help` plus the raw `akm` CLI through the `bash` tool.
+The plugin exposes **21 high-value tools**. Long-tail verbs (`add`, `save`, `import`, `clone`, `update`, `remove`, `list`-sources, `registry-search`, `index`-reindex, `config`, `upgrade`, `tasks`, ad-hoc `run`, raw `agent`, vault writes, secret writes/run) are reachable via `akm_help` plus the raw `akm` CLI through the `bash` tool.
 
 | Tool | Description |
 |------|-------------|
 | `akm_info` | Show `akm info` output together with the installed `akm-opencode` plugin version and install location |
-| `akm_search` | Search the local stash, the registry, or both. Type filter accepts `skill`, `command`, `agent`, `knowledge`, `lesson`, `memory`, `script`, `workflow`, `vault`, `wiki`, `any`; proposed hits can be included explicitly |
+| `akm_search` | Search the local stash, the registry, or both. Type filter accepts `skill`, `command`, `agent`, `knowledge`, `lesson`, `memory`, `script`, `task`, `workflow`, `vault`, `secret`, `wiki`, `any`; proposed hits can be included explicitly |
 | `akm_show` | Show a stash asset by its ref |
 | `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_remember` | Record a memory in the default stash |
-| `akm_feedback` | Record positive or negative feedback for a stash asset (skipped automatically for `memory:`, `vault:`, `lesson:`, and proposed-quality refs) |
+| `akm_feedback` | Record positive or negative feedback for a stash asset (skipped automatically for `memory:`, `vault:`, `secret:`, `lesson:`, and proposed-quality refs) |
 | `akm_curate` | Curate the stash for a task or topic and return ranked matches the agent can use |
 | `akm_evolve` | Dispatch the AKM curator subagent into a child session, capture the report as a memory, and seed the curator-context cache so it survives compaction |
 | `akm_parent_messages` | Summarize the parent OpenCode session so dispatched stash subagents can inherit upstream context |
 | `akm_session_messages` | Summarize a specific OpenCode session (arbitrary IDs restricted to `akm-curator`) |
-| `akm_vault` | Vault `list` / `show` (key names) / `create` / `set` / `unset` / `load` (opaque shell-eval text). **Values never surface** through `list`/`show`; `load` output is meant for `eval` and must not be displayed back |
+| `akm_vault` | Vault `list` / `show` (key names) / `load` (writes the shell snippet to a temp file path without surfacing values inline). **Values never surface** through tool output |
+| `akm_secret` | Secret `list` / `path` only. Returns refs or the absolute file path for `_FILE`-style consumers without reading contents |
 | `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`) |
-| `akm_proposal` | Operate the v0.7.0 proposal queue (`list` / `show` / `diff` / `accept` / `reject`). Always confirm with the user before `accept`/`reject` — those operations require explicit approval |
-| `akm_reflect` | Generate a reflection proposal via the configured agent CLI; output lands in the proposal queue only |
+| `akm_proposal` | Operate the v0.8.0 proposal queue (`list` / `show` / `diff` / `accept` / `reject`). Always confirm with the user before `accept`/`reject` — those operations require explicit approval |
+| `akm_improve` | Generate improvement proposals for an existing ref, a whole asset type, or the current stash scope; output lands in the proposal queue only |
 | `akm_propose` | Generate a new-asset proposal via the configured agent CLI; the result is `quality:"proposed"` until accepted |
-| `akm_distill` | Distill an AKM ref (typically `memory:*` or `knowledge:*`) into a proposed `lesson` (gated by `llm.features.feedback_distillation`) |
 | `akm_init` | Initialize AKM's working stash directory and persist `stashDir` in config. This is the agent-safe initialization path; interactive `akm setup` is human-facing |
 | `akm_help` | Discover the right `akm` CLI invocation for non-first-class verbs. Returns a curated quick-reference table plus live `akm <subcommand> --help` output |
 
@@ -43,25 +43,78 @@ The plugin exposes **20 high-value tools**. Long-tail verbs (`add`, `save`, `imp
 
 The plugin subscribes to OpenCode lifecycle events so AKM participates in the
 session loop instead of waiting to be called. Every hook is non-blocking and
-fails silently when `akm` is not on PATH — the TUI is never affected.
+fails silently when a compatible `akm` is not resolvable — the TUI is never affected.
 
 | Event | What happens |
 | --- | --- |
-| **`session.created`** (event hook) | Sets `agent.default` to `opencode` when missing, warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions start with relevant stash context. |
+| **`session.created`** (event hook) | Sets the AKM default agent in `~/.config/akm/config.json` to `opencode` when missing, warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions start with relevant stash context. |
 | **`chat.message`** | Records user feedback/memory intent and appends a short reminder to use `akm_search` / `akm_curate` when more stash context is needed. It does not auto-run AKM CLI lookups on every message. |
 | **`experimental.chat.system.transform`** | Appends cached hints, active workflow state, pending proposal summaries, the last curator report, and the current prompt's curated context to the model's system prompt. Hints and workflow state are re-injected after transcript compaction. |
-| **`tool.execute.before`** (`akm_*` tools) | Blocks destructive or sensitive operations until `confirm:true` is provided. |
-| **`permission.ask`** / **`command.execute.before`** | Detects risky raw `akm` CLI commands executed through shell/commands and denies them until the user explicitly approves the exact operation. |
+| **`tool.execute.before`** (`akm_*` tools) | Blocks destructive or sensitive operations on the plugin's own typed tools (`akm_vault show/load`, `akm_secret path`, `akm_proposal accept`, etc.) until `confirm:true` is provided. This contract is per-tool, not a generic shell-command gate. |
 | **`tool.execute.after`** (`akm_*` tools) | Logs asset usage, accumulates refs into the session buffer, records `akm feedback <ref> --positive` / `--negative` asynchronously with per-call dedupe, checkpoints memories every `AKM_MEMORY_CHECKPOINT_EVERY` successful asset-touching tool calls, and scans child-agent free text for additional refs. |
 | **`experimental.session.compacting`** | Pushes hints, curated context, active workflows, and the last curator report into the compaction prompt so they survive transcript shrinking. |
-| **`shell.env`** | Exposes `AKM_STASH_DIR`, `AKM_PROJECT`, and `AKM_PLUGIN_VERSION` to shell tools so plain `akm` calls inherit the right context. |
-| **`stop`** / **`session.idle`** / **`session.compacted`** / **`session.deleted`** | Flushes the per-session buffer into a `memory:opencode-session-YYYYMMDD-<sid>` memory so every meaningful session contributes durable context for future searches. Requires at least two observations before persisting. When `AKM_INDEX_ON_SESSION_END=1`, the hook follows a successful flush with `akm index` so upstream inference/graph passes run immediately. |
+| **`shell.env`** | Exposes `AKM_PROJECT`, `AKM_PLUGIN_VERSION`, and the resolved `AKM_STASH_DIR` to shell tools so raw shell checks and plain `akm` invocations see the same stash path as the plugin. |
+| **`stop`** / **`session.idle`** / **`session.compacted`** / **`session.deleted`** | Flushes the per-session buffer into a `memory:opencode-session-YYYYMMDD-<sid>` memory so every meaningful session contributes durable context for future searches. The persisted memory now includes compact event/candidate summaries plus explicit file paths to the full-detail plugin state and OpenCode host logs so `akm improve` can inspect deeper evidence when needed. Requires at least two observations before persisting. When `AKM_INDEX_ON_SESSION_END=1`, the hook follows a successful flush with `akm index` so upstream inference/graph passes run immediately. |
+
+### Locking down destructive commands
+
+Earlier versions of this plugin shipped `permission.ask` and
+`command.execute.before` hooks that tokenized each raw `akm` CLI invocation
+and **denied** a hard-coded list of risky subcommands (vault writes,
+`save --push`, `accept` / `reject` / `revert`, `tasks add` / `tasks run`,
+`upgrade`, `update --all`, etc.) until the user re-approved them inline.
+That gate has been removed in 0.8.0. The tokenized matcher was brittle — it
+produced false positives on commit messages, heredoc bodies, and other
+prose that happened to contain `akm <verb>` substrings — and gating
+destructive shell calls is fundamentally the host platform's job, not a
+plugin's.
+
+OpenCode does not currently expose a first-class declarative permission
+DSL equivalent to Claude Code's `permissions.ask` / `permissions.deny`.
+For the verbs that historically tripped the plugin's gate, lock things
+down at the OS level instead:
+
+- **Run `akm` under a wrapper script** that prompts (or denies) on the
+  destructive subcommands you care about. Put the wrapper earlier on
+  `PATH` than the real `akm`. For example:
+
+  ```sh
+  #!/usr/bin/env bash
+  # ~/bin/akm — wraps the real akm to confirm destructive verbs
+  case "$1 $2 $3" in
+    "vault set "*|"vault unset "*|"vault load "*|"vault create "*|\
+    "save --push"*|"sync "*|"sync"|"remove "*|\
+    "accept "*|"reject "*|"revert "*|\
+    "proposal accept "*|"proposal reject "*|"proposal revert "*|"proposal drain "*|\
+    "tasks add "*|"tasks remove "*|"tasks enable "*|"tasks disable "*|\
+    "tasks run "*|"upgrade"*|"update --all"*|"config set "*)
+      read -rp "Run 'akm $*' ? [y/N] " ans
+      [[ "$ans" == "y" || "$ans" == "Y" ]] || { echo "aborted"; exit 1; } ;;
+  esac
+  exec /usr/local/bin/akm-real "$@"
+  ```
+
+- **Use OS-level access controls** (`sudo`, `chmod`, mount restrictions,
+  AppArmor / SELinux profiles) when running OpenCode in shared or
+  sandboxed environments.
+- **Vault and secret writes still bypass the chat turn entirely.** Use the typed
+  `akm_vault` tool only for read paths (`list`, `show` of key names,
+  `load` when you need a temporary shell-file path without surfacing
+  values inline), and the typed `akm_secret` tool only for `list` / `path`.
+  To create vaults or set/unset values, or to set/run/remove whole-file
+  secrets, run `akm env …` / `akm secret …` directly in the shell so
+  secret material never passes through the chat turn.
+
+The plugin's typed `akm_*` tools (`akm_vault show`, `akm_proposal accept`,
+etc.) still apply their per-tool `confirm:true` contracts at
+`tool.execute.before`. Only the raw-shell tokenized gate has been removed.
 
 ### Environment overrides
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `AKM_AUTO_CURATE` | `1` | Set to `0` to disable automatic `akm curate` on user messages. Session start no longer auto-curates. |
+| `AKM_LOCAL_BUILD_CLI` | _(unset)_ | Optional absolute path to a locally built AKM CLI entrypoint such as `/abs/path/to/akm/dist/cli.js`. When set, the OpenCode plugin runs that build through Bun before falling back to bundled or PATH-based `akm` binaries. |
 | `AKM_AUTO_FEEDBACK` | `1` | Set to `0` to disable automatic `akm feedback` on tool success/failure. |
 | `AKM_AUTO_HINTS` | `1` | Set to `0` to skip injecting `akm hints` at session start. |
 | `AKM_AUTO_MEMORY` | `1` | Set to `0` to disable automatic session-summary memories. |
@@ -76,7 +129,6 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 | `AKM_RETROSPECTIVE_NEGATIVE_PATTERN` | `\b(wrong|failed|broken|didn't work|did not work|bad)\b` | Case-insensitive regex used for negative retrospective feedback signals. |
 | `AKM_SCOPE_KEYS` | `user,agent,run,channel` | Comma-separated list of scope fields to attach on every `akm_remember`, `akm_curate`, and `akm_feedback` call. Remove a key to opt out of that dimension. |
 | `AKM_PENDING_PROPOSAL_TIMEOUT` | `2` | Seconds allowed for lightweight pending-proposal count checks during context injection. |
-| `AKM_PACKAGE_REF` | `akm-cli@latest` | Override the npm/bun package spec used for auto-install (e.g. pin to `akm-cli@0.7.0` in CI). |
 
 ### Curator agent
 
@@ -96,14 +148,13 @@ The plugin injects a concise AKM workflow instruction pack into context so agent
 - record feedback after the result is known;
 - treat `lesson:*` as first-class durable assets;
 - treat proposed-quality assets as uncurated until accepted;
-- use `akm_help` to route `proposal`, `distill`, `reflect`, and `propose` CLI workflows;
-- require explicit user approval before proposal acceptance/rejection, push saves, source removal, CLI upgrades, update-all, or vault value access.
+- use `akm_help` to route `proposal`, `improve`, `propose`, and `tasks` CLI workflows;
+- require explicit user approval before proposal acceptance/rejection, push saves, source removal, CLI upgrades, update-all, vault value access, or secret-path access.
 
 The package also ships OpenCode command docs for common workflows:
 
 - `/akm-review-proposals`
-- `/akm-distill-lesson`
-- `/akm-reflect-on-failure`
+- `/akm-improve-asset`
 - `/akm-propose-asset`
 - `/akm-evolve-session`
 - `/akm-workflow-status`
@@ -120,7 +171,7 @@ Inputs:
 - `ref` (optional): stash ref like `agent:coach.md`
 - `query` (optional): resolve best matching stash agent when `ref` is omitted
 - `task_prompt` (required): user task to run
-- `dispatch_agent` (optional): OpenCode agent name (defaults to `general`)
+- `dispatch_agent` (optional): OpenCode agent name, or a `provider/model` override like `openai/gpt-5.3-codex` (defaults to `general`)
 - `as_subtask` (optional): create child session (defaults to `true`)
 
 At least one of `ref` or `query` is required.
@@ -128,6 +179,7 @@ At least one of `ref` or `query` is required.
 Behavior:
 - Loads the stash agent via `akm show`
 - Uses stash `prompt` verbatim as OpenCode `system`
+- Treats `dispatch_agent` values in `provider/model` form as model overrides and keeps a valid OpenCode agent in the `agent` field
 - Applies stash `modelHint` when in `provider/model` format
 - Applies stash `toolPolicy` when it maps to boolean tool flags
 
@@ -139,25 +191,25 @@ Inputs:
 - `ref` (optional): stash ref like `command:review.md`
 - `query` (optional): resolve best matching stash command when `ref` is omitted
 - `arguments` (optional): raw command arguments for `$ARGUMENTS`, `$1`, `$2`, etc.
-- `dispatch_agent` (optional): OpenCode agent name (defaults to current agent)
+- `dispatch_agent` (optional): OpenCode agent name, or a `provider/model` override like `openai/gpt-5.3-codex` (defaults to current agent)
 - `as_subtask` (optional): create child session (defaults to `false`)
 
 At least one of `ref` or `query` is required.
 
 ## Prerequisites
 
-When the plugin loads, it checks the installed `akm` version first and only runs `bun install -g akm-cli@latest` when `akm` is missing or older than the latest stable npm release. Newer pre-releases and local builds are left in place. It then prefers the Bun-installed binary and falls back to an existing `akm` on PATH when needed. It does not run the standalone shell installers automatically.
+When the plugin loads, it resolves the bundled `akm-cli` dependency installed with the plugin and requires an `akm` version that satisfies `^0.8.0`. It prefers that bundled binary first, falls back to an existing `akm` on PATH only when it also satisfies the same range, and otherwise returns a structured error telling you to reinstall or update the plugin so OpenCode/Bun installs the dependency. It does not run global installers from plugin runtime.
 
 ```sh
 # macOS / Linux
 curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
 # PowerShell (Windows)
 irm https://raw.githubusercontent.com/itlackey/akm/main/install.ps1 -OutFile install.ps1; ./install.ps1
-
-# Or via Bun
-bun install -g akm-cli@latest
 ```
 
+Reinstall or update the plugin to let OpenCode/Bun install the bundled `akm-cli`
+dependency automatically.
+
 ## Stash model
 
 The stash directory is resolved automatically via a three-tier fallback: `AKM_STASH_DIR` env var (optional override) → `stashDir` in `config.json` → platform default. Set it persistently with:
@@ -176,14 +228,16 @@ stash/
 ├── agents/     # markdown files
 ├── knowledge/  # markdown files
 ├── memories/   # markdown memory files (akm remember)
-├── lessons/    # first-class durable learnings (lesson:<name>) — produced by akm distill, accepted via akm_proposal accept
+├── lessons/    # first-class durable learnings (lesson:<name>) — often produced by akm improve, accepted via akm proposal accept
+├── tasks/      # scheduled task definitions (task:<name>) managed via akm tasks ...
 ├── workflows/  # multi-step procedures (workflow:<name>)
 ├── vaults/     # .env secret stores (vault:<name>) — values never surface through structured output
+├── secrets/    # whole-file secrets (secret:<name>) — contents never surface through structured output
 ├── wikis/      # per-wiki directories <name>/{schema,index,log}.md + raw/ + pages
-└── .akm/proposals/  # v0.7.0 proposal queue — drafts that never leak into search or commits
+└── .akm/proposals/  # v0.8.0 proposal queue — drafts that never leak into search or commits
 ```
 
-## Vaults
+## Vaults And Secrets
 
 `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,
@@ -196,8 +250,14 @@ AKM CLI itself guarantees vault values never appear in JSON, the search index,
   `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.
+Automatic feedback recording (`tool.execute.after`) skips `vault:*` and `secret:*`
+refs so usage signals can't leak which sensitive asset was touched.
+
+`akm_secret` mirrors the same safety boundary for whole-file secrets:
+
+- `action: "list"` returns secret refs only.
+- `action: "path"` returns the absolute file path without reading or surfacing contents.
+- `action: "set"`, `"run"`, and `"remove"` are intentionally absent from the typed tool surface. Use raw `akm secret …` through the shell only after explicit user approval.
 
 Assets are resolved from three source types: **working** (local stash), **search paths** (additional dirs via `searchPaths` config), and **installed** (registry kits via `akm add` — see `akm_help` topic="add").
 

package/agent/akm-curator.md

@@ -4,7 +4,7 @@ description: AKM stash curator. Reviews session activity and proposes stash impr
 permission:
   task: deny
 tools:
-  akm_vault: deny
+  akm_env: deny
   write: deny
   bash: deny
 ---
@@ -20,14 +20,14 @@ 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.
-- Lesson candidates: repeated memories or failures that should become a proposed lesson. Use akm_help topic="distill" before raw CLI distill commands.
+- Lesson candidates: repeated memories or failures that should become a proposed lesson. Use akm_help topic="improve" to surface the v0.8.0 improve flow (which replaces the old reflect/distill split) and propose an akm_improve <ref> call.
 - 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 via the akm CLI (see akm_help topic="reindex").
 - Pending proposals: list or diff them via akm_help topic="proposal" and recommend accept, reject, or revise. Never accept or reject without explicit user approval.
 - Duplicates / drift: near-identical descriptions or overlapping responsibilities. Propose a consolidation.
 - Stale memories: session summaries that never get recalled. Propose removal (see akm_help topic="remove") 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 load unless the user explicitly asks. Vault values must never appear in reports.
+- Never touch env or secret values: do not call akm_env run or akm_secret path unless the user explicitly asks. Values must never appear in reports.
 
 Rules of engagement:
 - Never apply destructive changes without explicit user approval.
@@ -45,7 +45,7 @@ Output shape: end every run with a markdown report that has these sections:
 - <ref> — failure signal — proposed fix
 
 ## Lesson candidates
-- <theme> — evidence refs — distill or reflect command to run
+- <theme> — evidence refs — `akm improve <ref>` or `akm propose <type> <name> --task "..."` command to run
 
 ## Coverage gaps
 - <theme> — proposed asset (type, name, one-line description)

package/commands/akm-improve-asset.md

@@ -0,0 +1,9 @@
+Improve existing AKM assets or distill repeated evidence into proposals.
+
+1. Identify the strongest evidence refs or the asset type that needs work.
+2. Record negative feedback when justified.
+3. Call `akm_help` with `topic: "improve"`.
+4. Run `akm improve [<type>|<ref>] [--task "..."]`.
+5. List resulting pending proposals and do not accept or reject them without explicit user approval.
+
+Improve-profile config (`profiles.improve.<name>`) shapes the run: `processes.triage` is a triage PRE-pass that drains the pending backlog by a deterministic policy (`{ enabled, applyMode: queue|promote, policy, maxAcceptsPerRun, maxDiffLines, rejectEmpty, judgment }`, same engine as `akm proposal drain`); `sync` (`{ enabled, push, message }`, with `{timestamp}{date}{time}{scope}{refs}{accepted}` message tokens) commits/pushes a git-backed stash at end of run. Override sync with `akm improve --sync/--no-sync` and `--push/--no-push`. Triage + `akm proposal drain` is the built-in replacement for the old manual proposal-management agent session.

package/commands/akm-propose-asset.md

@@ -4,5 +4,5 @@ Create a proposed AKM asset for a coverage gap.
 2. Confirm the gap is real.
 3. Call `akm_help` with `topic: "propose"`.
 4. Choose the smallest suitable asset type.
-5. Run `akm propose <type> <name> --task "..."`.
+5. Run `akm propose <type> <name> --task "..."` or `akm propose <type> <name> --file ./prompt.md`.
 6. Show proposal review commands and remind the user that proposed assets are not curated until accepted.

package/commands/akm-review-proposals.md

@@ -2,6 +2,7 @@ Review pending AKM proposals safely.
 
 1. Call `akm_help` with `topic: "proposal"`.
 2. Run `akm proposal list --status pending --format json`.
-3. For relevant proposals, run `akm proposal show <id>` and `akm proposal diff <id>`.
+3. For relevant proposals, run `akm proposal show <id>` and `akm proposal diff <id>` (positional id).
 4. Summarize the likely accept, reject, or revise outcome.
 5. Do not run `akm proposal accept` or `akm proposal reject` unless the user explicitly approves the exact command.
+6. For a large backlog, suggest the deterministic bulk path: `akm proposal drain --policy <personal-stash|conservative|manual> --dry-run` to preview, then `--promote --yes` only after explicit approval (mutating; commits to git, no batch revert). This — plus the automatic `processes.triage` pre-pass inside `akm improve` — is the built-in replacement for the old manual proposal-management agent session.