akm-cli 0.7.5 → 0.8.0-rc.11

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

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

package/README.md

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

package/SECURITY.md

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

package/dist/cli/config-migrate.js

@@ -0,0 +1,144 @@
+// 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/.
+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";
+const PROJECT_CONFIG_RELATIVE_PATH = path.join(".akm", "config.json");
+function backupConfigFile(configPath) {
+    if (!fs.existsSync(configPath))
+        return;
+    const backupDir = path.join(getCacheDir(), "config-backups");
+    fs.mkdirSync(backupDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
+    const backupPath = path.join(backupDir, `config-${timestamp}.json`);
+    fs.copyFileSync(configPath, backupPath);
+    const latestPath = path.join(backupDir, "config.latest.json");
+    fs.copyFileSync(configPath, latestPath);
+}
+function acquireMigrateLock(lockPath, noWait) {
+    const lockDir = path.dirname(lockPath);
+    fs.mkdirSync(lockDir, { recursive: true });
+    const maxAttempts = noWait ? 1 : 20;
+    const delayMs = 200;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            fs.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+            return () => {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // ignore
+                }
+            };
+        }
+        catch {
+            if (noWait) {
+                return null;
+            }
+            // Simple busy-wait — synchronous since this is a one-shot CLI action
+            const deadline = Date.now() + delayMs;
+            while (Date.now() < deadline) {
+                // spin
+            }
+        }
+    }
+    return null;
+}
+export async function migrateConfigFile(filePath, opts) {
+    if (!fs.existsSync(filePath)) {
+        return { changed: false, result: {} };
+    }
+    const text = fs.readFileSync(filePath, "utf8");
+    let raw;
+    try {
+        const stripped = stripJsonComments(text);
+        const parsed = JSON.parse(stripped);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            warn(`[akm] config-migrate: ${filePath} is not a valid JSON object, skipping.`);
+            return { changed: false, result: {} };
+        }
+        raw = parsed;
+    }
+    catch {
+        warn(`[akm] config-migrate: failed to parse ${filePath}, skipping.`);
+        return { changed: false, result: {} };
+    }
+    const { changed, result } = migrateConfigShape(raw);
+    if (!changed) {
+        return { changed: false, result };
+    }
+    const migratedText = `${JSON.stringify(result, null, 2)}\n`;
+    // WS-2: compute a diff when requested (always computed for --print-diff;
+    // never requires a write so safe in --dry-run).
+    const diff = opts.printDiff ? unifiedDiff(text, migratedText, filePath) : undefined;
+    if (opts.dryRun) {
+        return { changed: true, result, diff };
+    }
+    // WS-3: acquire config write lock + use atomic write (tmp → rename).
+    withConfigLock(() => {
+        backupConfigFile(filePath);
+        writeConfigAtomic(filePath, result);
+    });
+    return { changed: true, result, diff };
+}
+function discoverProjectConfigPaths(startDir) {
+    const paths = [];
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const configPath = path.join(currentDir, PROJECT_CONFIG_RELATIVE_PATH);
+        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
+            paths.unshift(configPath);
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            break;
+        currentDir = parentDir;
+    }
+    return paths;
+}
+export async function runConfigMigrate(opts) {
+    const userConfigPath = getConfigPath();
+    const projectPaths = discoverProjectConfigPaths(process.cwd());
+    const allPaths = [userConfigPath, ...projectPaths].filter((p, i, arr) => arr.indexOf(p) === i && fs.existsSync(p));
+    if (allPaths.length === 0) {
+        console.log("No config files found to migrate.");
+        return;
+    }
+    const lockPath = path.join(getCacheDir(), "config-migrate.lock");
+    const releaseLock = acquireMigrateLock(lockPath, opts.noWait ?? false);
+    if (!releaseLock) {
+        warn("[akm] config-migrate: another migration is already in progress, skipping.");
+        return;
+    }
+    try {
+        let anyChanged = false;
+        for (const filePath of allPaths) {
+            const { changed, diff } = await migrateConfigFile(filePath, { dryRun: opts.dryRun, printDiff: opts.printDiff });
+            if (changed) {
+                const action = opts.dryRun ? "would migrate" : "migrated";
+                console.log(`[akm] ${action}: ${filePath}`);
+                // WS-2: print the unified diff to stdout when --print-diff is set.
+                if (diff) {
+                    console.log(diff);
+                }
+                anyChanged = true;
+            }
+            else {
+                console.log(`[akm] already up to date: ${filePath}`);
+            }
+        }
+        if (!anyChanged) {
+            console.log("All config files are already at the current version.");
+        }
+    }
+    finally {
+        releaseLock();
+    }
+}

package/dist/cli/config-validate.js

@@ -0,0 +1,39 @@
+// 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/.
+/**
+ * `akm config validate` — verify the on-disk config matches the schema.
+ *
+ * Reads the user config file, validates against AkmConfigSchema, and either
+ * prints "All checks passed." or a list of structured errors (path + message).
+ * 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";
+export async function runConfigValidate() {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) {
+        console.log(`No config file at ${configPath} — nothing to validate.`);
+        return;
+    }
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new ConfigError(`Could not read config at ${configPath}: ${detail}`, "INVALID_CONFIG_FILE");
+    }
+    // parseConfigText throws ConfigError on malformed JSON (#458). Surface as-is.
+    const raw = parseConfigText(text, configPath);
+    const result = validateConfigShape(raw);
+    if (result.ok) {
+        console.log(`All checks passed. (${configPath})`);
+        return;
+    }
+    const lines = result.errors.map((e) => `  - ${e.path || "(root)"}: ${e.message}`).join("\n");
+    throw new ConfigError(`Config at ${configPath} has ${result.errors.length} validation error${result.errors.length === 1 ? "" : "s"}:\n${lines}`, "INVALID_CONFIG_FILE", "Fix the listed fields, or run `akm config migrate` if the errors look like legacy-shape leftovers.");
+}

package/dist/cli/confirm.js

@@ -0,0 +1,73 @@
+// 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/.
+/**
+ * Confirmation helper for destructive CLI commands.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { confirmDestructive } from "../cli/confirm";
+ *
+ * async function run({ args }) {
+ *   const yes = await confirmDestructive(
+ *     `Remove source "${args.target}"? This cannot be undone.`,
+ *     { yes: args.yes === true }
+ *   );
+ *   if (!yes) { console.error("Aborted."); return; }
+ *   // proceed...
+ * }
+ * ```
+ *
+ * ## Non-TTY policy
+ *
+ * In non-interactive contexts (stdin is not a TTY), destructive commands
+ * **fail by default** and require explicit `--yes` to proceed. This prevents
+ * 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
+ * recovered after deletion, so the cost of requiring `--yes` in scripts is
+ * low and the cost of accidental deletion is high.
+ *
+ * ## Safety exemptions
+ *
+ * `--quiet` NEVER suppresses the confirmation prompt — it is safety-critical
+ * output. The auto-migration banner is similarly exempt from `--quiet`.
+ */
+import * as p from "@clack/prompts";
+import { UsageError } from "../core/errors";
+/**
+ * Prompt the user to confirm a destructive action.
+ *
+ * Returns `true` if the user confirmed (or `--yes` was passed).
+ * Returns `false` if the user declined.
+ * Throws `UsageError("NON_INTERACTIVE_REQUIRES_YES")` when stdin is not a
+ * TTY and `--yes` was not passed — callers should propagate this error.
+ *
+ * The prompt defaults to NO so accidental Enter presses do not proceed.
+ *
+ * @param message  Human-readable description of what will be destroyed.
+ * @param opts     Options controlling confirmation behaviour.
+ */
+export async function confirmDestructive(message, opts) {
+    // --yes always skips the prompt
+    if (opts.yes)
+        return true;
+    // Non-TTY: fail loudly — require explicit --yes in scripts
+    const isInteractive = process.stdin.isTTY === true;
+    if (!isInteractive) {
+        throw new UsageError(`This command requires confirmation in non-interactive mode. Pass --yes / -y to proceed without prompting.\n\nAction: ${message}`, "NON_INTERACTIVE_REQUIRES_YES");
+    }
+    // Interactive: prompt with default = NO (false)
+    const confirmed = await p.confirm({
+        message,
+        initialValue: false,
+    });
+    // p.confirm returns a symbol when the user cancels (Ctrl+C)
+    if (p.isCancel(confirmed)) {
+        p.outro("Cancelled.");
+        process.exit(0);
+    }
+    return confirmed === true;
+}