akm-cli 0.9.0-rc.8 → 0.9.0

package/docs/reference/configuration.md

@@ -0,0 +1,358 @@
+# Configuration
+
+AKM reads one user configuration file: `$XDG_CONFIG_HOME/akm/config.json`
+(normally `~/.config/akm/config.json` on Linux and macOS, or
+`%APPDATA%\akm\config.json` on Windows). Set `AKM_CONFIG_DIR` to override the
+directory. Project `.akm/config.json` files are not merged.
+
+## Version 0.9
+
+A present configuration file must set `configVersion` to exactly `"0.9.0"`.
+Missing, older, newer, numeric, and malformed versions are rejected by ordinary
+commands without rewriting the file. `akm migrate status` reports config and
+database state independently; it exits nonzero when migration is blocked.
+`akm migrate apply` installs an operator-prepared 0.9 config and applies pending
+database migrations, but it never guesses profile-to-engine mappings. See [the
+migration guide](../migration/v0.8-to-v0.9.md) before editing an existing
+installation.
+
+Canonical config and durable database access fail closed while a restore or
+migration-apply operation is incomplete. Use `akm migrate status` to inspect it
+and `akm migrate apply` to retry; do not delete migration control files manually.
+
+AKM 0.8 does not provide these migration commands. To cross from 0.8 to 0.9,
+prepare the target and an independent filesystem backup first, install or stage
+the 0.9 binary manually, then invoke that new binary with `migrate apply
+--config`. Do not use `upgrade --migration-config` from 0.8; that installed 0.8
+code cannot enforce safeguards introduced by 0.9.
+
+```jsonc
+{
+  "configVersion": "0.9.0",
+  "$schema": "https://itlackey.github.io/akm/schemas/akm-config.json",
+  "engines": {
+    "fast": {
+      "kind": "llm",
+      "endpoint": "http://localhost:11434/v1/chat/completions",
+      "model": "qwen3",
+      "apiKey": "${LOCAL_LLM_API_KEY}"
+    },
+    "reviewer": {
+      "kind": "agent",
+      "platform": "opencode",
+      "model": "anthropic/claude-sonnet-4-6"
+    }
+  },
+  "defaults": {
+    "engine": "reviewer",
+    "llmEngine": "fast",
+    "improveStrategy": "default"
+  },
+  "workflow": {
+    "maxConcurrency": 8,
+    "judgeEngine": "reviewer"
+  },
+  "improve": {
+    "strategies": {
+      "nightly": {
+        "engine": "fast",
+        "processes": {
+          "reflect": {},
+          "memoryInference": { "model": "qwen3-small", "llm": { "temperature": 0.1 } }
+        }
+      }
+    }
+  }
+}
+```
+
+## Engines
+
+`engines` is the only public execution map. An engine name is lowercase
+kebab-case, at most 63 characters, and cannot start with `akm-`.
+
+| Kind | Required fields | Use |
+| --- | --- | --- |
+| `llm` | `endpoint`, `model` | OpenAI-compatible chat completions |
+| `agent` | `platform` | A registered dispatch-capable harness |
+
+LLM endpoints must be complete `http://` or `https://` chat-completions URLs
+ending in `/chat/completions`, without userinfo, query, or fragment. API keys
+are symbolic only: `$VAR` or `${VAR}`. AKM resolves them only at dispatch.
+
+An agent engine may set `bin`, `args`, `workspace`, `model`, `timeoutMs`, and
+`modelAliases`. Only `platform: "opencode-sdk"` may set `llmEngine`; it names
+the LLM engine used as that SDK engine's fallback connection.
+
+`platform: "opencode-sdk"` needs the **`opencode` binary** on PATH (or a `bin`
+pointing at it). akm bundles `@opencode-ai/sdk`, but that package is an HTTP
+client with no dependencies — it spawns `opencode serve` and talks to it — so
+the npm dependency alone does not make the platform usable. Install the binary
+with `npm i -g opencode-ai` or opencode's own installer.
+
+Config-root `modelAliases` resolve by exact engine/platform column first, then
+the shared `llm` column for direct and fallback LLM engines, then `"*"`. The
+resolved exact model is used consistently by direct dispatch, SDK fallback,
+health evidence, and frozen workflow plans.
+
+`defaults.engine` names an LLM or agent engine. `defaults.llmEngine` must name
+an LLM engine. There is no first-engine fallback: an unset `defaults.engine`
+never resolves to some arbitrary entry in `engines`. It resolves instead to a
+synthesized, config-free `opencode-sdk` engine when the `opencode` binary is on
+PATH — announced once per run, and preempted by any `opencode-sdk` engine you
+configure yourself. Naming an engine that is not configured is always an error
+and is never rescued by that fallback.
+
+Index passes select engines through `index.defaults.engine` or
+`index.<pass>.engine`. Per-pass `model`, `timeoutMs`, and `llm` fields are
+invocation overrides; `enabled: false` disables that pass. Connection fields
+such as `endpoint`, `provider`, and `apiKey` belong only on named engines.
+
+`workflow.maxConcurrency` is the native workflow engine ceiling. An explicit
+value is clamped to `1..64`. When absent, AKM derives the cap once from the CPU
+count (`min(16, max(1, cores - 2))`) and freezes it into the run plan, so resume
+does not change policy on a different host or after config edits.
+
+`workflow.judgeEngine` names the LLM or agent engine used to verify every
+non-empty workflow `### gate` rubric. It is required when a workflow declares
+completion criteria and is frozen into each new run, so later config edits do
+not change an in-flight run's verifier. Missing, failed, or malformed verifier
+results reject the gate; criteria are never silently bypassed.
+
+## Strategies
+
+Improve presets live under `improve.strategies`; invoke one with
+`akm improve --strategy <name>`. The selection order is `--strategy`,
+`defaults.improveStrategy`, then built-in `default`. A strategy and each process
+can select `engine`, `model`, `timeoutMs`, and LLM request overrides:
+
+```jsonc
+{
+  "improve": {
+    "strategies": {
+      "nightly": {
+        "engine": "fast",
+        "processes": {
+          "reflect": { "llm": { "temperature": 0.2 } },
+          "graphExtraction": { "model": "qwen3-small" }
+        }
+      }
+    }
+  }
+}
+```
+
+LLM-only improve processes require an LLM engine; an explicit invalid or
+incompatible engine never falls back to another engine. Built-in strategies
+are complete presets. User-defined strategies inherit omitted fields from the
+built-in `default` strategy before applying their own overrides.
+
+The shipped `default` and `frequent` strategies keep improve-stage session
+extraction off. `proactiveMaintenance` is off in `default` and
+`reflect-distill`; run `akm improve --strategy proactive-maintenance` to use the
+dedicated opt-in preset. Because strategies inherit from `default`, a preset
+that omits either process also inherits the off value. User strategy overrides
+are applied last, so an explicit `enabled: true` still opts the selected
+strategy in.
+
+These improve-stage defaults do not gate explicit standalone extraction through
+`akm proposal extract --type <harness>` or `akm proposal extract --auto`. The interactive
+scheduled-task step also continues to offer the bundled `core/extract` template
+as an unselected opt-in; it is not installed merely because the template is
+bundled.
+
+## Indexing
+
+`index.indexBodyOpening` defaults to `false`. When enabled, AKM captures the
+first prose paragraph of each Markdown asset body, capped at 280 characters,
+into the lowest-weight search content and embedding text. Secret and env files
+are never read for this field, and session-kind memories are excluded.
+
+Changing this option changes indexed text. Run `akm index --full` after
+toggling it so all entries and embeddings are rebuilt consistently. If the
+setting differs from the state used to build the current index, AKM warns until
+that full rebuild completes.
+
+## Semantic search
+
+`semanticSearchMode` (top-level, `"off" | "auto"`, default `"off"`) gates
+embedding-based search. `"auto"` lets AKM set up embeddings (which downloads
+a local model unless you point `embedding` at a remote provider) and falls
+back to keyword-only FTS if the embedding runtime is unavailable; `"off"`
+disables semantic search outright and search is always keyword-only FTS.
+The default is `"off"` so a bare or headless install (`akm bundle create`, `--yes`,
+`--config`) never silently downloads the local embedding model on first
+index.
+The interactive `akm setup` wizard pre-selects semantic search **on**
+regardless of this default, and warns that choosing it downloads the model
+unless a remote `embedding` config is provided.
+
+```jsonc
+{ "semanticSearchMode": "off" }
+```
+
+`embedding` configures the connection used for semantic search and
+`akm improve`'s memory-inference/consolidate passes when they call an
+embedding model: `provider`, `endpoint`, `model`, `apiKey` (symbolic
+reference, same rules as engine `apiKey`), `dimension`, `localModel`,
+`maxTokens`, `batchSize`, `chunkSize`, `contextLength`, and
+`ollamaOptions.num_ctx`.
+
+## Search tuning
+
+`search` tunes ranking, not behavior an ordinary user needs to touch:
+
+| Key | Purpose |
+| --- | --- |
+| `search.minScore` | Drop results below this score |
+| `search.defaultExcludeTypes` | Asset types excluded from results by default |
+
+### Graph boost search tuning
+
+| Key | Purpose |
+| --- | --- |
+| `search.graphBoost.*` | Entity-graph relevance boost: `directBoostPerEntity`/`directBoostCap` (directly related entities), `hopBoostPerEntity`/`hopBoostCap` (multi-hop, capped at `maxHops` ≤ 3), `confidenceMode` (`off`\|`blend`\|`multiply`, default `blend`), `confidenceWeight` (0–1, default `0.2`) |
+
+## Feedback
+
+`feedback` shapes the `akm feedback` taxonomy:
+
+| Key | Purpose |
+| --- | --- |
+| `feedback.requireReason` | Whether `akm feedback --negative` without `--reason`/`--failure-mode` is a hard error. **Defaults to `true`** when unset — set `false` to downgrade the check to a warning instead |
+| `feedback.allowedFailureModes` | Restrict `--failure-mode` values accepted by `akm feedback`. Curated set (also the default when unset): `incorrect`, `outdated`, `dangerous`, `incomplete`, `redundant` |
+
+## Bundles and write target
+
+`bundles` (replacing the retired `stashDir`/`sources[]`/`installed[]` trio)
+and `defaultBundle` are the 0.9 source configuration shape — see
+[Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) and the [CLI reference](cli.md) for the
+full bundle model (`path`, `git`, `website`, `npm`, `writable`, `registryId`,
+`components`). `defaultBundle` must name a key in `bundles` when set.
+
+### defaultWriteTarget
+
+`defaultWriteTarget` names the bundle that write commands (`akm remember`,
+`akm env`/`secret create`, `akm improve`, etc.) fall back to when no
+explicit destination flag is given and the command isn't already scoped to a
+specific source. It must name a configured bundle; setting it with no
+`bundles` configured, or naming an unconfigured bundle, is rejected at
+`config set` (or config load) time. The full write-target resolution order
+is the command's destination flag (`--bundle` on `remember`/`clone`/
+`improve`, `--target` on `env`/`secret create`) -> `defaultWriteTarget` ->
+working bundle (`defaultBundle`) -> `ConfigError`.
+
+### Memory scope
+
+`akm remember`'s scope flags (`--user`, `--agent`, `--run`, `--channel`)
+write four canonical top-level frontmatter keys on the memory file:
+`scope_user`, `scope_agent`, `scope_run`, `scope_channel` (one key per
+non-empty scope value; string values). This is not a config-file setting —
+it is documented here because it is the multi-tenant/multi-agent contract
+that `akm search --filter` and `akm show --filter` read back:
+`--filter user=<id>` / `--filter agent=<id>` / `--filter run=<id>` /
+`--filter channel=<name>` (repeatable) narrow results/resolution to assets
+whose frontmatter scope matches, without changing ranking. A memory with
+only scope flags and no tags is valid — the tag-required check is
+independent of scope. `--scope` was removed in 0.9.0 with no alias; use
+`--filter`.
+
+`archiveRetentionDays` (default `90` when unset) controls how long a pending
+proposal is kept before `akm improve`'s maintenance pass archives it (status
+`rejected`, reason `"expired: no action within retention window"`) — `akm
+proposal` itself has no archive/expire verb. Setting it to `0` or less
+disables expiry entirely.
+
+## Registries
+
+`registries` (top-level array, distinct from `bundles`) lists remote package
+registries `akm registry`/`akm bundle add` can search and install from.
+Each entry is `{ url, name?, enabled?, provider?, options? }`; `provider`
+defaults to `"static-index"`. See [Registries](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md) for the full
+field reference and provider list.
+
+## Output defaults
+
+`output.format` (one of `json`\|`yaml`\|`text`\|`jsonl`\|`md`\|`html`,
+default `json`) and `output.detail` (`brief`\|`normal`\|`full`, default
+`brief`) set the CLI's default `--format`/`--detail` when the flags are
+omitted. Per-command flags always override these.
+
+## Setup-derived recommendations
+
+`setup` is reserved for configuration derived by `akm setup`. It currently
+holds no keys — the `setup.taskSchedules` sub-key was removed in 0.9.0 after
+nothing in the setup flow or the tasks subsystem was found to read or write
+it. Scheduling lives in the tasks subsystem (`akm task`).
+
+## Experimental opt-ins
+
+`experimental` holds explicit opt-ins for behavior outside the 0.9
+stability contract (see [STABILITY.md](../../STABILITY.md) for full
+classification). Every key defaults to **off**; an absent `experimental`
+section, an absent key, and an explicit `false` all read identically as off.
+
+```jsonc
+{
+  "experimental": {
+    "improveAutonomy": false
+  }
+}
+```
+
+- **`experimental.improveAutonomy`** — gates only the autonomous
+  `memoryInference`, `triagePromote`, and `memoryCleanup` lanes. `akm improve`
+  itself always runs; this only gates mutations without a human in the loop.
+  Consolidation is not gated: it remains advisory and emits reviewable
+  proposals. `sync.push` is deliberately **not** gated by this key.
+
+## Managing Config
+
+```sh
+akm config list
+akm config get engines.fast
+akm config set engines.fast '{"kind":"llm","endpoint":"http://localhost:11434/v1/chat/completions","model":"qwen3"}'
+akm config set engines.fast.apiKey '$LOCAL_LLM_API_KEY'
+akm config unset engines.old
+akm migrate status
+akm migrate status --config ./prepared-0.9.json
+akm migrate apply --config ./prepared-0.9.json --dry-run
+akm migrate apply --config ./prepared-0.9.json
+```
+
+Object values passed to `config set` deep-merge with their current value.
+Arrays replace, `null` is only valid for nullable fields, and `config unset` is
+the only deletion operation. `configVersion` cannot be set or unset with the
+generic walker.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `AKM_CONFIG_DIR` | Override the user config directory (or set `XDG_CONFIG_HOME`) |
+| `AKM_ENGINE_<NAME>_API_KEY` | Fallback credential for LLM engine `<name>` |
+| `AKM_LLM_API_KEY` | Fallback only for the selected `defaults.llmEngine` |
+| `AKM_EMBED_API_KEY` | Embedding credential |
+| `AKM_BUNDLE_DIR` | Override the stash directory |
+| `AKM_DATA_DIR` | Override the data directory — durable `index.db`/`workflow.db`/`state.db`, `akm.lock`, config backups (or set `XDG_DATA_HOME`) |
+| `AKM_CACHE_DIR` | Override the cache directory — regenerable caches (or set `XDG_CACHE_HOME`) |
+| `AKM_STATE_DIR` | Override the state directory — task-scheduler invocation state (or set `XDG_STATE_HOME`) |
+| `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE` |
+| `AKM_VERBOSE` | Truthy value enables the same diagnostics as `--verbose` |
+| `AKM_DEBUG` | `1` prints a stack trace on unexpected internal errors |
+
+For an engine named `fast`, its fallback variable is
+`AKM_ENGINE_FAST_API_KEY`. An explicit `apiKey` symbolic reference is
+authoritative and does not fall through to another variable.
+
+Use `AKM_SQLITE_JOURNAL_MODE=DELETE` or `TRUNCATE` when WAL is unavailable,
+such as on some NFS/SMB mounts. With the default `WAL` setting, AKM detects a
+network filesystem for the data directory and falls back to `DELETE`.
+
+## Retired Configuration
+
+`profiles`, `llm`, `agent`, `features`, `stashes`, `defaults.llm`,
+`defaults.agent`, and `defaults.improve` are rejected in 0.9. Recreate the
+configuration using `engines`, `defaults.engine`, `defaults.llmEngine`, and
+`improve.strategies`; AKM deliberately does not infer or rename ambiguous
+profile identities.

package/docs/reference/data-and-telemetry.md

@@ -16,6 +16,7 @@ AKM adds no network destinations of its own. The requests it *does* make all go
 2. **Registry metadata and stash packages** from sources you explicitly configure (GitHub, npm, git remotes, websites) — those hosts receive the fetch/clone/crawl requests, and website sources receive requests for the pages you crawl.
 3. **`akm upgrade`** — fetches the latest release from GitHub releases (GitHub sees the request).
 4. **`akm setup`** — a single DNS lookup for `github.com` to decide whether to skip network-dependent steps (Ollama detection, remote embedding probes) when offline. No HTTP request is made by this probe; if it succeeds, akm proceeds with the network-dependent steps you already configured.
+5. **`akm improve` dead-link checks** — a full-scope improve run (the default for a bare `akm improve`) sends best-effort `HEAD` requests (following redirects, with a short timeout and a hard cap on URL count) to URLs found in the bodies of the knowledge assets it is improving, to flag dead links. The hosts of those URLs see a `HEAD` request; no asset content is sent. Keep URLs you don't want probed out of knowledge-asset bodies, or run improve with an explicit narrower scope.
 
 In every case the receiving endpoint is one you configured or invoked; the data leaving your machine is the data you directed AKM to send there.
 
@@ -29,7 +30,7 @@ AKM writes to these locations on your machine. All paths follow [XDG Base Direct
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
-| `config.json` | Your AKM configuration: engines, strategies, stash paths, and feature settings | **No** — deleting resets all settings |
+| `config.json` | Your AKM configuration: engines, improve strategies, bundles (stash sources), and experimental opt-ins — see [Configuration](configuration.md) | **No** — deleting resets all settings |
 
 Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 
@@ -39,6 +40,7 @@ Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 |---|---|---|
 | `index.db` | Search index for all your stash assets (FTS5 + metadata) | Yes — rebuilds via `akm index --full` |
 | `state.db` | Events, local usage telemetry, proposals, task history, improve run results, and workflow run state/history (the former `workflow.db` was folded in during the 0.9.0 cutover) | **No** — deletes event/usage logs, proposal queue, improve history, and workflow run history |
+| `logs.db` | Structured, high-volume task/run log lines (`{ts, task_id, run_id, stream, level, line}`), joined to `state.db`'s `task_history` rows by `task_id@started_at`. Kept separate from `state.db` because log lines are append-only and freely purgeable, unlike durable state | Yes — log lines are regenerable per run; deleting loses historical run output only |
 | `akm.lock` | Inter-process write lock | Yes — recreated automatically |
 | `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
 
@@ -52,7 +54,7 @@ Everything in the cache is regenerable. It is safe to delete the entire cache di
 |---|---|---|
 | `config-backups/config-<timestamp>.json` | Pre-save config snapshots (5 retained; owner-only permissions — file `0600`, dir `0700`, since 08-F4) | Yes |
 | `config-backups/config.latest.json` | Latest backup alias (owner-only `0600`) | Yes |
-| `registry/` | Downloaded registry tarballs (stash packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm add` or `akm update` |
+| `registry/` | Downloaded registry tarballs (stash packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm bundle add` or `akm bundle update` |
 | `registry-index/` | Legacy per-URL JSON cache (v0.7 artifact) | Yes — fully replaced by `index.db` in 0.8.0 |
 | `semantic-status.json` | Semantic index build status marker | Yes |
 | `bin/` | Downloaded AKM binary cache (used by `akm upgrade`) | Yes |
@@ -65,10 +67,10 @@ Override: set `AKM_CACHE_DIR` or `XDG_CACHE_HOME`.
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
-| `<stash>/` | All your asset files: agents, skills, commands, knowledge, workflows, memories, env files, secrets, wikis, lessons, facts | **No** — this is YOUR data |
+| `<stash>/` | All your asset files: agents, skills, commands, knowledge, instructions, workflows, scripts, memories, env files, secrets, lessons, tasks, sessions, facts, plus any bundle-adapter-owned content (e.g. `llm-wiki` bundle roots — not an AKM `PLACEMENT_SPECS` type) | **No** — this is YOUR data |
 | `<stash>/.akm/` | Hidden AKM metadata (v0.7 proposals, legacy runs) | Caution — check for pending proposals first |
 
-Override: set `AKM_STASH_DIR` (or configure `stashDir` in `config.json`).
+Override: set `AKM_BUNDLE_DIR`, or configure `bundles`/`defaultBundle` in `config.json` (the top-level `stashDir` key from 0.8 is retired and rejected in 0.9 — see [Configuration](configuration.md#bundles-and-write-target)).
 
 ---
 
@@ -92,54 +94,118 @@ An append-only log of every mutating action you perform with AKM. Events are sto
 - API keys or secrets (config is not stored in events)
 - Personal information
 
-**Retention:** Events older than 90 days are purged automatically when `akm improve` runs its maintenance pass. Purge is controlled by `purgeOldEvents()` with a 90-day default.
+**Retention:** Events older than 90 days are purged automatically when `akm improve` runs its maintenance pass. The window is `improve.eventRetentionDays` (default `90`; set `0` to disable), enforced by `purgeOldEvents()`.
 
-**Full event type list:**
+**Full event type list.** `EventType` (`src/core/events.ts`) is an open
+string union — new types can be added without a schema bump — so this is
+the set of types the code actually emits at HEAD (verified against every
+`appendEvent(...)` call site, 2026-07-27), grouped by area:
+
+*Asset lifecycle*
 
 | Event type | When emitted | Key metadata fields |
 |---|---|---|
-| `add` | `akm add <source>` | `ref`, `provider` |
-| `remove` | `akm remove <source>` | `ref` |
-| `update` | `akm update [source]` | `ref` |
+| `add` | `akm bundle add <source>` | `ref`, `provider` |
+| `remove` | `akm bundle remove <source>` | `ref` |
+| `update` | `akm bundle update [source]` | `ref` |
 | `remember` | `akm remember <text>` | `ref` |
 | `import` | `akm import <file>` | `ref` |
-| `save` | `akm sync` | `ref` |
-| `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
+| `rekey` | `scripts/rekey-asset-ref.ts` moved at least one row onto a renamed asset's new ref — nothing is emitted on a no-op re-run | `ref` (the new ref); metadata `{from, to, changed}` (row counts only) |
+
+*Search, retrieval, sync*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
 | `search` | `akm search <query>` | `query`, `source`, `signal` |
 | `curate` | `akm curate <prompt>` | `query`, `source` |
 | `show` | `akm show <ref>` | `ref`, `type`, `name` |
 | `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
+| `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
+| `sync` | `akm sync` (renamed from `save` in 0.9.0; historical rows keep `save`, and `akm log --type save`/`--type sync` are synonyms on read) | `ref` |
+| `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason` |
+| `env_access` | `akm env run <name> -- <command>` (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
+| `secret_access` | `akm secret run <ref> <VAR> -- <command>` (audit trail: var **name** only, value never recorded) | `ref`, `var` |
+
+*Proposals*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
 | `promoted` | `akm proposal accept <id>` | `ref` |
 | `rejected` | `akm proposal reject <id>` | `ref` |
+| `proposal_reverted` | `akm proposal revert <id>` (undoes a previously-accepted proposal, restores prior content) | `ref` |
+| `proposal_expired` | A pending proposal aged past the retention window and was auto-expired | `ref` |
+| `proposal_expiration_pass` | Summary emitted once per `akm improve` maintenance run after per-proposal `proposal_expired` events | expiry counts |
+| `proposal_orphan_purge` | Stale proposals whose target asset no longer exists on disk, pruned by improve maintenance | `checked`, `rejected` |
+| `proposal_creation_rejected` | `createProposal()` validation failed before write | `ref`, `reason`, `source` |
+| `triage_drained` | `akm proposal drain` run summary | `promoted`, `rejected`, `deferredByReason`, `skippedByCap`, `policy`, `applyMode` |
+| `triage_deferred` | `akm proposal drain` left items unresolved after the (optional) judgment tier | `deferred`, `deferredByReason`, `reason` |
+
+*`akm improve` pipeline*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `improve_invoked` | Start of an `akm improve` run | `ref` (scope); `strategy`, `scope`, `dryRun`, `eligibleCount` |
+| `improve_completed` | `akm improve` run finished | run stats |
+| `improve_failed` | `akm improve` run errored | error |
+| `improve_skipped` | Asset skipped by cooldown or budget | `ref`, `reason` |
+| `improve_lock_recovered` | Stale improve lock cleared at startup | |
+| `improve_review_needed` | `akm feedback` pushed a high-utility asset's utility below the review threshold — a review-needed escalation is recorded (not a proposal, so it can't accidentally overwrite the asset) | `ref`, `previousUtility`, `nextUtility` |
 | `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |
 | `reflect_completed` | Reflect phase produced a proposal | `ref` |
 | `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
-| `propose_invoked` | `akm propose` | `ref` |
-| `distill_invoked` | `akm distill` | |
-| `improve_skipped` | Asset skipped by cooldown or budget | `ref`, `reason` |
-| `improve_completed` | `akm improve` run finished | run stats |
-| `improve_failed` | `akm improve` run errored | error |
-| `improve_lock_recovered` | Stale lock cleared at startup | |
-| `proposal_orphan_purge` | Stale proposals pruned | `checked`, `rejected` |
-| `proposal_creation_rejected` | `createProposal()` validation failed | `ref`, `reason`, `source` |
-| `proposal_expired` | Proposal expired | `ref` |
-| `events_purged` | Old events deleted by maintenance | `purgedCount`, `retentionDays` |
-| `workflow_started` | `akm workflow start <ref>` | `ref`, `runId` |
-| `workflow_step_completed` | `akm workflow next` (genuine `completed` transition only) | `ref`, `runId`, `stepId`, `status` |
-| `workflow_step_updated` | `akm workflow next` (non-`completed` transitions: `failed`/`skipped`/`blocked`) | `ref`, `runId`, `stepId`, `status` |
-| `workflow_finished` | `akm workflow complete` | `ref`, `runId` |
-| `schema_repair_invoked` | `akm lint --repair` triggered schema repair | `ref` |
-| `archive_cleanup` | Archive cleanup during consolidation | |
+| `propose_invoked` | `akm proposal new` | `ref` |
+| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome |
+| `consolidate_completed` | `akm improve`'s consolidate pass processed at least one memory | `ref` (`memories/_consolidation`) |
+| `extract_invoked` | `akm proposal extract --type <harness>` / `--auto`, or improve-stage session extraction | `outcome`, `sessionId`, `harness` |
+| `extract_triaged` | The pre-LLM extract triage gate evaluated at least one session | `evaluated`, `passed`, `triagedOut`, `sourceRun` (aggregated) |
+| `schema_repair_invoked` | The schema-repair pass inside `akm improve` (`runSchemaRepairPass`) attempts to patch missing frontmatter on an asset that failed schema validation. **There is no `akm lint --repair` flag** — `lint` has `--fix`/`--auto-fix`, unrelated to this event | `ref`, outcome |
+| `proactive_selected` | The proactive-maintenance selector runs (once per `akm improve` run) | `count`, `dueTotal`, `neverReflected` (aggregated) |
+| `improve_replay_selected` | Bounded replay-budget selection ran | `count`, `budget`, `convergedSkipped`, `candidatePool` (aggregated) |
+| `improve_salience_first_run` | First improve run with no pre-existing salience baseline to compare against | `candidateCount`, `note` |
+| `improve_salience_rank_change` | Stash-wide rank-change report, from the second improve run onward | `stashSize`, `totalChanged`, `forgettingCandidates`, `topDrops` |
+| `outcome_proxy_inverted` | Proxy-adequacy tripwire: `outcome_score` correlates *negatively* with accepted-change rate (corr < −0.3) | `correlation`, `n` |
+| `outcome_proxy_dead` | Proxy-adequacy tripwire: `outcome_score` is statistically unrelated to accepted-change rate (\|corr\| < 0.1, n ≥ 500) | `correlation`, `n` |
+| `collapse_detector_alert` | The collapse/churn detector trips an alert rule during an improve cycle | `kind` (collapse-recall\|collapse-entropy\|collapse-shrink\|churn\|merge-floor), `detail`, `metrics`, `canarySetId`, `runId` |
+| `events_purged` | Old events deleted by improve maintenance (90-day default retention) | `purgedCount`, `retentionDays` |
+| `improve_runs_purged` | Old `improve_runs` rows deleted by improve maintenance (same retention window as events) | `purgedCount`, `retentionDays` |
+| `improve_cycle_metrics_purged` | Old `improve_cycle_metrics` rows (365-day retention) deleted by improve maintenance | `purgedCount`, `retentionDays` |
+| `task_logs_purged` | Old scheduled-task log files purged by improve maintenance | |
+
+*Workflows*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `workflow_started` | `akm workflow run <ref>` creates a run (including native workflow task execution) | `ref`, `runId` |
+| `workflow_step_completed` | The run completion path records a genuine `completed` transition | `ref`, `runId`, `stepId`, `status` |
+| `workflow_step_updated` | The run completion path records a non-`completed` transition (`failed`/`skipped`/`blocked`) | `ref`, `runId`, `stepId`, `status` |
+| `workflow_finished` | A `run` transition makes the run terminal | `ref`, `runId` |
+| `workflow_abandoned` | `akm workflow abandon` | `runId` only — never the workflow title |
+| `workflow_unit_started` | A unit begins through `akm workflow run` | ids/status only — never unit instructions or results |
+| `workflow_unit_finished` | A workflow unit terminates | ids/status/tokens only — never unit instructions or results |
+
+*LLM usage and health*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `llm_usage` | Per-attempt LLM call usage telemetry (#576) | model provenance, terminal outcome, duration, optional token usage |
+| `llm_usage_summary` | The owning LLM telemetry sink's terminal-record count marker | `expectedTerminalRecords` |
+| `health_probe` | `akm health`'s state.db round-trip write/read probe. **Not durably retained**: the row is inserted then deleted within the same connection once the round trip is confirmed, so the net effect on the `events` table is always zero rows | n/a (ephemeral) |
 
 ### 2. Usage Events Table
 
-`usage_events` is the local analytical record behind `akm history`, utility
-ranking, retrieval-demand counts, GRR, and real-query eval generation. It stores
+`usage_events` is the local analytical record behind utility ranking,
+retrieval-demand counts, GRR, and real-query eval generation (0.9.0: its CLI
+read surface, `akm history`, was removed — the table itself and everything
+below still applies). It stores
 search/curate queries, per-entry search impressions, explicit show/curate
 engagement, feedback signals, stable refs, and timestamps. It never leaves the
 machine unless you explicitly copy the database or send derived content to a
 configured endpoint.
 
+Successful `search`, `curate`, and `show` commands record usage by default.
+Pass `--no-track-usage` to any of those commands to leave local usage events
+and ranking signals unchanged.
+
 Every runtime writer stamps provenance as `user`, `improve`, `task`, `audit`, or
 `unknown`. Direct interactive CLI traffic defaults to `user`; internal improve,
 scheduled-task, and eval subprocesses preserve their stamp across nested
@@ -167,15 +233,15 @@ use `control: false` and may contain:
 
 Attribution metadata contains fully-qualified refs and graph identifiers, never
 asset bodies or provenance content. It is not added to `search`, `curate`, or
-`show` result payloads, but stored metadata is visible through
-`akm history --detail full`. The full index still applies its existing
+`show` result payloads; there is no CLI surface that reads it back (0.9.0:
+`akm history` was removed). The full index still applies its existing
 higher-priority-wins `(type, entry.name)` dedup across sources: attribution
 source-qualifies every indexed row but does not invent a lower-priority row for
 an identity that production indexing omitted.
 
 ### 3. Proposals Table
 
-The proposal queue: pending, accepted, and rejected improvement proposals for your stash assets. Generated by `akm improve`, `akm propose`, and related proposal-producing flows.
+The proposal queue: pending, accepted, and rejected improvement proposals for your stash assets. Generated by `akm improve`, `akm proposal new`, and related proposal-producing flows.
 
 Contents:
 - Proposal UUID (primary key)
@@ -187,7 +253,7 @@ Contents:
 
 ### 4. Task History Table
 
-A record of scheduled task runs (from `akm tasks`):
+A record of scheduled task runs (from `akm task`):
 - Task ID, status, start/end times
 - Log file path (the log content stays in `$CACHE/tasks/logs/`)
 
@@ -199,16 +265,13 @@ A record of scheduled task runs (from `akm tasks`):
 
 ```sh
 # List recent events
-akm log list
-
-# Stream live events (tail)
-akm log tail
+akm log
 
 # Filter by type
-akm log list --type search --limit 20
+akm log --type search --limit 20
 
 # Filter by asset ref
-akm log list --ref skills/code-review
+akm log --ref skills/code-review
 ```
 
 ### Inspect proposals
@@ -234,8 +297,8 @@ rm -rf ~/.cache/akm/registry/
 rm -rf ~/.cache/akm/config-backups/
 
 # Delete the events log from state.db (non-reversible)
-# There is no akm CLI command to do this directly in 0.8.0.
-# Use SQLite directly:
+# There is no akm CLI command to do this directly (`akm log` only exposes
+# `list`/`tail`, no delete/purge verb). Use SQLite directly:
 sqlite3 ~/.local/share/akm/state.db "DELETE FROM events;"
 
 # Delete all proposals
@@ -264,7 +327,7 @@ You can redirect any AKM directory to a custom path:
 | `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE`. Use `DELETE`/`TRUNCATE` on network filesystems (NFS/SMB) where WAL is impossible. When left at the `WAL` default, akm auto-detects a network FS for the data dir and falls back to `DELETE`. |
 | `AKM_STATE_DIR` | State directory (`~/.local/state/akm/`) |
 | `AKM_CACHE_DIR` | Cache directory (`~/.cache/akm/`) |
-| `AKM_STASH_DIR` | Default stash directory (`~/akm/`) |
+| `AKM_BUNDLE_DIR` | Default stash directory (`~/akm/`) |
 | `XDG_CONFIG_HOME` | XDG base — akm appends `/akm` |
 | `XDG_DATA_HOME` | XDG base — akm appends `/akm` |
 | `XDG_STATE_HOME` | XDG base — akm appends `/akm` |