akm-cli 0.8.3 → 0.9.0-beta.1

package/CHANGELOG.md

@@ -4,6 +4,215 @@ 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.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.3] - 2026-06-08
 
 ### 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

package/dist/cli/config-migrate.js

@@ -3,12 +3,12 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { stripJsonComments } from "../core/config";
-import { unifiedDiff, withConfigLock, writeConfigAtomic } from "../core/config-io";
-import { migrateConfigShape } from "../core/config-migration";
-import { getCacheDir, getConfigPath } from "../core/paths";
-import { warn } from "../core/warn";
-export { migrateConfigShape } from "../core/config-migration";
+import { stripJsonComments } from "../core/config/config.js";
+import { unifiedDiff, withConfigLock, writeConfigAtomic } from "../core/config/config-io.js";
+import { migrateConfigShape } from "../core/config/config-migration.js";
+import { getCacheDir, getConfigPath } from "../core/paths.js";
+import { warn } from "../core/warn.js";
+export { migrateConfigShape } from "../core/config/config-migration.js";
 const PROJECT_CONFIG_RELATIVE_PATH = path.join(".akm", "config.json");
 function backupConfigFile(configPath) {
     if (!fs.existsSync(configPath))

package/dist/cli/config-validate.js

@@ -9,10 +9,10 @@
  * Exits non-zero on errors so it composes well in CI hooks.
  */
 import fs from "node:fs";
-import { parseConfigText } from "../core/config-io";
-import { validateConfigShape } from "../core/config-schema";
-import { ConfigError } from "../core/errors";
-import { getConfigPath } from "../core/paths";
+import { parseConfigText } from "../core/config/config-io.js";
+import { validateConfigShape } from "../core/config/config-schema.js";
+import { ConfigError } from "../core/errors.js";
+import { getConfigPath } from "../core/paths.js";
 export async function runConfigValidate() {
     const configPath = getConfigPath();
     if (!fs.existsSync(configPath)) {

package/dist/cli/confirm.js

@@ -7,7 +7,7 @@
  * ## Usage
  *
  * ```ts
- * import { confirmDestructive } from "../cli/confirm";
+ * import { confirmDestructive } from "../cli/confirm.js";
  *
  * async function run({ args }) {
  *   const yes = await confirmDestructive(
@@ -26,7 +26,7 @@
  * accidental destruction in scripts that forget to pass `-y`.
  *
  * This is intentionally stricter than many CLIs that silently proceed in
- * non-TTY mode. The rationale: vault keys, sources, and proposals cannot be
+ * non-TTY mode. The rationale: secrets, sources, and proposals cannot be
  * recovered after deletion, so the cost of requiring `--yes` in scripts is
  * low and the cost of accidental deletion is high.
  *
@@ -36,7 +36,7 @@
  * output. The auto-migration banner is similarly exempt from `--quiet`.
  */
 import * as p from "@clack/prompts";
-import { UsageError } from "../core/errors";
+import { UsageError } from "../core/errors.js";
 /**
  * Prompt the user to confirm a destructive action.
  *

package/dist/cli/parse-args.js

@@ -7,7 +7,7 @@
  * These were extracted from `src/cli.ts` to eliminate repetition and keep the
  * main CLI file focused on command definitions and routing.
  */
-import { UsageError } from "../core/errors";
+import { UsageError } from "../core/errors.js";
 // ── Subcommand detection ─────────────────────────────────────────────────────
 /**
  * Return true when `args._[0]` is a member of `validSet`.

package/dist/cli/shared.js

@@ -7,11 +7,13 @@
  *
  * Exported: output, runWithJsonErrors, parseAllFlagValues, emitJsonError
  */
+import { defineCommand } from "citty";
 import { stringify as yamlStringify } from "yaml";
-import { ConfigError, NotFoundError, UsageError } from "../core/errors";
-import { getOutputMode } from "../output/context";
-import { shapeForCommand } from "../output/shapes";
-import { formatPlain, outputJsonl } from "../output/text";
+import { assertNever } from "../core/assert.js";
+import { AkmError } from "../core/errors.js";
+import { getOutputMode } from "../output/context.js";
+import { shapeForCommand } from "../output/shapes.js";
+import { formatPlain, outputJsonl } from "../output/text.js";
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -22,6 +24,7 @@ import { formatPlain, outputJsonl } from "../output/text";
  *   1  general / not-found
  *   2  usage error
  *   4  health warn (health command only)
+ *  70  internal / unclassified (sysexits EX_SOFTWARE — akm threw unexpectedly)
  *  78  config error
  */
 export const EXIT_CODES = {
@@ -29,17 +32,35 @@ export const EXIT_CODES = {
     GENERAL: 1,
     USAGE: 2,
     HEALTH_WARN: 4,
+    // sysexits.h EX_SOFTWARE. Distinct from GENERAL(1) so scripts can tell an
+    // expected "not found" outcome from akm itself throwing an unexpected error.
+    INTERNAL: 70,
     CONFIG: 78,
 };
 // ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Map a thrown value to a process exit code.
+ *
+ * Known, classified errors (instances of `AkmError`) are dispatched through an
+ * exhaustive switch on the `kind` discriminant — `assertNever` makes a missing
+ * case a compile-time error, so adding a new error class can't silently inherit
+ * the wrong code. Anything that is NOT an `AkmError` is treated as a genuinely
+ * unexpected internal failure and maps to INTERNAL(70) rather than GENERAL(1),
+ * so callers can distinguish "akm threw" from a normal not-found outcome.
+ */
 function classifyExitCode(error) {
-    if (error instanceof UsageError)
-        return EXIT_CODES.USAGE;
-    if (error instanceof ConfigError)
-        return EXIT_CODES.CONFIG;
-    if (error instanceof NotFoundError)
-        return EXIT_CODES.GENERAL;
-    return EXIT_CODES.GENERAL;
+    if (!(error instanceof AkmError))
+        return EXIT_CODES.INTERNAL;
+    switch (error.kind) {
+        case "usage":
+            return EXIT_CODES.USAGE;
+        case "config":
+            return EXIT_CODES.CONFIG;
+        case "not-found":
+            return EXIT_CODES.GENERAL;
+        default:
+            return assertNever(error.kind, "classifyExitCode");
+    }
 }
 function extractHint(error) {
     if (error instanceof Error && "hint" in error && typeof error.hint === "function") {
@@ -55,9 +76,9 @@ export function emitJsonError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const hint = extractHint(error);
     const exitCode = classifyExitCode(error);
-    const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
-        ? error.code
-        : undefined;
+    // Classified akm errors carry a stable machine-readable `code`; unexpected
+    // internal errors have none.
+    const code = error instanceof AkmError ? error.code : undefined;
     console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
     process.exit(exitCode);
 }
@@ -73,6 +94,22 @@ export async function runWithJsonErrors(fn) {
         emitJsonError(error);
     }
 }
+/**
+ * Define a citty command whose `run` body is automatically wrapped in
+ * `runWithJsonErrors`, so the handler emits a byte-identical JSON error
+ * envelope (stdout/stderr/exit-code) on throw without the boilerplate. A
+ * command without a `run` (a pure subcommand group) is passed through
+ * unchanged.
+ */
+export function defineJsonCommand(def) {
+    const { run, ...rest } = def;
+    if (!run)
+        return defineCommand({ ...rest });
+    return defineCommand({
+        ...rest,
+        run: (context) => runWithJsonErrors(() => run(context)),
+    });
+}
 /**
  * Render a command result according to the active output mode (json/jsonl/yaml/text).
  */

package/dist/cli-node.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// Node entry wrapper for akm.
+//
+// The primary entry `dist/cli.js` carries a `#!/usr/bin/env bun` shebang and,
+// when run under Node, relies on a text-import loader hook for its embedded
+// `.md`/`.xml` assets (Bun loads those natively; Node needs a hook). Those
+// imports are static and hoisted, so the hook MUST be registered before the
+// module graph is evaluated — i.e. before `cli.js` is imported. This wrapper
+// does exactly that: register the hook, then dynamically import the real CLI.
+//
+// Bun users never touch this file; it exists solely so `node dist/cli-node.mjs`
+// (and the `test:node-smoke` script / Node CI matrix) can run akm end-to-end.
+
+import { register } from "node:module";
+
+register("./text-import-hook.mjs", import.meta.url);
+
+// cli.js gates its startup block on `import.meta.main`, which is false when we
+// `import()` it here. Opt in explicitly so the CLI actually runs `runMain`.
+process.env.AKM_NODE_ENTRY = "1";
+
+await import("./cli.js");