akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/assets/wiki/ingest-workflow-template.md

@@ -6,23 +6,50 @@ Schema: {{SCHEMA_PATH}}
 Follow these steps. akm commands handle the invariants; use your native
 Read/Write/Edit tools for page edits.
 
+This workflow is for ingesting sources that are ALREADY present under
+`{{WIKI_DIR}}/raw/`. Do not ask the user for a source unless the raw queue is
+empty and the caller explicitly asked for interactive ingest.
+
 1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
    kinds, contradiction policy, and any wiki-specific conventions. Do not
    skip this step even on familiar wikis — the schema may have changed.
 
-2. **File the source under `raw/`.**
+2. **Discover the pending raw queue.**
    ```sh
-   akm wiki stash {{WIKI_NAME}} <path-or-url-to-source>
-   # or: cat <source> | akm wiki stash {{WIKI_NAME}} -
+   akm wiki lint {{WIKI_NAME}}
    ```
-   Returns `{ slug, path, ref }`. The raw copy is immutable — never edit it.
+   Focus on `uncited-raw` findings: those raw files exist under `raw/` but are
+   not yet cited by any authored page. Treat each `uncited-raw` finding as a
+   pending ingest item, and sort the queue **oldest raw file first** (by
+   filename/mtime). Processing oldest-first keeps backlog age bounded even
+   when the queue is larger than one run can finish. If there are no
+   `uncited-raw` findings, exit cleanly after a final `akm index` +
+   `akm wiki lint {{WIKI_NAME}}` verification.
+
+   Do not read or classify the whole backlog upfront. Work the queue as a
+   bounded loop, one raw file at a time: fully finish a raw (read → decide →
+   edit → log entry, steps 3-7 below) before looking at the next one. If you
+   run low on time partway through a large backlog, stop after finishing your
+   current raw — do not start a new one you can't complete. This is expected
+   and fine: whatever you already merged is committed to the pages and
+   `log.md`, so the next scheduled run picks up where you left off instead of
+   redoing this run's work.
+
+3. **For the current raw file, read the source and find related pages.**
+   Open the raw file directly from `{{WIKI_DIR}}/raw/`.
+
+   If the file does not read as text (binary content, garbled bytes, e.g. a
+   raw PDF byte-dump that was never text-extracted), do not attempt deep
+   forensic recovery (no web searches, no `strings`-style dumps). Append a
+   one-line `log.md` entry noting it as skipped/unprocessable with a short
+   reason, then move on to the next raw in the queue.
 
-3. **Find related existing pages.**
+   Otherwise, search for related pages:
    ```sh
-   akm wiki search {{WIKI_NAME}} "<key terms from the source>"
+   akm wiki search {{WIKI_NAME}} "<key terms from the raw source>"
    ```
-   Read the top hits with `akm show wiki:{{WIKI_NAME}}/<page>`. Use
-   `akm show wiki:{{WIKI_NAME}}/<page> toc` for large pages.
+   Read the top hits with `akm show wiki:{{WIKI_NAME}}/pages/<page>`. Use
+   `akm show wiki:{{WIKI_NAME}}/pages/<page> toc` for large pages.
 
 4. **Decide for each candidate.** For each related page:
    - **Append**: add a section or paragraph under the relevant heading.
@@ -31,16 +58,18 @@ Read/Write/Edit tools for page edits.
      Follow the schema's contradiction policy.
    - **Skip**: source doesn't add to this page — move on.
 
-5. **Create new pages for concepts/entities the source introduces.** Each
-   new page must have frontmatter with `description`, `pageKind`,
-   `xrefs`, and `sources`. Cross-reference with related pages both
-   directions.
+5. **Create new pages for concepts/entities the source introduces**, under
+   `{{WIKI_DIR}}/pages/` (never at the wiki root — only `schema.md`,
+   `index.md`, and `log.md` belong there). Each new page must have
+   frontmatter with `description`, `pageKind`, `xrefs`, and `sources`.
+   Cross-reference with related pages both directions.
 
 6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
    page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
 
-7. **Append to `log.md`.** One entry per ingest: date, source slug, one-line
-   summary, refs to created/edited pages. Newest at the top.
+7. **Append to `log.md`.** One entry per processed raw source (ingested or
+   skipped-as-unprocessable): date, raw slug, one-line summary, refs to
+   created/edited pages. Newest at the top.
 
 8. **Regenerate the index + verify.**
    ```sh
@@ -50,5 +79,5 @@ Read/Write/Edit tools for page edits.
    Resolve any lint findings before calling the ingest done.
 
 That's it. `akm` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, unique slugs, ref validation, index
-regeneration, structural lint).
+the invariants (raw immutability, ref validation, index regeneration,
+structural lint).

package/dist/assets/wiki/schema-template.md

@@ -8,7 +8,7 @@ wikiRole: schema
 This wiki follows the three-layer pattern:
 
 - `raw/` — immutable ingested sources (never edit)
-- `<page>.md` and `<topic>/<page>.md` — agent-authored pages
+- `pages/<page>.md` and `pages/<topic>/<page>.md` — agent-authored pages
 - `schema.md` (this file), `index.md`, `log.md` — wiki-level metadata
 
 ## Page frontmatter
@@ -20,7 +20,7 @@ Every page should carry frontmatter so akm can index and link it:
 description: one-sentence summary used in search and lint
 pageKind: entity | concept | question | note | <your-custom-kind>
 xrefs:
-  - wiki:{{WIKI_NAME}}/other-page
+  - wiki:{{WIKI_NAME}}/pages/other-page
 sources:
   - raw/<slug>.md
 ---
@@ -36,14 +36,14 @@ will surface in `index.md` as new sections after the next `akm index` run.
 1. Copy the new source into `raw/` with `akm wiki stash {{WIKI_NAME}} <path>`.
 2. Find related pages: `akm wiki search {{WIKI_NAME}} "<terms>"`.
 3. For each related page: append a section, note a contradiction, or create a
-   new page. Update xrefs on both sides.
+   new page under `pages/`. Update xrefs on both sides.
 4. Cite the raw source in each touched page's `sources:` frontmatter.
 5. Append one entry to `log.md` describing what was assimilated.
 
 ### Query
 
 1. `akm wiki search {{WIKI_NAME}} "<question>"` — find candidate pages.
-2. `akm show wiki:{{WIKI_NAME}}/<page>` — read the top hits.
+2. `akm show wiki:{{WIKI_NAME}}/pages/<page>` — read the top hits.
 3. Compose the answer from the wiki; cite raw sources only when the wiki
    points at them.
 

package/dist/cli/clack.js

@@ -0,0 +1,56 @@
+// 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 { cancel as realCancel, confirm as realConfirm, intro as realIntro, isCancel as realIsCancel, log as realLog, multiselect as realMultiselect, note as realNote, outro as realOutro, select as realSelect, spinner as realSpinner, text as realText, } from "@clack/prompts";
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter
+// (via tests/_helpers/seams.ts `overrideSeam`, never directly).
+let clackFake;
+/** TEST-ONLY. Swap the clack prompt surface; pass undefined to restore. */
+export function _setClackForTests(fake) {
+    clackFake = fake;
+}
+const realFns = {
+    intro: realIntro,
+    outro: realOutro,
+    cancel: realCancel,
+    confirm: realConfirm,
+    select: realSelect,
+    multiselect: realMultiselect,
+    text: realText,
+    spinner: realSpinner,
+    note: realNote,
+    isCancel: realIsCancel,
+};
+/** Delegator with the real export's exact type; reads the fake at call time. */
+function bind(name) {
+    return ((...args) => {
+        const impl = (clackFake?.[name] ?? realFns[name]);
+        return impl(...args);
+    });
+}
+function bindLog(name) {
+    return ((...args) => {
+        const impl = (clackFake?.log?.[name] ?? realLog[name]);
+        return impl(...args);
+    });
+}
+export const intro = bind("intro");
+export const outro = bind("outro");
+export const cancel = bind("cancel");
+export const confirm = bind("confirm");
+export const select = bind("select");
+export const multiselect = bind("multiselect");
+export const text = bind("text");
+export const spinner = bind("spinner");
+export const note = bind("note");
+export const isCancel = bind("isCancel");
+export const log = {
+    message: bindLog("message"),
+    info: bindLog("info"),
+    success: bindLog("success"),
+    step: bindLog("step"),
+    warn: bindLog("warn"),
+    warning: bindLog("warning"),
+    error: bindLog("error"),
+};

package/dist/cli/config-migrate.js

@@ -14,12 +14,18 @@ function backupConfigFile(configPath) {
     if (!fs.existsSync(configPath))
         return;
     const backupDir = path.join(getCacheDir(), "config-backups");
-    fs.mkdirSync(backupDir, { recursive: true });
+    // 08-F4: lock the backup dir owner-only (0700) — see config-io.ts.
+    fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(backupDir, 0o700);
     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);
+    // 08-F4: config backups can carry secrets (endpoints/tokens) — keep them
+    // owner-only rather than inheriting the source file's (often 0644) mode.
+    fs.chmodSync(backupPath, 0o600);
+    fs.chmodSync(latestPath, 0o600);
 }
 function acquireMigrateLock(lockPath, noWait) {
     const lockDir = path.dirname(lockPath);

package/dist/cli/confirm.js

@@ -35,8 +35,8 @@
  * `--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.js";
+import * as p from "./clack.js";
 /**
  * Prompt the user to confirm a destructive action.
  *

package/dist/cli/parse-args.js

@@ -8,7 +8,52 @@
  * main CLI file focused on command definitions and routing.
  */
 import { UsageError } from "../core/errors.js";
-// ── Subcommand detection ─────────────────────────────────────────────────────
+function cittyComparableName(name) {
+    return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
+}
+function toAliasArray(alias) {
+    if (Array.isArray(alias))
+        return alias;
+    return typeof alias === "string" ? [alias] : [];
+}
+function isCittyValueFlag(flag, argsDef) {
+    const name = flag.replace(/^-{1,2}/, "");
+    const normalized = cittyComparableName(name);
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type !== "string" && def.type !== "enum")
+            continue;
+        if (normalized === cittyComparableName(key))
+            return true;
+        if (toAliasArray(def.alias).includes(name))
+            return true;
+    }
+    return false;
+}
+/**
+ * Match citty's top-level subcommand scan (`findSubCommandIndex`).
+ *
+ * Citty does not assume `rawArgs[0]` is the command: global string flags may
+ * appear first and consume the following token. The CLI startup guard uses this
+ * to classify the requested command before any command handler can run.
+ */
+export function findCittyTopLevelCommandIndex(rawArgs, argsDef) {
+    for (let i = 0; i < rawArgs.length; i += 1) {
+        const arg = rawArgs[i];
+        if (arg === "--")
+            return -1;
+        if (arg.startsWith("-")) {
+            if (!arg.includes("=") && isCittyValueFlag(arg, argsDef))
+                i += 1;
+            continue;
+        }
+        return i;
+    }
+    return -1;
+}
+export function findCittyTopLevelCommand(rawArgs, argsDef) {
+    const index = findCittyTopLevelCommandIndex(rawArgs, argsDef);
+    return index >= 0 ? rawArgs[index] : undefined;
+}
 /**
  * Return true when `args._[0]` is a member of `validSet`.
  *

package/dist/cli/shared.js

@@ -15,6 +15,7 @@ import { getOutputMode } from "../output/context.js";
 import { DEFAULT_TEMPLATE, deliverRendered, escapeHtml, renderHtml, resolveTemplatePath } from "../output/html-render.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
+import { hasSubcommand } from "./parse-args.js";
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -111,6 +112,33 @@ export function defineJsonCommand(def) {
         run: (context) => runWithJsonErrors(() => run(context)),
     });
 }
+/**
+ * Define a citty subcommand-group command (env, secret, proposal, tasks, wiki,
+ * graph, …) that shares one wiring shape: a `subCommands` map, a routing set
+ * DERIVED from that map's keys (so the set can never silently desync from the
+ * registered subcommands), and a default body that fires ONLY for the bare
+ * group invocation — citty still runs the group body after dispatching a
+ * subcommand, so the shared guard short-circuits when `args._[0]` names a
+ * registered subcommand.
+ *
+ * The `defaultRun` body is wrapped in `runWithJsonErrors`, so it emits a
+ * byte-identical JSON error envelope on throw — exactly the per-site
+ * `run() { return runWithJsonErrors(() => { if (hasSubcommand(...)) return; … }); }`
+ * boilerplate this replaces.
+ */
+export function defineGroupCommand(def) {
+    const subcommandSet = new Set(Object.keys(def.subCommands));
+    return defineCommand({
+        meta: def.meta,
+        ...(def.args ? { args: def.args } : {}),
+        subCommands: def.subCommands,
+        run: (context) => runWithJsonErrors(() => {
+            if (hasSubcommand(context.args, subcommandSet))
+                return;
+            return def.defaultRun(context);
+        }),
+    });
+}
 /**
  * Render a command result according to the active output mode
  * (json/jsonl/yaml/text/md/html). When `--output <path>` is set, the rendered

package/dist/cli.js

@@ -8,18 +8,21 @@
 // `dist/cli-node.mjs` wrapper, which registers the text-import loader hook
 // before this module graph loads; running `node dist/cli.js` directly still
 // works for code paths that touch no embedded text asset, but the wrapper is
-// the supported entry. The hard floor is Node 20: `@clack/core` (prompts) imports
+// the supported entry. The hard floor is Node 20.12: `@clack/core` (prompts) imports
 // `node:util`'s `styleText` (added in Node 20.12) — Node 18 (EOL) throws at import.
 {
     const isBun = typeof globalThis.Bun !== "undefined";
     if (!isBun) {
-        const major = Number.parseInt((process.versions.node ?? "0").split(".")[0], 10);
-        if (Number.isNaN(major) || major < 20) {
-            console.error("\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh) or Node.js >= 20.\n" +
+        const [major = 0, minor = 0, patch = 0] = (process.versions.node ?? "0")
+            .split(".")
+            .map((part) => Number.parseInt(part, 10) || 0);
+        const nodeOk = major > 20 || (major === 20 && (minor > 12 || (minor === 12 && patch >= 0)));
+        if (!nodeOk) {
+            console.error("\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh) or Node.js >= 20.12.\n" +
                 `  Detected Node.js ${process.versions.node ?? "unknown"}.\n` +
                 "  Install options:\n" +
                 "    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\n" +
-                "    2. Node:   upgrade to Node.js 20 or newer (https://nodejs.org)\n" +
+                "    2. Node:   upgrade to Node.js 20.12 or newer (https://nodejs.org)\n" +
                 "    3. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\n");
             process.exit(1);
         }
@@ -57,6 +60,7 @@ process.on("uncaughtException", (err) => {
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
+import { findCittyTopLevelCommand } from "./cli/parse-args.js";
 import { EXIT_CODES, emitJsonError, output, parseAllFlagValues, runWithJsonErrors } from "./cli/shared.js";
 import { agentCommand, lintCommand, proposeCommand } from "./commands/agent/contribute-cli.js";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions.js";
@@ -65,7 +69,9 @@ import { envCommand } from "./commands/env/env-cli.js";
 import { secretCommand } from "./commands/env/secret-cli.js";
 import { feedbackCommand } from "./commands/feedback-cli.js";
 import { graphCommand } from "./commands/graph/graph-cli.js";
-import { akmHealth, parseWindowSpec, renderRunsDetailMd, renderWindowCompareMd, } from "./commands/health.js";
+import { akmHealth } from "./commands/health.js";
+import { renderRunsDetailMd, renderWindowCompareMd } from "./commands/health/md-report.js";
+import { parseWindowSpec } from "./commands/health/windows.js";
 import { extractCommand } from "./commands/improve/extract-cli.js";
 import { improveCommand } from "./commands/improve/improve-cli.js";
 import { hintsCommand, lessonsCommand, logCommand } from "./commands/observability-cli.js";
@@ -77,7 +83,7 @@ import { registryCommand } from "./commands/registry-cli.js";
 import { addCommand } from "./commands/sources/add-cli.js";
 import { renderMigrationHelp } from "./commands/sources/migration-help.js";
 import { cloneCommand, historyCommand, listCommand, removeCommand, syncCommand, updateCommand, upgradeCommand, } from "./commands/sources/sources-cli.js";
-import { dbCommand, importKnowledgeCommand, indexCommand, infoCommand, initCommand, } from "./commands/sources/stash-cli.js";
+import { importKnowledgeCommand, indexCommand, infoCommand, initCommand } from "./commands/sources/stash-cli.js";
 import { tasksCommand } from "./commands/tasks/tasks-cli.js";
 import { wikiCommand } from "./commands/wiki-cli.js";
 import { workflowCommand } from "./commands/workflow-cli.js";
@@ -208,8 +214,8 @@ const setupCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const noInit = getHyphenatedBoolean(args, "no-init");
-            const detectOnly = getHyphenatedBoolean(args, "detect-only");
-            const resetRecommended = getHyphenatedBoolean(args, "reset-recommended");
+            const detectOnly = args["detect-only"];
+            const resetRecommended = args["reset-recommended"];
             if (detectOnly) {
                 // Detection only: no prompts, no writes.
                 const { runDetectOnly } = await import("./setup/setup.js");
@@ -320,10 +326,14 @@ const healthCommand = defineCommand({
             // window-compare read for the trend deltas (defaults to 24h,
             // overridable via --compare).
             if (mode.format === "html") {
-                const compare = args.compare ?? windowCompareRaw ?? "24h";
-                const result = akmHealth({ since: args.since, groupBy: "run" });
+                // Default the compare window to the report's own `--since` window so the
+                // trend deltas are like-for-like (e.g. last 7d vs the prior 7d). A fixed
+                // 24h default made a `--since 7d` report compare its 7-day totals against
+                // a 24-hour prior window, producing meaningless deltas.
+                const compare = args.compare ?? windowCompareRaw ?? args.since ?? "24h";
+                const result = akmHealth({ since: args.since, groupBy: "run", windowCompare: compare });
                 resultStatus = result.status;
-                const deltas = akmHealth({ since: args.since, windowCompare: compare }).deltas;
+                const deltas = result.deltas;
                 const { buildHealthHtmlReplacements } = await import("./commands/health/html-report.js");
                 const { listPendingProposals } = await import("./commands/proposal/proposal.js");
                 const replacements = buildHealthHtmlReplacements(result, {
@@ -482,7 +492,6 @@ export const main = defineCommand({
         health: healthCommand,
         info: infoCommand,
         graph: graphCommand,
-        db: dbCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -517,6 +526,7 @@ export const main = defineCommand({
         tasks: tasksCommand,
     },
 });
+const MAIN_TOP_LEVEL_ARGS = main.args;
 // ── Exit codes ──────────────────────────────────────────────────────────────
 // Canonical table lives in `src/cli/shared.ts` (EXIT_CODES). These aliases keep
 // the local call sites terse. EXIT_HEALTH_WARN (4) is the `akm health` "warn"
@@ -557,7 +567,8 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
     // output-shaping time after the side effect has already happened. The
     // shape-registry gate in shapeForCommand() remains as defense-in-depth (and
     // covers the in-process test harness, which skips this startup block).
-    if (getOutputMode().shape === "summary" && process.argv[2] !== "show") {
+    const topLevelCommand = findCittyTopLevelCommand(process.argv.slice(2), MAIN_TOP_LEVEL_ARGS);
+    if (getOutputMode().shape === "summary" && topLevelCommand !== "show") {
         emitJsonError(new UsageError("'--shape summary' is only valid on 'akm show'.", "INVALID_SHAPE_VALUE"));
     }
     // One-time cleanup of stale 0.7.x index file at the old cache location.

package/dist/commands/agent/agent-dispatch.js

@@ -18,7 +18,7 @@ import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { requireAgentProfile } from "../../integrations/agent/config.js";
 import { runAgent } from "../../integrations/agent/spawn.js";
-import { runAgentSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
+import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
 /**
  * Fill `{{0}}`, `{{1}}`, ... placeholders in `template` with the
  * corresponding entries in `args`. Any placeholder index that exceeds the
@@ -90,10 +90,11 @@ export async function akmAgentDispatch(options) {
         parseOutput: "text",
         ...(options.args?.length && !options.commandRef && !options.workflowRef ? { args: options.args } : {}),
         ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.cwd ? { cwd: options.cwd } : {}),
         ...(dispatchRequest !== undefined ? { dispatch: dispatchRequest } : {}),
     };
     const result = profile.sdkMode
-        ? await runAgentSdk(profile, prompt ?? "", runOptions, options.llmConfig)
+        ? await runOpencodeSdk(profile, prompt ?? "", runOptions, options.llmConfig)
         : await runAgent(profile, prompt, runOptions);
     return {
         schemaVersion: 1,

package/dist/commands/agent/agent-support.js

@@ -1,13 +1,6 @@
 // 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/.
-/**
- * Shared helpers for agent-based commands (reflect, propose, etc.).
- *
- * Consolidates utility functions that were duplicated byte-for-byte across
- * `reflect.ts` and `propose.ts`. Any command that shells out to an agent
- * profile can import from here rather than copy-pasting.
- */
 import { loadConfig } from "../../core/config/config.js";
 import { requireAgentProfile, } from "../../integrations/agent/index.js";
 // ── Config helpers ───────────────────────────────────────────────────────────

package/dist/commands/agent/contribute-cli.js

@@ -28,8 +28,7 @@ import { EXIT_CODES, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
-import { getHyphenatedArg } from "../../output/context.js";
-import { akmLint } from "../lint.js";
+import { akmLint } from "../lint/index.js";
 import { akmPropose } from "../proposal/propose.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
 const EXIT_GENERAL = EXIT_CODES.GENERAL;
@@ -57,13 +56,17 @@ export const agentCommand = defineCommand({
             description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
         },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+        cwd: {
+            type: "string",
+            description: "Working directory for the spawned agent (defaults to the current directory)",
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             if (!args.profile) {
                 throw new UsageError("Usage: akm agent <profile> [<agent-ref>] [--prompt <text>] [--model <model>]", "MISSING_REQUIRED_ARGUMENT", "Provide the agent profile name. Available profiles are listed in profiles.agent.");
             }
-            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
             const config = loadConfig();
             const { getDefaultLlmConfig } = await import("../../core/config/config.js");
             // After 0.8.0 the agent block IS the loaded AkmConfig.
@@ -85,6 +88,7 @@ export const agentCommand = defineCommand({
             const promptText = getStringArg(args, "prompt");
             const commandRef = getStringArg(args, "command");
             const workflowRef = getStringArg(args, "workflow");
+            const cwd = getStringArg(args, "cwd");
             // Only build a dispatch request when there is something to dispatch — a
             // prompt, an agent asset, or a model override. When none of these are
             // present the agent is launched interactively (no injected prompt, no
@@ -104,9 +108,11 @@ export const agentCommand = defineCommand({
                             systemPrompt,
                             model,
                             tools: assetTools,
+                            ...(cwd ? { cwd } : {}),
                         },
                     }
                     : {}),
+                ...(cwd ? { cwd } : {}),
                 ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
             });
             output("agent-result", result);
@@ -122,23 +128,36 @@ export const lintCommand = defineCommand({
         description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
     },
     args: {
-        fix: { type: "boolean", description: "Apply auto-fixes in place", default: false },
+        fix: {
+            type: "boolean",
+            alias: "auto-fix",
+            description: "Apply auto-fixes in place (alias: --auto-fix)",
+            default: false,
+        },
         dir: { type: "string", description: "Override stash root directory (default: from config)" },
         "fail-on-flagged": {
             type: "boolean",
             description: "Exit non-zero when summary.flagged > 0 (CI-friendly). Default: exit 0 regardless of findings.",
             default: false,
         },
+        type: {
+            type: "string",
+            description: "Only lint assets of this type (e.g. workflows, tasks, memories)",
+            default: undefined,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const result = akmLint({
                 fix: args.fix ?? false,
                 dir: getStringArg(args, "dir"),
+                typeFilter: getStringArg(args, "type"),
             });
             output("lint", result);
-            if (args["fail-on-flagged"] && result.summary.flagged > 0)
-                process.exit(EXIT_GENERAL);
+            if (args["fail-on-flagged"] && result.summary.flagged > 0) {
+                process.exitCode = EXIT_GENERAL;
+                return;
+            }
         });
     },
 });
@@ -183,7 +202,7 @@ export const proposeCommand = defineCommand({
             assertFlatAssetName(String(args.name));
             const proposedName = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), String(args.name));
             const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
-            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
             const result = await akmPropose({
                 type: String(args.type),
                 name: proposedName,

package/dist/commands/config-cli.js

@@ -16,8 +16,7 @@
  *   - `parseConfigValue` returns a Partial<AkmConfig> so it can be merged with
  *     the runtime config object via `mergeConfigValue`.
  */
-import { hasSubcommand } from "../cli/parse-args.js";
-import { defineJsonCommand, output } from "../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { resolveStashDir } from "../core/common.js";
 import { DEFAULT_CONFIG, getSources, loadConfig, loadUserConfig, saveConfig, } from "../core/config/config.js";
 import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config/config-walker.js";
@@ -64,7 +63,10 @@ function rewriteKey(config, key) {
 // ── Public API ──────────────────────────────────────────────────────────────
 export function getConfigValue(config, key) {
     const k = rewriteKey(config, key);
-    return configGet(config, k);
+    const value = configGet(config, k);
+    if (k.split(".").at(-1) === "apiKey")
+        return null;
+    return omitApiKeysForOutput(value);
 }
 export function setConfigValue(config, key, rawValue) {
     // #454: reject the legacy aliases up front so the error message names the
@@ -154,7 +156,20 @@ export function listConfig(config) {
         result.archiveRetentionDays = config.archiveRetentionDays;
     if (config.configVersion !== undefined)
         result.configVersion = config.configVersion;
-    return result;
+    return omitApiKeysForOutput(result);
+}
+function omitApiKeysForOutput(value) {
+    if (Array.isArray(value))
+        return value.map(omitApiKeysForOutput);
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "apiKey")
+            continue;
+        out[key] = omitApiKeysForOutput(child);
+    }
+    return out;
 }
 export { unknownKeyHint };
 // ── `akm config` command surface ────────────────────────────────────────────
@@ -202,7 +217,7 @@ function toggleComponent(targetRaw, enabled) {
     // normalizeToggleTarget throws for any unsupported target; this is unreachable.
     throw new UsageError(`Unsupported target "${targetRaw}". Supported targets: skills.sh`);
 }
-export const configCommand = defineJsonCommand({
+export const configCommand = defineGroupCommand({
     meta: { name: "config", description: "Show and manage configuration" },
     args: {
         list: { type: "boolean", description: "List current configuration", default: false },
@@ -369,14 +384,12 @@ export const configCommand = defineJsonCommand({
             },
         }),
     },
-    run({ args }) {
-        if (hasSubcommand(args, CONFIG_SUBCOMMAND_SET))
-            return;
-        if (args.list) {
-            output("config", listConfig(loadConfig()));
-            return;
-        }
+    // The bare `akm config` invocation (and `akm config --list`) dumps the
+    // current config. defineGroupCommand short-circuits this body when a
+    // registered subcommand ran, so the routing set stays derived from the
+    // subCommands map and can never desync (previously validate/migrate were
+    // missing from a hand-maintained set, causing a spurious second dump).
+    defaultRun() {
         output("config", listConfig(loadConfig()));
     },
 });
-const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "show", "get", "set", "unset", "enable", "disable"]);