akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/commands/remember.js

@@ -50,6 +50,8 @@ export function buildMemoryFrontmatter(fields) {
         obj.tags = fields.tags;
     if (fields.source?.trim())
         obj.source = fields.source;
+    if (fields.xrefs && fields.xrefs.length > 0)
+        obj.xrefs = fields.xrefs;
     if (fields.observed_at?.trim())
         obj.observed_at = fields.observed_at;
     if (fields.expires?.trim())

package/dist/commands/sources/init.js

@@ -11,7 +11,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
-import { loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { mutateConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
 import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../../core/paths.js";
 import { ensureRg } from "../../core/ripgrep/install.js";
@@ -115,21 +115,20 @@ async function akmInitReal(options) {
     // Otherwise (--dir + existing default + no --set-default) leave the default
     // pointer alone; the target dir is still scaffolded above.
     const configPath = getConfigPath();
-    const existing = loadUserConfig();
-    const existingStashDir = existing.stashDir;
-    const shouldPersist = !dirExplicitlyProvided || !existingStashDir || setDefault;
     let defaultStashUpdated = false;
     let previousStashDir;
-    if (shouldPersist) {
-        if (!existingStashDir || existingStashDir !== stashDir) {
-            saveConfig({ ...existing, stashDir });
-            defaultStashUpdated = true;
-        }
-        // else: already pointed here — no-op, no spurious rewrite.
-    }
-    else {
-        // Default left untouched; surface it so the CLI can inform the user.
-        previousStashDir = existingStashDir;
+    if (options?.persistConfig !== false) {
+        const result = mutateConfig((latest) => {
+            const shouldPersist = !dirExplicitlyProvided || !latest.stashDir || setDefault;
+            if (!shouldPersist) {
+                previousStashDir = latest.stashDir;
+                return latest;
+            }
+            if (latest.stashDir === stashDir)
+                return latest;
+            return { ...latest, stashDir };
+        });
+        defaultStashUpdated = result.written;
     }
     // Ensure ripgrep is available (install to cache/bin if needed)
     let ripgrep;

package/dist/commands/sources/migration-help.js

@@ -116,12 +116,15 @@ export function renderMigrationHelp(versionInput, changelogText = loadChangelog(
     if (changelogText) {
         for (const candidate of candidates) {
             const section = extractChangelogSection(changelogText, candidate);
-            if (section) {
-                const bundled = loadReleaseNote(candidate);
-                if (!bundled)
-                    return `${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+            const bundled = loadReleaseNote(candidate);
+            if (bundled) {
+                if (!section)
+                    return `${bundled.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
                 return `${bundled.trim()}\n\nRelease notes\n-------------\n${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
             }
+            if (section) {
+                return `${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+            }
         }
     }
     const fallbackVersion = candidates.find((candidate) => candidate !== "latest") ?? requested;

package/dist/commands/sources/schema-repair.js

@@ -39,8 +39,8 @@ const SCHEMA_REPAIR_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 // ── Main ─────────────────────────────────────────────────────────────────────
 /**
  * Run the schema-repair loop for a batch of validation failures.
- * Returns a list of per-asset outcome records and the set of refs that were
- * successfully repaired (so the caller can exclude them from skip logic).
+ * Returns a list of per-asset outcome records and the set of refs whose live
+ * files were repaired. Queued proposals never count as live repairs.
  */
 export async function runSchemaRepairPass(failures, options) {
     const repairs = [];
@@ -167,8 +167,6 @@ export async function runSchemaRepairPass(failures, options) {
                 outcome: "queued",
                 proposalId: proposalResult.id,
             });
-            // Mark as repaired so the caller removes it from the validation-failure set.
-            repairedRefs.add(failure.ref);
         }
         catch (e) {
             appendEvent({

package/dist/commands/sources/source-add.js

@@ -4,7 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
-import { getSources, loadConfig, loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { getSources, loadConfig, mutateConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { upsertLockEntry } from "../../integrations/lockfile.js";
@@ -67,38 +67,33 @@ export async function registerWikiSource(input) {
 async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);
-    const config = loadUserConfig();
     // Derive the canonical name: explicit --name wins, then wiki name, then readable path.
     const derivedName = explicitName ?? wikiName ?? toReadableId(resolvedPath);
-    // Check for duplicates in sources[]
-    const sources = [...getSources(config)];
-    const existing = sources.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
     let persistedEntry;
-    if (!existing) {
-        persistedEntry = {
-            type: "filesystem",
-            path: resolvedPath,
-            name: derivedName,
-            ...(wikiName ? { wikiName } : {}),
-        };
-        sources.push(persistedEntry);
-        saveConfig({ ...config, sources });
-    }
-    else {
-        let changed = false;
-        // If --name was explicitly supplied, update the persisted name.
-        if (explicitName && existing.name !== explicitName) {
-            existing.name = explicitName;
-            changed = true;
+    mutateConfig((config) => {
+        const sources = [...getSources(config)];
+        const index = sources.findIndex((source) => source.type === "filesystem" && source.path && path.resolve(source.path) === resolvedPath);
+        if (index < 0) {
+            persistedEntry = {
+                type: "filesystem",
+                path: resolvedPath,
+                name: derivedName,
+                ...(wikiName ? { wikiName } : {}),
+            };
+            sources.push(persistedEntry);
+            return { ...config, sources };
         }
-        if (wikiName && existing.wikiName !== wikiName) {
+        const existing = { ...sources[index] };
+        if (explicitName)
+            existing.name = explicitName;
+        if (wikiName)
             existing.wikiName = wikiName;
-            changed = true;
-        }
-        if (changed)
-            saveConfig({ ...config, sources });
         persistedEntry = existing;
-    }
+        if (JSON.stringify(existing) === JSON.stringify(sources[index]))
+            return config;
+        sources[index] = existing;
+        return { ...config, sources };
+    });
     const index = await akmIndex({ stashDir });
     const updatedConfig = loadConfig();
     return {
@@ -108,9 +103,9 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
         sourceAdded: {
             type: "filesystem",
             path: resolvedPath,
-            name: persistedEntry.name ?? toReadableId(resolvedPath),
+            name: persistedEntry?.name ?? toReadableId(resolvedPath),
             stashRoot: resolvedPath,
-            ...(persistedEntry.wikiName ? { wiki: persistedEntry.wikiName } : {}),
+            ...(persistedEntry?.wikiName ? { wiki: persistedEntry.wikiName } : {}),
         },
         config: {
             sourceCount: getSources(updatedConfig).length,
@@ -128,33 +123,32 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
 async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
     const allowPrivateHosts = shouldAllowPrivateWebsiteUrlForTests(ref);
     const normalizedUrl = validateWebsiteInputUrl(ref, { allowPrivateHosts });
-    const config = loadUserConfig();
-    const sources = [...getSources(config)];
-    let entry = sources.find((stash) => stash.type === "website" && stash.url === normalizedUrl);
-    if (!entry) {
-        entry = {
-            type: "website",
-            url: normalizedUrl,
-            name: name ?? toWebsiteName(normalizedUrl),
-            ...(options && Object.keys(options).length > 0 ? { options } : {}),
-            ...(wikiName ? { wikiName } : {}),
-        };
-        sources.push(entry);
-        saveConfig({ ...config, sources });
-    }
-    else {
-        let changed = false;
-        if (options && Object.keys(options).length > 0) {
-            entry.options = { ...entry.options, ...options };
-            changed = true;
-        }
-        if (wikiName && entry.wikiName !== wikiName) {
-            entry.wikiName = wikiName;
-            changed = true;
+    let entry;
+    mutateConfig((config) => {
+        const sources = [...getSources(config)];
+        const index = sources.findIndex((source) => source.type === "website" && source.url === normalizedUrl);
+        if (index < 0) {
+            entry = {
+                type: "website",
+                url: normalizedUrl,
+                name: name ?? toWebsiteName(normalizedUrl),
+                ...(options && Object.keys(options).length > 0 ? { options } : {}),
+                ...(wikiName ? { wikiName } : {}),
+            };
+            sources.push(entry);
+            return { ...config, sources };
         }
-        if (changed)
-            saveConfig({ ...config, sources });
-    }
+        const existing = { ...sources[index] };
+        if (options && Object.keys(options).length > 0)
+            existing.options = { ...existing.options, ...options };
+        if (wikiName)
+            existing.wikiName = wikiName;
+        entry = existing;
+        if (JSON.stringify(existing) === JSON.stringify(sources[index]))
+            return config;
+        sources[index] = existing;
+        return { ...config, sources };
+    });
     const cachePaths = await ensureWebsiteMirror(entry, {
         requireStashDir: true,
         ...(allowPrivateHosts ? { allowPrivateHosts: true } : {}),
@@ -168,9 +162,9 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
         sourceAdded: {
             type: "website",
             url: normalizedUrl,
-            name: entry.name,
+            name: entry?.name,
             stashRoot: cachePaths.stashDir,
-            ...(entry.wikiName ? { wiki: entry.wikiName } : {}),
+            ...(entry?.wikiName ? { wiki: entry.wikiName } : {}),
         },
         config: {
             sourceCount: getSources(updatedConfig).length,
@@ -258,25 +252,20 @@ async function addRegistryStash(ref, stashDir, writable, wikiName) {
 }
 /** Persist or replace an installed stash entry in the user config. */
 export function upsertInstalledRegistryEntry(entry) {
-    const current = loadUserConfig();
-    const currentInstalled = current.installed ?? [];
-    const withoutExisting = currentInstalled.filter((item) => item.id !== entry.id);
-    const nextInstalled = [...withoutExisting, normalizeInstalledEntry(entry)];
-    const nextConfig = { ...current, installed: nextInstalled };
-    saveConfig(nextConfig);
-    return nextConfig;
+    return mutateConfig((current) => {
+        const withoutExisting = (current.installed ?? []).filter((item) => item.id !== entry.id);
+        return { ...current, installed: [...withoutExisting, normalizeInstalledEntry(entry)] };
+    }).config;
 }
 /** Remove an installed stash entry from the user config. */
 export function removeInstalledRegistryEntry(id) {
-    const current = loadUserConfig();
-    const currentInstalled = current.installed ?? [];
-    const nextInstalled = currentInstalled.filter((item) => item.id !== id);
-    const nextConfig = {
-        ...current,
-        installed: nextInstalled.length > 0 ? nextInstalled : undefined,
-    };
-    saveConfig(nextConfig);
-    return nextConfig;
+    return mutateConfig((current) => {
+        const currentInstalled = current.installed ?? [];
+        const nextInstalled = currentInstalled.filter((item) => item.id !== id);
+        if (nextInstalled.length === currentInstalled.length)
+            return current;
+        return { ...current, installed: nextInstalled.length > 0 ? nextInstalled : undefined };
+    }).config;
 }
 function normalizeInstalledEntry(entry) {
     return {

package/dist/commands/sources/source-manage.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { isRemoteUrl } from "../../core/common.js";
-import { getSources, loadConfig, loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { getSources, loadConfig, mutateConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 // ── Operations ──────────────────────────────────────────────────────────────
@@ -22,65 +22,69 @@ export function addStash(opts) {
     if (writable === true && providerType && providerType !== "filesystem" && providerType !== "git") {
         throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
     }
-    const config = loadUserConfig();
-    const sources = [...getSources(config)];
-    let entry;
+    let result;
     if (isRemoteUrl(target)) {
         if (!providerType) {
             throw new UsageError("--provider is required for URL sources (e.g. --provider git --provider website)");
         }
-        // Deduplicate by URL
-        if (sources.some((s) => s.url === target)) {
-            return { sources, added: false, message: "Source URL already configured" };
-        }
-        entry = { type: providerType, url: target };
-        if (name)
-            entry.name = name;
-        if (writable)
-            entry.writable = true;
-        if (providerOptions)
-            entry.options = providerOptions;
     }
-    else {
-        // Filesystem path
-        const resolvedPath = path.resolve(target);
-        if (sources.some((s) => s.path && path.resolve(s.path) === resolvedPath)) {
-            return { sources, added: false, message: "Source path already configured" };
+    mutateConfig((config) => {
+        const sources = [...getSources(config)];
+        let entry;
+        if (isRemoteUrl(target)) {
+            if (sources.some((source) => source.url === target)) {
+                result = { sources, added: false, message: "Source URL already configured" };
+                return config;
+            }
+            entry = { type: providerType, url: target };
+            if (name)
+                entry.name = name;
+            if (writable)
+                entry.writable = true;
+            if (providerOptions)
+                entry.options = providerOptions;
         }
-        entry = { type: "filesystem", path: resolvedPath };
-        if (name)
-            entry.name = name;
-    }
-    sources.push(entry);
-    saveConfig({ ...config, sources });
-    return { sources, added: true, entry };
+        else {
+            const resolvedPath = path.resolve(target);
+            if (sources.some((source) => source.path && path.resolve(source.path) === resolvedPath)) {
+                result = { sources, added: false, message: "Source path already configured" };
+                return config;
+            }
+            entry = { type: "filesystem", path: resolvedPath };
+            if (name)
+                entry.name = name;
+        }
+        sources.push(entry);
+        result = { sources, added: true, entry };
+        return { ...config, sources };
+    });
+    return result;
 }
 /**
  * Remove a stash source by URL, path, or name.
  * Match priority: URL > path > name (most specific first).
  */
 export function removeStash(target) {
-    const config = loadUserConfig();
-    const sources = [...getSources(config)];
     const isUrlTarget = isRemoteUrl(target);
     const resolvedPath = !isUrlTarget ? path.resolve(target) : undefined;
-    // Try URL match first, then path, then name (most specific → least specific)
-    let idx = -1;
-    if (isUrlTarget) {
-        idx = sources.findIndex((s) => s.url === target);
-    }
-    if (idx === -1 && resolvedPath) {
-        idx = sources.findIndex((s) => s.path && path.resolve(s.path) === resolvedPath);
-    }
-    if (idx === -1) {
-        idx = sources.findIndex((s) => s.name === target);
-    }
-    if (idx === -1) {
-        return { sources, removed: false, message: "No matching source found" };
-    }
-    const removed = sources.splice(idx, 1)[0];
-    saveConfig({ ...config, sources });
-    return { sources, removed: true, entry: removed };
+    let result;
+    mutateConfig((config) => {
+        const sources = [...getSources(config)];
+        let idx = isUrlTarget ? sources.findIndex((source) => source.url === target) : -1;
+        if (idx === -1 && resolvedPath) {
+            idx = sources.findIndex((source) => source.path && path.resolve(source.path) === resolvedPath);
+        }
+        if (idx === -1)
+            idx = sources.findIndex((source) => source.name === target);
+        if (idx === -1) {
+            result = { sources, removed: false, message: "No matching source found" };
+            return config;
+        }
+        const removed = sources.splice(idx, 1)[0];
+        result = { sources, removed: true, entry: removed };
+        return { ...config, sources };
+    });
+    return result;
 }
 /**
  * List all stash sources (local filesystem + configured stashes).

package/dist/commands/sources/stash-cli.js

@@ -27,8 +27,9 @@
 import path from "node:path";
 import { defineCommand } from "citty";
 import * as p from "../../cli/clack.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineJsonCommand, output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { isHttpUrl } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
@@ -38,7 +39,7 @@ import { clearLogFile, info, isVerbose, setLogFile } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../output/context.js";
-import { readKnowledgeInput, writeMarkdownAsset } from "../read/knowledge.js";
+import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
 import { akmInit } from "./init.js";
 export const initCommand = defineJsonCommand({
@@ -181,21 +182,57 @@ export const importKnowledgeCommand = defineJsonCommand({
             type: "string",
             description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
         },
+        xref: {
+            type: "string",
+            description: "Cross-reference ref merged into the document's `xrefs:` frontmatter (repeatable: --xref knowledge:auth-flow). Existing frontmatter is preserved (dedupe-append, never a nested block); a document whose frontmatter is not parseable YAML aborts the import rather than being rewritten lossily. Each ref must resolve in the write target or a configured source; an unresolvable ref aborts the import.",
+        },
+        supersedes: {
+            type: "string",
+            description: "Ref of an existing asset this document corrects (repeatable: --supersedes knowledge:legacy-guide). Imports the correction with an xref to the old asset AND demotes the old asset (`beliefState: superseded` + `supersededBy`, a metadata-only edit) so ranking prefers the correction and `--belief current` hides the stale version. An unresolvable or self-referencing ref aborts the import; a ref outside the write target and working stash still imports the correction but skips the demotion (reported as applied: false).",
+        },
     },
     async run({ args }) {
         // `--name` is a flat name; subdirectory placement is `--path`'s job.
         assertFlatAssetName(args.name);
+        // Collect and validate --xref occurrences (repeatable; citty only exposes
+        // the last value, so read argv directly). Validation happens BEFORE any
+        // read/write so an unresolvable ref (UsageError → exit 2) leaves the
+        // stash untouched.
+        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), args.target);
+        // Collect and validate --supersedes occurrences (repeatable). Same
+        // before-any-read/write contract: an unresolvable ref exits 2 with nothing
+        // imported AND nothing demoted. The superseded refs fold into the imported
+        // doc's xrefs automatically (correction provenance); the demotion runs
+        // inside writeMarkdownAsset, ordered before the git boundary commit.
+        const supersedes = resolveSupersedesForWrite(parseAllFlagValues("--supersedes"), args.target);
+        for (const s of supersedes) {
+            if (!xrefs.includes(s.ref))
+                xrefs.push(s.ref);
+        }
         const stashDir = resolveWriteTarget(loadConfig(), args.target).source.path;
         const { content, preferredName } = await readKnowledgeInput(args.source, { stashDir });
+        // Imported docs may carry their own frontmatter: merge (dedupe-append)
+        // BEFORE the write so write-path indexing sees the final content and no
+        // second frontmatter block is ever nested.
+        // The slug must come from the document BODY: a merged (or self-carried)
+        // frontmatter block puts the `---` fence on the first line, which
+        // inferAssetName would slugify to "" and fall back to a random
+        // knowledge-<epoch>-<rand> name. A stdin import (no filename-derived
+        // preferredName) therefore pre-infers the name from the pre-merge
+        // content's PARSED body — not the raw text, whose first line is the fence
+        // whenever the piped doc carries its own frontmatter — so --xref/
+        // --supersedes never change the slug and a frontmattered doc gets its
+        // heading-derived slug on every path.
         const result = await writeMarkdownAsset({
             type: "knowledge",
-            content,
+            content: mergeXrefsIntoContent(content, xrefs),
             name: args.name ?? (isHttpUrl(args.source) ? preferredName : undefined),
             fallbackPrefix: "knowledge",
-            preferredName,
+            preferredName: preferredName ?? inferAssetName(parseFrontmatter(content).content, "knowledge"),
             force: args.force,
             target: args.target,
             path: args.path,
+            supersedes,
         });
         appendEvent({
             eventType: "import",

package/dist/commands/tasks/default-tasks.js

@@ -7,8 +7,8 @@
  * Ships a well-tuned multi-cadence task set so a typical single-developer
  * install is correct with zero manual config. Registration is **idempotent**:
  * running `akm setup` / `akm tasks init` twice yields the same task set with no
- * duplicates. Each default task is a shell-command task (`akm improve --profile
- * <name>`), so the profile is overridable in `config.json` without editing the
+ * duplicates. Each default task is a shell-command task (`akm improve --strategy
+ * <name>`), so the strategy is overridable in `config.json` without editing the
  * task definition.
  *
  * The OS-scheduler-touching primitives (`add` / `setEnabled` / `list`) are
@@ -27,40 +27,40 @@ import { akmTasksAdd, akmTasksList } from "./tasks.js";
 export const DEFAULT_IMPROVE_TASKS = [
     {
         id: "akm-improve-frequent",
-        profile: "frequent",
-        command: "akm improve --profile frequent --auto-accept safe",
+        strategy: "frequent",
+        command: "akm improve --strategy frequent --auto-accept safe",
         schedule: "0 * * * *",
         description: "Frequent extract + inference pass (every 60 min)",
         enableMode: "always",
     },
     {
         id: "akm-improve-consolidate",
-        profile: "consolidate",
-        command: "akm improve --profile consolidate --auto-accept safe",
+        strategy: "consolidate",
+        command: "akm improve --strategy consolidate --auto-accept safe",
         schedule: "0 */4 * * *",
         description: "Consolidation-only pass (every 4h)",
         enableMode: "always",
     },
     {
         id: "akm-improve-nightly",
-        profile: "thorough",
-        command: "akm improve --profile thorough --auto-accept safe",
+        strategy: "thorough",
+        command: "akm improve --strategy thorough --auto-accept safe",
         schedule: "0 2 * * *",
         description: "Full nightly quality sweep (daily 2am)",
         enableMode: "server",
     },
     {
         id: "akm-improve-catchup",
-        profile: "catchup",
-        command: "akm improve --profile catchup --auto-accept safe",
+        strategy: "catchup",
+        command: "akm improve --strategy catchup --auto-accept safe",
         schedule: null,
         description: "Manual recovery — consolidation + triage drain (run on demand)",
         enableMode: "manual",
     },
     {
         id: "akm-graph-refresh-weekly",
-        profile: "graph-refresh",
-        command: "akm improve --profile graph-refresh --auto-accept safe",
+        strategy: "graph-refresh",
+        command: "akm improve --strategy graph-refresh --auto-accept safe",
         schedule: "0 3 * * 0",
         description: "Full-corpus graph rebuild (weekly Sunday 3am)",
         enableMode: "always",

package/dist/commands/tasks/tasks-cli.js

@@ -31,7 +31,9 @@ const tasksAddCommand = defineJsonCommand({
             type: "string",
             description: 'Shell command to run on the schedule (no AI agent), e.g. "akm improve --auto-accept safe". Split on whitespace; quote the whole flag value.',
         },
-        profile: { type: "string", description: "Agent profile to use for prompt targets (default: defaults.agent)" },
+        engine: { type: "string", description: "Engine to use for prompt targets (default: defaults.engine)" },
+        model: { type: "string", description: "Model override for prompt targets" },
+        "timeout-ms": { type: "string", description: "Positive timeout in milliseconds for prompt or command targets" },
         params: { type: "string", description: "Workflow params as a JSON object" },
         name: { type: "string", description: "Human-readable name for the task" },
         "when-to-use": { type: "string", description: "Guidance on when this task runs or should be used" },
@@ -47,7 +49,9 @@ const tasksAddCommand = defineJsonCommand({
             workflow: args.workflow,
             prompt: args.prompt,
             command: args.command,
-            profile: args.profile,
+            engine: args.engine,
+            model: args.model,
+            timeoutMs: args["timeout-ms"] === undefined ? undefined : parsePositiveIntFlag(args["timeout-ms"]),
             params: args.params,
             name: args.name,
             when_to_use: args["when-to-use"],
@@ -179,7 +183,7 @@ export const tasksCommand = defineGroupCommand({
     meta: {
         name: "tasks",
         alias: "task",
-        description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
+        description: "Schedule version-2 workflows, prompts, or commands via the OS-native scheduler (cron / launchd / schtasks)",
     },
     subCommands: {
         add: tasksAddCommand,