akm-cli 0.8.0-rc2 → 0.8.1

package/dist/{output → assets/hints}/cli-hints-full.md

@@ -16,12 +16,13 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 
 | Flag | Values | Default |
 | --- | --- | --- |
-| `--type` | `skill`, `command`, `agent`, `knowledge`, `workflow`, `script`, `memory`, `vault`, `wiki`, `any` | `any` |
+| `--type` | `skill`, `command`, `agent`, `knowledge`, `workflow`, `script`, `memory`, `env`, `secret`, `wiki`, `any` | `any` |
 | `--source` | `stash`, `registry`, `both` | `stash` |
 | `--limit` | number | `20` |
 | `--format` | `json`, `jsonl`, `text`, `yaml` | `json` |
-| `--detail` | `brief`, `normal`, `full`, `summary`, `agent` | `brief` |
-| `--for-agent` | boolean (deprecated — use `--detail agent`) | `false` |
+| `--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 +60,7 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
 | vault | `keys`, `comments` |
-| wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list` then `akm wiki ingest <name>` for the workflow. |
+| 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
 
@@ -102,13 +103,17 @@ akm wiki stash research https://example.com/paper # Fetch one URL into raw/<slug
 akm wiki stash research ./paper.md --target my-stash # Route write to a named writable stash source
 echo "..." | akm wiki stash research -         # stdin form
 akm wiki lint research                         # Structural checks: orphans, broken xrefs, uncited raws, stale index
-akm wiki ingest research                       # Print the ingest workflow for this wiki (no action)
-akm wiki remove research --force               # Delete pages/schema/index/log; preserves raw/
-akm wiki remove research --force --with-sources # Full nuke, including raw/
+akm wiki ingest research                       # Dispatch defaults.agent to run the ingest workflow on this wiki
+akm wiki ingest research --profile claude --model sonnet  # Override profile and model
+akm wiki ingest research --timeout-ms 600000   # Override agent CLI timeout (default: profile setting)
+akm wiki remove research -y                    # Delete pages/schema/index/log; preserves raw/ (--force is a deprecated alias for -y)
+akm wiki remove research -y --with-sources     # Full nuke, including raw/
 ```
 
-**For any wiki task, start with `akm wiki list`, then `akm wiki ingest <name>`
-to get the step-by-step workflow.** Wiki pages are also addressable as
+**For any wiki task, start with `akm wiki list`. Then `akm wiki ingest <name>`
+dispatches the configured agent (defaults.agent or `--profile`) to execute
+the wiki's ingest workflow end-to-end — schema read, source dedup, search,
+page create/update, log entry, lint, reindex.** Wiki pages are also addressable as
 `wiki:<name>/<page-path>` and show up in stash-wide `akm search` as
 `type: wiki`. Files under `raw/` and the wiki root infrastructure files
 `schema.md`, `index.md`, and `log.md` are not indexed and do not appear in
@@ -163,23 +168,40 @@ akm clone "npm:@scope/pkg//script:deploy.sh"  # Clone from remote package
 
 When `--dest` is provided, `akm init` is not required first.
 
-## Save
+## Sync
 
-Commit local changes in a git-backed stash. Behaviour adapts automatically:
+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.)
 
-- **Not a git repo** — no-op (silent skip)
+- **No `.git` directory** — no-op (silent skip)
 - **Git repo, no remote** — stage and commit only (the default stash always falls here)
 - **Git repo, has remote, not writable** — stage and commit only
 - **Git repo, has remote, `writable: true`** — stage, commit, and push
+- **Any writable repo with `--no-push`** — stage and commit only
 
 ```sh
-akm save                                      # Save primary stash (timestamp message)
-akm save -m "Add deploy skill"               # Save with explicit message
-akm save my-skills                            # Save a named writable git stash
-akm save my-skills -m "Update patterns"      # Save named stash with message
+akm sync                                      # Sync primary stash (timestamp message)
+akm sync -m "Add deploy skill"               # Sync with explicit message
+akm sync --no-push                            # Commit only; never push
+akm sync my-skills                            # Sync a named writable git stash
+akm sync my-skills -m "Update patterns"      # Sync named stash with message
 ```
 
-The `--writable` flag on `akm add` opts a remote git stash into push-on-save:
+`akm improve` also performs an end-of-run batch commit for git-backed stashes.
+The `--sync` / `--no-sync` and `--push` / `--no-push` flags control this:
+
+```sh
+akm improve                                   # auto-sync per profile default (default/thorough: on; quick/memory-focus: off)
+akm improve --no-sync                         # skip the end-of-run commit
+akm improve --no-push                         # commit but skip push for this run
+akm improve --sync                            # force sync even on profiles that disable it
+```
+
+Profile sync defaults: `default` and `thorough` auto-commit + push; `quick` and
+`memory-focus` skip sync entirely. Override with `--sync` / `--no-sync` flags.
+
+The `--writable` flag on `akm add` opts a remote git stash into push-on-sync:
 
 ```sh
 akm add git@github.com:org/skills.git --provider git --name my-skills --writable
@@ -193,8 +215,8 @@ akm add @scope/stash                            # From npm (managed)
 akm add owner/repo                            # From GitHub (managed)
 akm add ./path/to/local/stash                   # Local directory
 akm add git@github.com:org/repo.git --provider git --name my-skills --writable
-akm enable skills.sh                          # Enable the skills.sh registry
-akm disable skills.sh                         # Disable the skills.sh registry
+akm config enable skills.sh                   # Enable the skills.sh registry
+akm config disable skills.sh                  # Disable the skills.sh registry
 akm list                                      # List all sources
 akm list --kind managed                       # List managed sources only
 akm remove <target>                           # Remove by id, ref, path, or name
@@ -244,24 +266,29 @@ akm completions --install                     # Install completions
 ## Proposals & Improvement (0.8.0+)
 
 ```sh
-akm improve <ref>                              # Propose improvement for an asset
-akm proposals                                  # List pending proposals
-akm show proposal <id>                         # Render the proposal body
-akm diff <ref-or-id>                           # Diff by ref, UUID, or 8-char prefix (proposal positional optional)
-akm diff skill:akm-dream                       # Diff by asset ref
-akm accept 7c115132                            # Accept by UUID prefix
-akm accept <id> --target team-stash            # Accept to a named writable stash source
-akm reject skill:my-skill --reason "not ready" # Reject by asset ref
-akm reject <id> --reason "..."                 # Archive with a reason
+akm improve <ref>                                       # Propose improvement for an asset
+akm proposal list                                       # List pending proposals
+akm proposal show <id>                                  # Render the proposal body
+akm proposal diff <ref-or-id>                           # Diff by ref, UUID, or 8-char prefix
+akm proposal diff skill:akm-dream                       # Diff by asset ref
+akm proposal accept 7c115132                            # Accept by UUID prefix
+akm proposal accept <id> --target team-stash            # Accept to a named writable stash source
+akm proposal reject skill:my-skill --reason "not ready" # Reject by asset ref
+akm proposal reject <id> --reason "..."                 # Archive with a reason
+akm proposal revert <id>                                # Restore the pre-promotion content
 ```
 
+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).
+
 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
 (milliseconds) to override `config.agent.timeoutMs` for that task only.
 
 ## Output Control
 
-All commands accept `--format` and `--detail` flags:
+All commands accept `--format`, `--detail`, and `--shape` flags:
 
 - `--format json` (default) — structured JSON
 - `--format jsonl` — one JSON object per line (streaming-friendly)
@@ -270,8 +297,9 @@ All commands accept `--format` and `--detail` flags:
 - `--detail brief` (default) — compact output
 - `--detail normal` — adds tags, refs, origins
 - `--detail full` — includes scores, paths, timing, debug info
-- `--detail summary` — metadata only (no content/template/prompt), under 200 tokens
-- `--detail agent` — agent-optimized output: strips non-actionable fields
-- `--for-agent` — deprecated alias for `--detail agent`
+- `--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/{output → assets/hints}/cli-hints-short.md

@@ -33,15 +33,17 @@ akm remember "note" --target my-stash         # Route write to a named writable
 akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
 akm import ./doc.md --target my-stash         # Route import to a named writable stash source
 akm wiki list                                 # List available wikis
-akm wiki ingest <name>                        # Print the ingest workflow for a wiki
+akm wiki ingest <name>                        # Dispatch an agent to run the ingest workflow (uses defaults.agent or --profile)
 akm wiki stash <name> ./paper.md --target my-stash # Route wiki stash write to a named source
-akm diff skill:akm-dream                      # Diff proposal by ref, UUID, or 8-char prefix
-akm accept 7c115132                           # Accept by UUID prefix (proposal positional optional)
-akm reject skill:my-skill --reason "..."      # Reject by ref (proposal positional optional)
+akm proposal diff skill:akm-dream             # Diff proposal by ref, UUID, or 8-char prefix
+akm proposal accept 7c115132                  # Accept by UUID prefix
+akm proposal reject skill:my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive|--negative      # Record whether an asset helped
 akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
-akm save                                      # Commit (and push if writable remote) changes in the primary stash
+akm sync                                      # Commit (and push if writable remote) changes in the primary stash (--no-push to commit only)
+akm improve --no-sync                         # Run improve without the end-of-run auto-commit
+akm improve --no-push                         # Auto-commit but skip push for this run
 akm registry search "<query>"                 # Search all registries
 ```
 
@@ -56,8 +58,9 @@ 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) |
-| vault | Key names only; use `akm vault path` or `akm vault run` to use values safely |
-| wiki | A page in a multi-wiki knowledge base. For any wiki task, start with `akm wiki list`, then `akm wiki ingest <name>` for the workflow. Run `akm wiki -h` for the full surface. |
+| 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. |
+| 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. |
 
 When an asset meaningfully helps or fails, record that with `akm feedback` so
 future search ranking can learn from real usage.

package/dist/assets/profiles/default.json

@@ -0,0 +1,15 @@
+{
+  "description": "Standard improve pass — all sub-processes, markdown asset types.",
+  "processes": {
+    "reflect": {
+      "enabled": true,
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
+    },
+    "distill": { "enabled": true, "allowedTypes": ["memory"] },
+    "consolidate": { "enabled": true, "allowedTypes": ["memory"] },
+    "memoryInference": { "enabled": true },
+    "graphExtraction": { "enabled": true },
+    "triage": { "enabled": false, "applyMode": "queue", "policy": "personal-stash" }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/profiles/graph-refresh.json

@@ -0,0 +1,13 @@
+{
+  "description": "Full-corpus graph extraction pass — rebuilds graph relationships across all stash files. Disables all other sub-processes. Use via `akm improve --profile graph-refresh` or the embedded `graph-refresh-weekly` task.",
+  "processes": {
+    "reflect": { "enabled": false },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": false },
+    "memoryInference": { "enabled": false },
+    "graphExtraction": { "enabled": true, "fullScan": true },
+    "extract": { "enabled": false },
+    "triage": { "enabled": false }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/profiles/memory-focus.json

@@ -0,0 +1,12 @@
+{
+  "description": "Memory and lesson improvement only — no distill, consolidate, or graphExtraction.",
+  "processes": {
+    "reflect": { "enabled": true, "allowedTypes": ["memory", "lesson"] },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": false },
+    "memoryInference": { "enabled": true },
+    "graphExtraction": { "enabled": false },
+    "triage": { "enabled": false }
+  },
+  "sync": { "enabled": false }
+}

package/dist/assets/profiles/quick.json

@@ -0,0 +1,15 @@
+{
+  "description": "Reflect-only pass — no distill, consolidate, memoryInference, or graphExtraction.",
+  "processes": {
+    "reflect": {
+      "enabled": true,
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
+    },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": false },
+    "memoryInference": { "enabled": false },
+    "graphExtraction": { "enabled": false },
+    "triage": { "enabled": false }
+  },
+  "sync": { "enabled": false }
+}

package/dist/assets/profiles/thorough.json

@@ -0,0 +1,15 @@
+{
+  "description": "All sub-processes enabled (currently identical to default; reserved for future divergence).",
+  "processes": {
+    "reflect": {
+      "enabled": true,
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
+    },
+    "distill": { "enabled": true, "allowedTypes": ["memory"] },
+    "consolidate": { "enabled": true, "allowedTypes": ["memory"] },
+    "memoryInference": { "enabled": true },
+    "graphExtraction": { "enabled": true },
+    "triage": { "enabled": true, "applyMode": "queue" }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/prompts/extract-session.md

@@ -0,0 +1,80 @@
+You are extracting durable engineering insights from a software session transcript. Most sessions produce zero new durable insights — the agent already captures what's worth keeping via explicit `akm remember` / `akm feedback` calls during the session. Your job is to identify learnings that slipped through.
+
+## What counts as "durable insight"
+
+Things worth extracting:
+- Recovery patterns ("X fails when Y; the fix is Z")
+- Hidden constraints discovered mid-task ("this codebase requires X before deploy")
+- Architecture observations ("module A is consumed by B and C via the D bus")
+- Non-obvious workarounds for real defects
+- Domain knowledge the agent learned and would benefit a future session
+
+Things NOT to extract:
+- Successful command sequences (already in git history / shell history)
+- Tool counts / aggregates
+- The agent's own narrative about what it was doing
+- Restatements of what the user asked for
+- Generic platitudes ("test your code", "be careful with X")
+- Anything already preserved via the agent's explicit calls (see below)
+
+## Already preserved by the agent — DO NOT re-extract
+
+{{ALREADY_PRESERVED}}
+
+## Session metadata
+
+- Harness: {{HARNESS}}
+- Title: {{TITLE}}
+- Started: {{STARTED_AT}}
+- Ended: {{ENDED_AT}}
+- Project hint: {{PROJECT_HINT}}
+
+## Filtered session transcript
+
+The transcript below has already had read-only `akm` meta-ops and platform boilerplate stripped. Only content that might carry signal remains.
+
+{{TRANSCRIPT}}
+
+## Output contract
+
+Respond with EXACTLY one JSON object matching this shape:
+
+```
+{
+  "candidates": [
+    {
+      "type": "memory" | "lesson" | "knowledge",
+      "name": "<kebab-case-slug>",
+      "description": "<one sentence 20-400 chars>",
+      "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
+      "body": "<markdown body, 200-3000 chars typical>",
+      "confidence": <number 0.0-1.0>,
+      "evidence": "<one-line pointer to the moment in the session>"
+    }
+  ],
+  "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
+}
+```
+
+## Rules
+
+1. **Zero candidates is a valid and frequent answer.** Most sessions yield no new durable insight. When that's the case, return `{"candidates": [], "rationale_if_empty": "..."}` explaining what you saw and why it didn't rise to durable-knowledge level. Do not fabricate.
+
+2. **Pick the right type per candidate:**
+   - `memory` — a fact or short observation. Use for "X works on this codebase", "auth uses Y library version Z".
+   - `lesson` — a "do X / avoid Y" pattern, ALWAYS with `when_to_use`. Use for hard-won learnings about pitfalls, recovery patterns, or non-obvious gotchas.
+   - `knowledge` — substantive multi-section reference doc. Rare from one session.
+
+3. **Calibrate `confidence` honestly:**
+   - `0.9+` — high certainty this is a real durable insight a reviewer would clearly accept
+   - `0.7-0.89` — clear improvement, but a reviewer might prefer different framing or scope
+   - `0.5-0.69` — marginal / judgment call
+   - `<0.5` — don't include; prefer fewer-but-better candidates
+
+4. **`evidence` must reference the session** — a brief pointer like "agent's tool failure at ts=...", "user's correction at ...", "after the recovery in the Bash sequence around ...". Without evidence the candidate is hard to validate; default to lower confidence when evidence is vague.
+
+5. **Do not duplicate already-preserved content.** If a candidate substantively overlaps with anything in the "Already preserved" list above, skip it.
+
+6. **No speculation.** Only extract things the session genuinely demonstrates. If the agent struggled and didn't resolve, that may itself be a lesson (`when_to_use: "When attempting X, expect Y to fail"`) — but only if the failure mode is concrete enough to be useful next time.
+
+7. Respond with the JSON object only. No prose before or after. No code fences.

package/dist/assets/prompts/graph-extract-user-prompt.md

@@ -0,0 +1,35 @@
+Extract entities and relations from the asset body below.
+
+Rules:
+- Output ONLY a JSON object: {"entities": ["Entity One", ...], "relations": [{"from": "A", "to": "B", "type": "uses"}, ...]}.
+- Entities are short, canonical noun phrases (project names, services, tools, people, file/dir names, technical concepts).
+- Relations connect two entities that both appear in the entities array.
+- "type" is a short verb phrase (e.g. "uses", "depends on", "owns", "documents"). Optional; omit when unsure.
+- Drop pleasantries, meta-commentary, and timestamps.
+- Limit to at most {{MAX_ENTITIES}} entities and {{MAX_RELATIONS}} relations per asset.
+- Return {"entities": [], "relations": []} if the body has no extractable graph content.
+- DO NOT return markdown code blocks, ONLY valid JSON objects.
+
+Examples:
+
+Input:
+## Deployment Notes
+The auth-service uses PostgreSQL for user sessions. It depends on the redis-cache
+for rate limiting. The terraform-provisioner deploys everything to the prod cluster.
+Owner: @alice.
+
+Output:
+{"entities":["auth-service","PostgreSQL","redis-cache","terraform-provisioner","prod cluster","@alice"],"relations":[{"from":"auth-service","to":"PostgreSQL","type":"uses"},{"from":"auth-service","to":"redis-cache","type":"depends on"},{"from":"terraform-provisioner","to":"prod cluster","type":"deploys"},{"from":"terraform-provisioner","to":"auth-service","type":"deploys"},{"from":"@alice","to":"auth-service","type":"owns"}]}
+
+Input:
+## Meeting: API Redesign
+Discussed moving from REST to GraphQL. The frontend team will use Apollo Client.
+Backend needs to implement resolvers. Timeline: Q2.
+
+Output:
+{"entities":["REST","GraphQL","Apollo Client","frontend team","backend","resolvers","Q2"],"relations":[{"from":"frontend team","to":"Apollo Client","type":"uses"},{"from":"backend","to":"resolvers","type":"implements"},{"from":"frontend team","to":"GraphQL","type":"migrates to"}]}
+
+===============
+
+Request:
+

package/dist/assets/tasks/graph-refresh-weekly.yml

@@ -0,0 +1,10 @@
+id: graph-refresh-weekly
+description: >
+  Weekly full-corpus graph extraction pass. Rebuilds entity and relation
+  indexes across all stash files using the graph-refresh improve profile.
+  Complements the per-run improve pipeline which only extracts graph data
+  for files touched by actionable refs.
+command: akm improve --profile graph-refresh
+schedule: "0 3 * * 0"
+enabled: false
+timeout: 3600000

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.");
+}