akm-cli 0.8.7 → 0.8.14

package/CHANGELOG.md

@@ -4,6 +4,434 @@ 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.9.0-beta.3] - 2026-06-12
+
+Stabilization batch closing the remaining 0.9.0 milestone: DB-locking and
+improve-pipeline perf backports, extract/reflect gate fixes, SQLite-first
+proposal and log storage, `--format html` output, and per-stage LLM telemetry.
+
+### Added
+
+- **`--format html` output with per-command templates** (#582). `akm health
+  --format html` renders the full interactive health report (ECharts inlined by
+  default, or via CDN with `AKM_ECHARTS=cdn`); every other command falls back to
+  a dark-mode default template that pretty-prints its JSON. A global `--output
+  <path>` flag writes the rendered HTML to a file instead of stdout. Token
+  replacement only — no template engine. The standalone health-report skill is
+  now folded into core.
+- **Per-stage LLM telemetry** (#576). Every `chatCompletion` call now records
+  tokens (prompt/completion/total/reasoning), wall-time, model, and
+  finish_reason as an `llm_usage` event, attributed to the pipeline stage via an
+  ambient `AsyncLocalStorage` context (`withLlmStage`) set once per phase — no
+  `stage` parameter threaded through call sites. `akm health` exposes per-stage
+  token and time aggregates. Telemetry is best-effort and can never fail a run;
+  capture is forward-only.
+- **Per-proposal gate decision + confidence** (#577). When a proposal passes
+  through the auto-accept/triage gate, its outcome (`auto-accepted` /
+  `deferred` / `auto-rejected`), reason, confidence, measured value, and the
+  thresholds in effect are persisted on the proposal (in the SQLite metadata).
+  `akm proposal show`/`list` surface them with reconstructable comparisons
+  (e.g. `0.72 < 0.90`), so tooling can explain *why* each proposal is pending
+  instead of relying on a run-level aggregate. Forward-only; legacy proposals
+  render `unknown`.
+
+### Fixed
+
+- **`SQLITE_BUSY` / "database is locked" under concurrent runs** (#584, #585,
+  #589). `busy_timeout` raised from 5 s to 30 s on every SQLite open path
+  (index.db and state.db); the improve maintenance pass now closes its index.db
+  handle before each reindex (which opens its own writer to the same WAL file);
+  and the post-loop purge reuses the long-lived events connection instead of
+  opening a second state.db writer. Together these eliminate all observed
+  lock failures from overlapping cron improve runs. (Backports of 0.8.8.)
+- **Extract gate ignored the active profile's `extract.enabled: false`** (#593,
+  #594). The session-extraction gate hardcoded the `default` profile, so a
+  non-default profile (e.g. a quick pass) ran extract anyway — 300–600 s of
+  redundant work per run when a dedicated extract task also exists. The gate
+  now resolves `extract` against the active improve profile. (Backport of
+  0.8.11.)
+- **Memory inference burned LLM calls on already-derived parents** (#588). The
+  primary pass now checks for the `<parent>.derived.md` child on disk *before*
+  the LLM/cache call, and opportunistically marks the parent processed so it
+  never re-pends. Previously ~55 % of the inference budget was spent
+  rediscovering children that already existed.
+- **Reflect no longer queues empty-diff or cosmetic-only proposals** (#580).
+  A deterministic, LLM-free noise gate diffs each candidate against the current
+  asset; byte-identical edits are dropped and changes that are pure formatting
+  (whitespace reflow, hard-wrap changes, code-fence language hints, YAML scalar
+  re-folding) are suppressed, each recorded via summary events so suppression
+  rates are visible in `akm health`.
+
+### Added
+
+- **`minContentChars` pre-LLM extract gate** (#595, #596). Sessions whose raw
+  size is below `profiles.improve.<name>.processes.extract.minContentChars`
+  (default 10 — only truly empty sessions/journal files) skip the extract LLM
+  call entirely. Gates on raw input size, not post-noise-filter size.
+  (Backports of 0.8.12–0.8.14.)
+- **Structured logs database** (#579). Task and run log lines now land in a
+  dedicated `logs.db` (WAL, 30 s busy_timeout) keyed by task, run, stream, and
+  time, with retention/purge wired into the existing purge pass and `ATTACH`
+  support for joining log lines to `state.db` rows (e.g. a failed
+  `task_history` row to its log output). The scattered-log audit and per-source
+  keep/move/drop decisions are documented in `docs/technical/logs-audit.md`.
+
+### Changed
+
+- **Proposals are now stored canonically in SQLite** (#578). The previously
+  bypassed `proposals` table in state.db is the single source of truth; all
+  proposal commands (`list`/`show`/`diff`/`accept`/`reject`/`revert`/`drain`),
+  the improve auto-accept gate, and health metrics read and write it through
+  one storage layer. Pending file-based proposals are imported on first read;
+  `akm proposal *` UX is unchanged. Design and migration notes live in
+  `docs/technical/proposal-storage.md`.
+- **Improve planning no longer does per-ref DB lookups or per-ref skip events**
+  (#591, #592). Eligible refs carry a pre-resolved `filePath`, removing a
+  serial async lookup per ref (~500 s on 9 k-ref stashes), and the
+  profile-filtered skip loop emits one summary event with a count instead of
+  thousands of rows. (Backports of 0.8.9–0.8.10.)
+
+## [0.9.0-beta.2] - 2026-06-09
+
+### Fixed
+
+- **Consolidation starved merge recall; the memory pool grew unbounded.** Commit
+  `633ece41` made the `incrementalSince` narrowing unconditional, so every
+  consolidation run only judged memories changed since the last run plus their
+  immediate vector-neighbors. Stale-but-unmerged duplicate clusters were never
+  re-examined, so the eligible pool grew monotonically and never shrank, and
+  contradiction detection (which rides on the consolidation pass) went dark.
+  Consolidation only runs on the nightly default-profile pass (`quick`/`frequent`
+  disable it), so a full-pool sweep is correct and affordable; the override is
+  removed. `lastConsolidateTs` still gates whether the pass runs. (Forward-port
+  of the 0.8.5 fix.)
+- **`akm tasks sync` ignored schedule changes** — forward-ported from 0.8.4.
+  Sync classified any task already present in the OS scheduler as "unchanged"
+  without comparing its installed entry, so editing a task's `schedule:` in the
+  `.yml` never reached the crontab; the same gap affected `tasks enable`/`disable`
+  (toggled the comment, re-enabling a stale schedule). Sync now compares the
+  backend's installed signature against the signature the current definition
+  renders to and reinstalls on drift (new `updated[]` field); `enable`/`disable`
+  reinstall from the current `.yml`. The cron backend gains `expectedSignature()`
+  and a per-entry signature on `list()`; other backends fall back to an
+  idempotent reinstall.
+
+### Added
+
+- **`akm improve --skip-if-locked`** — forward-ported from 0.8.4. When another
+  improve run already holds the lock, the run logs and exits 0 with a no-op
+  result (`skipped.reason: "lock-held"`) instead of failing with the "already
+  running" config error (exit 78). Intended for high-frequency scheduled runs
+  (e.g. an every-30-min `quick` pass) that overlap a longer run. Default off.
+
+### Removed
+
+- **`akm config edit`** — the interactive menu-based editor was removed. A
+  prompt-driven drill-down was clunkier than just editing the file. Edit the
+  config directly (the path is shown by `akm config path`), use
+  `akm config set/get/unset` for scripted changes, and `akm config validate` to
+  check it.
+
+## [0.9.0-beta.1] - 2026-06-08
+
+### Fixed
+
+- **`improve.lock` leaked on signal death (cron timeout)** — forward-ported from
+  0.8.3. The improve SIGTERM/SIGINT/SIGHUP handler calls `process.exit()`, which
+  skips `finally` blocks, so the `finally` releasing `improve.lock` never ran and
+  every timed-out cron run leaked the lock. It is now released from a
+  `process.on("exit", …)` handler registered at acquire time, via a new
+  ownership-checked `releaseLockIfOwned(path, pid)`.
+- **`quick` profile was not quick** — forward-ported from 0.8.3. It did not
+  disable the default-ON session-`extract` process, so a `quick` run processed
+  the entire session backlog (~40 min). `quick` now sets
+  `processes.extract.enabled: false`.
+- **`akm-eval` smoke suite adapted to the 0.9.0 CLI** (CI/tooling only). The
+  eval harness called `akm search --detail agent`, but 0.9.0 moved the
+  agent/summary projections to `--shape`; it now uses `--shape agent`.
+  Additionally, the improve-run history readers (`listRecentImproveRunIds` /
+  `resolveImproveRunId`) treated a missing `state.db` as an error rather than
+  "no runs", which broke the read-only smoke + replay-determinism gates on a
+  fresh checkout; a missing `state.db` is now handled as an empty history.
+
+## [0.9.0-beta.0] - 2026-06-08
+
+### Added
+
+- **Cross-runtime: akm now runs on Node.js (≥ 20) in addition to Bun** (#560,
+  #465). A two-file runtime boundary (`src/storage/database.ts` owns SQLite via
+  `bun:sqlite` on Bun / `better-sqlite3` on Node; `src/runtime.ts` owns every
+  `Bun.*` API) contains all runtime-specific code, enforced by a lint guard so it
+  cannot leak back out. A CI `node-smoke` matrix runs the built CLI under Node
+  20 and 22. **Minimum Node is 20** — the prompts dependency (`@clack/core`) uses
+  `node:util.styleText`, added in Node 20.12; Node 18 is EOL and unsupported.
+  Bun remains the primary/default runtime.
+- **`session` asset type — agent sessions are now searchable** (#561). The
+  `extract` pass, after distilling memory proposals from a session, additionally
+  writes the session itself as a first-class `session` asset
+  (`sessions/<harness>/<id>.md`) with an LLM-generated `## Summary` /
+  `## Key topics` body plus `harness` / `session_id` / `started_at` / `ended_at`
+  / `project` / `log_path` / `access` frontmatter. Sessions become discoverable
+  via `akm search --type session` and `akm curate`, and the `access` + `log_path`
+  fields tell any agent how to open the raw session log. The behaviour is
+  ADDITIVE, FAIL-OPEN, and config-gated via
+  `profiles.improve.default.processes.extract.indexSessions` (default on when an
+  LLM is configured; set `false` for byte-identical legacy extract behaviour) and
+  `…extract.minSessionDuration` (default 5 minutes). Session assets are not
+  graph-extracted. No new LLM call is made when no provider is configured.
+
+- **`akm env set` / `akm env unset` — single-key `.env` management.** `akm env
+  set <ref> <KEY>` sets/updates one key (value from stdin by default, or
+  `--from-env <VAR>` / `--from-file <path>` — never argv, never echoed); `akm env
+  unset <ref> <KEY...>` removes one or more keys. Both do a minimal edit that
+  preserves existing comments and key order, and use `dotenv` as the
+  serialisation oracle: a value is only written if `dotenv.parse` reads it back
+  exactly, and the whole edit is re-verified so no sibling key is disturbed. This
+  reintroduces key-level management (the deprecated `vault set`/`vault unset`
+  pointed here); `akm env remove` still removes the whole file.
+
+- **`--path` for subdirectory asset creation** (#503) — a consistent `--path
+  <relative-dir>` flag across the asset-creating command surface: `akm remember`,
+  `akm import`, `akm propose`, `akm workflow create`, `akm env create`, and
+  `akm secret set`. `--path` is a directory applied rooted at the asset's type
+  directory (e.g. `akm remember "buy milk" --path personal --name grocery-list`
+  → `memories/personal/grocery-list.md`; `akm workflow create ship --path
+  release` → `workflows/release/ship.md`). The filename/name still comes from the
+  `--name`/name positional (or, for `remember`/`import`, the content/source slug).
+  The explicit name is now a **flat** name everywhere: a `/` in it is rejected
+  with guidance to use `--path`. System-derived names (e.g. a URL-path-derived
+  knowledge name from `akm import <url>`) may still nest. Shared semantics live in
+  `src/core/asset-create.ts`. (Replaces #503's earlier nested-`--name` approach.)
+- **Workflow runs record agent harness + session identity** — `akm workflow start`
+  now persists the agent harness (e.g. `claude-code`, `opencode`) and the
+  platform-native session id that owns each run. Identity is resolved best-effort
+  from the environment (`AKM_AGENT_HARNESS` / `AKM_SESSION_ID`, falling back to the
+  harness-native session env var) or can be passed explicitly to `startWorkflowRun`.
+  Stored via additive migration `002-add-agent-identity` and surfaced on
+  `WorkflowRunSummary.agentHarness` / `.agentSessionId`. This is the first concrete,
+  scoped slice toward workflow session monitoring (#501).
+- **Workflow agent check-in + step-summary validation** (#506) — workflow runs now
+  use a file-signal / command-loop check-in model (no resident background thread, per
+  the ADR in `docs/technical/workflow-agent-checkin-adr.md`). `akm workflow start`
+  arms a durable check-in timestamp; `akm workflow complete --summary` now **requires**
+  a per-step summary and runs it through an LLM completion-criteria validation gate —
+  on failure the step stays pending and structured corrective feedback is returned
+  (`workflow-complete-rejected`). A pure `evaluateCheckin` surfaces a strong `continue`
+  directive through `getNextWorkflowStep` when an active run looks stalled. Migration
+  `002` adds `agent_harness`, `agent_session_id`, `checkin_armed_at` on
+  `workflow_runs` and `summary` on `workflow_run_steps`.
+- **Default improve profiles + scheduled task set** (#552) — three new bundled
+  profiles in `src/assets/profiles/` — `frequent` (extract + inference; distill /
+  consolidate excluded), `consolidate` (consolidation-only), and `catchup` (manual
+  recovery: consolidate + triage drain) — alongside the existing `default` / `quick` /
+  `thorough` / `memory-focus` / `graph-refresh`. `akm setup` and the new `akm tasks
+  init` register a multi-cadence task set **idempotently**: `akm-improve-frequent`
+  (60 min), `akm-improve-consolidate` (4 h), `akm-improve-nightly` (`thorough`, daily
+  2 am, server-gated), `akm-improve-catchup` (registered but unscheduled), and
+  `akm-graph-refresh-weekly` (Sun 3 am). Registration is CI-aware (skips when
+  `CI=true`) and asks a single "Is this a server install?" prompt to gate the nightly
+  task (default yes on Linux-without-battery, no on macOS/laptop).
+
+### Design notes
+
+- **#501 narrowed; superseded by #506 for the monitoring design.** Issue #501
+  ("Add background thread for workflow command session monitoring and agent
+  prompting") was an epic. Per #506's stated preference to avoid always-on
+  background threads/daemons, the background-thread requirement is **not**
+  implemented here. #501 is narrowed to the one tractable, prerequisite sub-feature
+  — persisting harness + session identity on each workflow run — which any future
+  monitor needs regardless of design. The session-monitoring/agent-steering loop is
+  deferred to #506 and requires a separately approved design.
+
+### Changed
+
+- **`improve`: consolidation runs before extract + smarter pool-delta gate**
+  (#551). The consolidation phase now runs **before** the session-extract pass
+  in the improve pipeline. Extract auto-accept writes new memory `.md` files on
+  every run, which previously made the consolidation pool-delta gate
+  (`memoryUpdatedAfterLastConsolidate`) fire unconditionally — consolidation
+  never skipped and wastefully re-judged freshly-promoted single-source
+  memories with no merge/contradiction candidates yet. Running consolidation
+  first means it only ever sees memories from **prior** runs; current-run
+  extract promotions are not on disk yet. The pool-delta gate is additionally
+  narrowed: a memory whose only mtime bump since the last consolidate came from
+  its **own** auto-accept promotion (tracked via the `promoted` event's
+  `assetPath`) is excluded from the "work to do" check, so adjacent-run
+  promotions get a full improve cycle to settle before consolidation considers
+  them. When the gate now correctly skips, the existing
+  `improve_skipped` / `consolidation_no_memory_updates` event is emitted so
+  health reflects it. No event-shape changes; emitted-event order changes only
+  because consolidation moved earlier.
+
+- **Unified git commit model — single batch-at-boundary commit** (#507). Writing
+  or deleting an asset on a git-backed source no longer commits (and optionally
+  pushes) **per asset**. `writeAssetToSource` / `deleteAssetFromSource` now
+  perform a plain filesystem write/unlink for every kind, and git-backed targets
+  are committed **once** at the operation boundary (`akm remember --target`,
+  proposal accept/revert, consolidate) as a single complete commit — `git add -A`
+  stages `.akm/` state + sibling assets together — pushed under the same
+  `writable + remote` gate as `akm save`/`akm sync`. This removes the noisy,
+  incomplete per-asset commits (~25 per improve run) and leaves no dirty
+  working-tree residue.
+
+- **`improve/consolidate`: `minPoolSize` guard** (#553). Consolidation now skips
+  itself when the eligible memory pool is below `processes.consolidate.minPoolSize`
+  (default **500**), emitting a `consolidation_skipped` event with
+  `reason: pool_below_min_size` and making **zero** LLM calls — so the always-enabled
+  consolidate task self-activates only once a stash is large enough to have real
+  merge/contradiction candidates. `minPoolSize: 0` disables the guard. The skip
+  surfaces in `akm health` improve output. The bundled `consolidate` profile sets
+  `500`, `catchup` sets `0`.
+
+- **`improve/extract`: `minNewSessions` gate** (#554). The extract phase now counts
+  in-window, not-yet-seen candidate sessions **before** any LLM call and skips the
+  pass (emitting `extract_skipped` / `reason: below_min_new_sessions`, visible in
+  `akm health`) when the count is below `processes.extract.minNewSessions`. The
+  in-code default is **0 (disabled)**, so existing profiles keep always-run behaviour;
+  only the new `frequent` profile opts in with `3`. This removes the ~22% of improve
+  runs that previously ran the full `ensureIndex` + extract pipeline for zero new
+  sessions.
+
+### Deprecated
+
+- **`options.pushOnCommit`** (#507). The per-asset push-on-commit knob is retired.
+  Existing configs still parse — its push intent is mapped onto the batch push
+  gate and a one-time deprecation warning is emitted when the option is
+  encountered. Remove it and rely on `writable: true` + a configured remote.
+
+### Fixed
+
+- **Memory inference re-queued `hot` parents forever** (#550). `markParentProcessed`
+  was only called when a derived child was newly written; when the child already
+  existed (`written = 0`), the parent never got `inferenceProcessed: true` and was
+  re-queued on every `akm improve` run (~37 wasted LLM calls/run on one production
+  stash). The child-exists path now marks the parent done (a genuine write failure
+  still leaves it unmarked for retry), while `skippedChildExists` accounting is
+  unchanged.
+- **Auto-accept rejected truncated LLM descriptions** (#556). ~9.3% of proposals
+  failed auto-accept validation because the LLM cut the description mid-clause (ending
+  in `to`/`for`/`and`/a comma/etc.) or lost a YAML continuation line. A deterministic
+  post-generation repair pass (`repairTruncatedDescription` in
+  `src/core/text-truncation.ts`) now trims the truncated fragment to the last complete
+  clause or swaps in the first complete sentence from the body — never fabricating
+  text — wired into the extract and distill proposal-write paths before validation.
+  Already-valid descriptions pass through byte-identical. (Plus a one-line prompt
+  tightening requiring a complete sentence.)
+- **Semantic index verification stuck on stashes with vault entries** (#502).
+  Verification compared the stored embedding count against the *full* entry count, but
+  the embedding phase intentionally excludes vault rows — so any index with vault
+  entries reported `embeddingCount < totalEntries` forever and stayed in
+  semantic-blocked / verification-failed state. A new `getEmbeddableEntryCount`
+  (`entry_type != 'vault'`) now feeds the zero-entry short-circuit, the readiness gate,
+  the "Semantic search ready (X/Y)" message, and the persisted `entryCount`; a
+  genuinely missing embedding on an embeddable entry still reports `ok:false`.
+
+### Internal
+
+- **#490 architecture refactor.** Decomposed `src/cli.ts` from **4,589 → 620 LOC**
+  across 16 per-family command modules under `src/commands/*-cli.ts` (adopting a
+  `defineJsonCommand` factory for byte-identical JSON envelopes); converted `akm
+  health` checks to an ordered `HealthCheck` registry; and turned the
+  `migrate-storage` bin's 54 hand-rolled `recordStep` sites into a `MigrationStep`
+  registry with 3 recursive copy helpers unified into one `copyTree`. Shipped as
+  serialized local merges with a zero-behaviour-change contract (byte-identical CLI
+  surface + JSON envelopes), each gated and reviewed; the secret-migrating
+  `migrate-storage` change is pinned by a sha256 + file-mode fixture-stash
+  differential test.
+
+## [0.8.14] - 2026-06-11
+
+### Fixed
+
+- **`akm extract` minContentChars default lowered from 500 to 10.** The 500-char
+  threshold used inputCount (raw session size) but analysis showed 209 of 218
+  candidate-producing sessions had inputCount < 500 — tiny agent sessions (22–368
+  chars) regularly yield 1–5 candidates. The only reliably skippable sessions are
+  empty ones (0 chars, journal files). Default lowered to 10 to catch only
+  truly empty sessions while preserving all signal-bearing content. Closes #597.
+
+## [0.8.13] - 2026-06-11
+
+### Fixed
+
+- **`akm extract` minContentChars gate filtered all sessions.** The threshold was
+  checked against `filtered.stats.outputCount` (post-noise-filter chars), but the
+  pre-filter strips so much boilerplate that even signal-bearing sessions end up
+  below 500 chars of output. All 75 sessions in the first post-deploy run were
+  filtered, dropping candidates from 4–13 to 0. Fix: gate on `inputCount` (raw
+  session size) instead — a session with < 500 raw chars has nothing worth
+  extracting regardless of what the pre-filter produces. Closes #596.
+
+## [0.8.12] - 2026-06-11
+
+### Fixed
+
+- **`akm extract` calling the LLM for noise sessions that never yield candidates.**
+  96% of processed sessions (72/75 measured) produced zero candidates, consuming
+  ~330 s of LLM time per run. The pre-filter had no minimum content threshold —
+  sessions as short as 50 chars were sent to the LLM regardless. A new
+  `minContentChars` gate (default 500) skips the LLM call when post-filter
+  content falls below threshold, cutting extract LLM calls by ~95% on typical
+  stashes. Configurable via `profiles.improve.<name>.processes.extract.minContentChars`.
+  Closes #595.
+
+## [0.8.11] - 2026-06-11
+
+### Fixed
+
+- **`akm improve --profile <name>` ignored profile's `extract.enabled: false` setting.**
+  The session-extraction gate in the preparation stage called
+  `isLlmFeatureEnabled(config, "session_extraction")`, which hardcodes a lookup
+  against `profiles.improve.default.processes.extract.enabled`. Any non-default
+  profile that set `extract.enabled: false` (e.g. `quick-shredder`) was silently
+  ignored, causing the extract pass to run regardless. The fix adds a
+  `resolveProcessEnabled("extract", improveProfile)` check so the active
+  resolved profile gates the pass correctly. Closes #593.
+
+## [0.8.10] - 2026-06-11
+
+### Fixed
+
+- **`akm improve` taking 8–10 minutes per run due to O(n) DB writes for
+  profile-filtered refs.** When a profile disables reflect and distill for
+  certain asset types, `collectEligibleRefs` marks those refs as
+  `profile_filtered_all_passes`. The caller then emitted one `improve_skipped`
+  event per ref — a sequential DB write for each. On a ~9 000-ref stash this
+  was ~500 s of SQLite writes before any consolidation or memory inference
+  began. The fix collapses the per-ref loop into a single summary event
+  carrying a `count` field, eliminating ~9 000 sequential writes per run.
+  Closes #590.
+
+## [0.8.9] - 2026-06-11
+
+### Fixed
+
+- **`akm improve` validation pass was O(n) in stash size, causing ~510 s overhead
+  on large stashes.** For every indexed ref, the preparation phase called
+  `findAssetFilePath()` — an async round-trip to the index DB followed by a
+  filesystem probe — serially inside a `for…await` loop. With ~9 000 indexed
+  refs at ~55 ms each, this loop consumed the entire 600–900 s run budget before
+  any reflect, triage, or memory-inference work began. The fix threads
+  `filePath` from the planning stage (`collectEligibleRefs`) through
+  `ImproveEligibleRef` so the validation pass and the disk-existence guard can
+  use the pre-resolved path directly. The async lookup is retained only as a
+  fallback for refs that enter via a narrow scope (e.g. `--scope ref:foo`).
+  Closes #587.
+
+## [0.8.8] - 2026-06-11
+
+### Fixed
+
+- **SQLite `SQLITE_BUSY` errors under concurrent improve runs.** `busy_timeout`
+  was set to 5 000 ms in all three database open paths (`openDatabase`,
+  `openExistingDatabase`, `openStateDatabase`). Under a busy cron schedule — or
+  when a reindex triggered by memory inference ran concurrently with an event
+  write — the 5 s window was routinely exhausted, producing "database is locked"
+  failures. Raised to 30 000 ms across all three paths so transient lock
+  contention is retried for up to 30 s before surfacing as an error.
+
 ## [0.8.7] - 2026-06-09
 
 ### Fixed

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

@@ -4,8 +4,7 @@ Usage:
 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.)
+  (The flat `akm proposals` alias was removed in 0.9.0 — use `akm proposal list`.)
 
 Options:
   --status <status>    Filter by pending, accepted, or rejected

package/dist/assets/hints/cli-hints-full.md

@@ -22,7 +22,6 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 | `--format` | `json`, `jsonl`, `text`, `yaml` | `json` |
 | `--detail` | `brief`, `normal`, `full` | `brief` |
 | `--shape` | `human`, `agent`, `summary` (`summary` only on `show`) | `human` |
-| `--for-agent` | boolean (deprecated — use `--shape agent`) | `false` |
 
 ## Curate
 
@@ -59,7 +58,8 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | knowledge | `content` (with view modes: `full`, `toc`, `frontmatter`, `section`, `lines`) |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
-| vault | `keys`, `comments` |
+| env | `keys`, `comments` (key names + comments only — values never returned) |
+| secret | `name` only (the whole file is the value — never returned) |
 | wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list`. To ingest sources, `akm wiki ingest <name>` dispatches the configured agent (defaults.agent or `--profile`) to execute the ingest workflow. |
 
 ## Capture Knowledge While You Work
@@ -78,7 +78,7 @@ akm workflow next workflow:ship-release        # Start or resume the next workfl
 akm feedback skill:code-review --positive      # Record that an asset helped
 akm feedback agent:reviewer --negative         # Record that an asset missed the mark
 akm feedback memory:deployment-notes --positive # Works for memories too
-akm feedback vault:prod --positive             # Records vault feedback without surfacing values
+akm feedback env:prod --positive               # Records env feedback without surfacing values
 ```
 
 Use `akm feedback` whenever an asset materially helps or fails so future search
@@ -119,20 +119,37 @@ page create/update, log entry, lint, reindex.** Wiki pages are also addressable
 `schema.md`, `index.md`, and `log.md` are not indexed and do not appear in
 search results. No `--llm` anywhere — akm never reasons about page content.
 
-## Vaults
+## Env files
 
-Encrypted-at-rest key/value stores for secrets. Each vault is a `.env`-format
-file at `<stashDir>/vaults/<name>.env`.
+A group of related CONFIGURATION for an app/service in one `.env` file at
+`<stashDir>/env/<name>.env`, sourced/injected wholesale. Key names + comments
+are discoverable; values stay on disk and never reach stdout or the index. akm
+does not edit entries — you edit the file with your own editor and akm loads it.
 
 ```sh
-akm vault create prod                         # Create a new vault
-akm vault set prod DB_URL postgres://...      # Set a key (or KEY=VALUE combined form)
-akm vault set prod DB_URL=postgres://...      # Combined KEY=VALUE form also works
-akm vault unset prod DB_URL                   # Remove a key
-akm vault list                                # List all vaults across all stashes with key names
-akm vault path vault:prod                     # Print the vault file path for shell loading
-akm vault run vault:prod -- env               # Run one command with all vault vars injected
-akm vault run vault:prod/DB_URL -- printenv DB_URL # Inject one key for one command
+akm env create prod                           # Create an empty env file
+akm env create prod --from-file ./.env        # Ingest an existing .env
+akm env list                                  # List all env files across stashes with key names
+akm show env:prod                             # Inspect key names + comments (never values)
+akm env run env:prod -- ./deploy.sh           # Run a command with the whole .env injected (the safe path)
+akm env run env:prod -- $SHELL                # Open an interactive shell with values injected
+akm env export env:prod --out ./env.sh        # Write a sourceable script to a file (mode 0600)
+akm env path env:prod --quiet                 # Print the raw file path (for Docker `_FILE` / `--env-file`)
+akm env remove env:prod                       # Delete the env file
+```
+
+## Secrets
+
+A single sensitive value used on its own for authentication (a token, key, or
+cert) — one file = one value at `<stashDir>/secrets/<name>`. The ENTIRE file is
+the value; only the name is ever surfaced.
+
+```sh
+printf '%s' "$TOKEN" | akm secret set secret:deploy-token   # Store a single value
+akm secret list                                             # List secrets (names only)
+akm secret path secret:deploy-token                         # Print the file path (Docker `_FILE`)
+akm secret run secret:deploy-token GITHUB_TOKEN -- gh release create v1.0.0  # Inject into one env var
+akm secret remove secret:deploy-token                       # Delete the secret
 ```
 
 ## Workflows
@@ -171,8 +188,7 @@ When `--dest` is provided, `akm init` is not required first.
 ## Sync
 
 Commit local changes in a git-backed stash. Behaviour adapts automatically.
-(`akm save` is the deprecated 0.7 spelling — it still works but warns; removed
-in 0.9.0.)
+(`akm save` was the pre-0.8 spelling; it was removed in 0.9.0 — use `akm sync`.)
 
 - **No `.git` directory** — no-op (silent skip)
 - **Git repo, no remote** — stage and commit only (the default stash always falls here)
@@ -279,8 +295,8 @@ akm proposal revert <id>                                # Restore the pre-promot
 ```
 
 The flat verbs `akm proposals` / `akm show proposal` / `akm accept` /
-`akm reject` / `akm diff` / `akm revert` still work as deprecated aliases
-(warn on stderr; removed in 0.9.0).
+`akm reject` / `akm diff` / `akm revert` were removed in 0.9.0 — use the
+`akm proposal <verb>` forms above.
 
 Per-task `timeoutMs`: task markdown frontmatter may set `timeoutMs: null` to
 disable the agent kill timer for long-running local-model tasks, or a number
@@ -300,6 +316,5 @@ All commands accept `--format`, `--detail`, and `--shape` flags:
 - `--shape human` (default) — standard projection
 - `--shape agent` — agent-optimized output: strips non-actionable fields
 - `--shape summary` — metadata only (no content/template/prompt), under 200 tokens; only valid on `akm show`
-- `--for-agent` — deprecated alias for `--shape agent` (removed 0.9.0)
 
 Run `akm -h` or `akm <command> -h` for per-command help.

package/dist/assets/hints/cli-hints-short.md

@@ -58,7 +58,7 @@ akm registry search "<query>"                 # Search all registries
 | knowledge | A reference doc (use `toc` or `section "..."` to navigate) |
 | workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
-| env | A `.env` file of related CONFIGURATION (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). `vault` is the deprecated alias. |
+| env | A `.env` file of related CONFIGURATION (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |
 | secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Use `akm secret path` / `akm secret run`. |
 | wiki | A page in a multi-wiki knowledge base. For any wiki task, start with `akm wiki list`. To ingest sources, run `akm wiki ingest <name>` — it dispatches the configured agent profile to execute the ingest workflow against the wiki's `raw/` directory. Run `akm wiki -h` for the full surface. |
 

package/dist/assets/profiles/catchup.json

@@ -0,0 +1,13 @@
+{
+  "description": "Manual catch-up — consolidation + triage drain with no interval minimum.",
+  "processes": {
+    "reflect": { "enabled": false },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": true, "allowedTypes": ["memory"], "maxChunkSize": 50, "minPoolSize": 0 },
+    "memoryInference": { "enabled": false },
+    "graphExtraction": { "enabled": false },
+    "extract": { "enabled": false },
+    "triage": { "enabled": true, "applyMode": "queue", "policy": "personal-stash", "maxAcceptsPerRun": 100 }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/profiles/consolidate.json

@@ -0,0 +1,13 @@
+{
+  "description": "Consolidation-only pass — merges, deduplicates, and prunes memories every 4h.",
+  "processes": {
+    "reflect": { "enabled": false },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": true, "allowedTypes": ["memory"], "maxChunkSize": 25, "minPoolSize": 500 },
+    "memoryInference": { "enabled": false },
+    "graphExtraction": { "enabled": false },
+    "extract": { "enabled": false },
+    "triage": { "enabled": false }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/profiles/frequent.json

@@ -0,0 +1,13 @@
+{
+  "description": "Frequent extract + inference pass — sessions, memory inference, graph, reflect.",
+  "processes": {
+    "reflect": { "enabled": true },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": false },
+    "memoryInference": { "enabled": true },
+    "graphExtraction": { "enabled": true },
+    "extract": { "enabled": true, "minNewSessions": 3 },
+    "triage": { "enabled": false }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/tasks/core/backup.yml

@@ -0,0 +1,4 @@
+schedule: "0 3 * * 0"
+command: akm db backups
+enabled: true
+description: Weekly config/DB backup

package/dist/assets/tasks/core/extract.yml

@@ -0,0 +1,4 @@
+schedule: "*/30 * * * *"
+command: akm extract
+enabled: true
+description: Extract insights from session files every 30 min

package/dist/assets/tasks/core/improve.yml

@@ -0,0 +1,4 @@
+schedule: "0 2 * * *"
+command: akm improve --auto-accept safe
+enabled: true
+description: Run improve pipeline nightly

package/dist/assets/tasks/core/index-refresh.yml

@@ -0,0 +1,4 @@
+schedule: "0 4 * * *"
+command: akm index
+enabled: true
+description: Nightly incremental index refresh

package/dist/assets/tasks/core/sync.yml

@@ -0,0 +1,4 @@
+schedule: "*/15 * * * *"
+command: akm sync
+enabled: true
+description: Sync stash changes to git remote every 15 min

package/dist/assets/tasks/core/update-stashes.yml

@@ -0,0 +1,4 @@
+schedule: "0 1 * * *"
+command: akm update
+enabled: true
+description: Pull latest changes for all managed stash sources

package/dist/assets/tasks/core/version-check.yml

@@ -0,0 +1,4 @@
+schedule: "0 9 * * 1"
+command: akm info --check-version
+enabled: true
+description: Weekly check for new akm releases