@united-workforce/cli 0.6.1 → 0.8.1

package/dist/cli.js

@@ -1,18 +1,31 @@
 #!/usr/bin/env -S node --disable-warning=ExperimentalWarning
-import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createCLI } from "@ocas/cli-kit";
+import { z } from "zod";
 import { cmdConfigGet, cmdConfigList, cmdConfigSet } from "./commands/config.js";
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdPromptAdapterDeveloping, cmdPromptBootstrap, cmdPromptList, cmdPromptUsage, cmdPromptWorkflowAuthoring, } from "./commands/prompt.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
-import { cmdStepAsk, cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
+import { cmdStepAsk, cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow, cmdStepTurns, } from "./commands/step.js";
 import { cmdThreadCancel, cmdThreadExec, cmdThreadJoin, cmdThreadList, cmdThreadPoke, cmdThreadRead, cmdThreadResume, cmdThreadShow, cmdThreadStart, cmdThreadStop, THREAD_READ_DEFAULT_QUOTA, } from "./commands/thread.js";
 import { parseTimeInput } from "./commands/thread-time-parser.js";
 import { cmdWorkflowAdd, cmdWorkflowList, cmdWorkflowShow, cmdWorkflowValidate, } from "./commands/workflow.js";
 import { formatOutput, isOutputFormat, SUPPORTED_FORMATS, writeEnvelope, } from "./format.js";
 import { toStepDetailPayload, toStepListPayload, toThreadExecPayload, toThreadListPayload, toThreadStartPayload, toThreadStatusPayload, toValidateResultPayload, toWorkflowAddPayload, toWorkflowDetailPayload, toWorkflowListPayload, } from "./output-mappers.js";
 import { createUwfStore, resolveStorageRoot } from "./store.js";
+// --- Package version (readFileSync replaces dynamic import) ---
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const VERSION = pkg.version;
+// --- Module-level state (cli-kit v0.2.1 workaround: no global --format) ---
+// Parsed from argv early, before cli-kit sees it.
+let formatOverride = null;
+// Parsed from argv early — cli-kit rejects values starting with `-`.
+let countOverride = null;
 function getFormat() {
-    const raw = program.opts().format;
+    const raw = formatOverride ?? "text";
     if (!isOutputFormat(raw)) {
         process.stderr.write(`Invalid --format: ${raw}. Must be one of: ${SUPPORTED_FORMATS.join(", ")}\n`);
         process.exit(1);
@@ -34,121 +47,18 @@ async function writeOutput(payload, schemaName, storageRoot) {
  * (the default) it renders via the per-command registry when available
  * and falls back to JSON.
  */
-function writeRawOutput(data, commandPath) {
+function writeRawOutput(data, commandPath = null) {
     const fmt = getFormat();
-    process.stdout.write(`${formatOutput(data, fmt, commandPath)}\n`);
+    process.stdout.write(`${formatOutput(data, fmt, commandPath ?? undefined)}\n`);
 }
 function runAction(action) {
-    action().catch((e) => {
+    return action().catch((e) => {
         const message = e instanceof Error ? e.message : String(e);
         process.stderr.write(`${message}\n`);
         process.exit(1);
     });
 }
-const program = new Command();
-// eslint-disable-next-line -- dynamic import for version
-const pkg = await import("../package.json", { with: { type: "json" } });
-program
-    .name("uwf")
-    .description("Stateless workflow CLI\n\n" +
-    "Four-layer architecture:\n" +
-    "  workflow → thread → step → turn")
-    .version(pkg.default.version, "-V, --version");
-program.option("--format <fmt>", "Output format: text (default), json, yaml, raw-json, raw-yaml", "text");
-const workflow = program
-    .command("workflow")
-    .description("Workflow definitions (layer 1: templates)");
-workflow
-    .command("add")
-    .description("Register a workflow from YAML")
-    .argument("<file>", "Workflow YAML file")
-    .action((file) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const result = await cmdWorkflowAdd(storageRoot, file);
-        await writeOutput(toWorkflowAddPayload(result), "workflow-add", storageRoot);
-    });
-});
-workflow
-    .command("validate")
-    .description("Validate a workflow YAML without registering it (CI-friendly)")
-    .argument("<file>", "Workflow YAML file")
-    .action((file) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const errors = await cmdWorkflowValidate(file);
-        await writeOutput(toValidateResultPayload(errors), "validate-result", storageRoot);
-        if (errors.length > 0) {
-            process.exit(1);
-        }
-    });
-});
-workflow
-    .command("show")
-    .description("Show a workflow by name or CAS hash")
-    .argument("<id>", "Workflow name or hash")
-    .action((id) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const result = await cmdWorkflowShow(storageRoot, id, process.cwd());
-        await writeOutput(toWorkflowDetailPayload(result), "workflow-detail", storageRoot);
-    });
-});
-workflow
-    .command("list")
-    .description("List registered workflows")
-    .action(() => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const result = await cmdWorkflowList(storageRoot, process.cwd());
-        await writeOutput(toWorkflowListPayload(result), "workflow-list", storageRoot);
-    });
-});
-const thread = program.command("thread").description("Thread execution (layer 2: instances)");
-thread
-    .command("start")
-    .description("Create a thread without executing")
-    .argument("<workflow>", "Workflow name or hash")
-    .requiredOption("-p, --prompt <text>", "User prompt")
-    .option("--cwd <path>", "Working directory for thread execution (default: process.cwd())")
-    .action((workflow, opts) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const result = await cmdThreadStart(storageRoot, workflow, opts.prompt, process.cwd(), opts.cwd ?? process.cwd());
-        await writeOutput(toThreadStartPayload(result), "thread-start", storageRoot);
-    });
-});
-thread
-    .command("exec")
-    .description("Execute one or more steps")
-    .argument("<thread-id>", "Thread ULID")
-    .option("--agent <cmd>", "Override agent command")
-    .option("-c, --count <number>", "Number of steps to run (default: 1)")
-    .option("--background", "Run in background and return immediately")
-    .option("--_background-worker", "Internal flag for background worker process", false)
-    .action((threadId, opts) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const agentOverride = opts.agent ?? null;
-        const count = opts.count !== undefined ? Number(opts.count) : 1;
-        const background = opts.background ?? false;
-        const backgroundWorker = opts._backgroundWorker ?? false;
-        const results = await cmdThreadExec(storageRoot, threadId, agentOverride, count, background, backgroundWorker);
-        await writeOutput(toThreadExecPayload(results), "thread-exec", storageRoot);
-    });
-});
-thread
-    .command("show")
-    .description("Show thread head pointer")
-    .argument("<thread-id>", "Thread ULID")
-    .action((threadId) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const result = await cmdThreadShow(storageRoot, threadId);
-        await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
-    });
-});
-// Helper functions for thread list command parsing
+// --- Helper functions for thread list / step turns parsing (unchanged) ---
 function parseStatusFilter(status) {
     if (status === undefined)
         return null;
@@ -203,87 +113,755 @@ function parsePaginationOptions(skip, take) {
     }
     return { skip: skipVal, take: takeVal };
 }
+/**
+ * Parse a `step turns` `--limit`/`--offset` value into a non-negative integer, or
+ * `null` when the flag is absent (the OCAS `ListOptions` "no limit" / offset-0
+ * convention). `--limit 0` is a legal value (renders no turns); negative or
+ * non-numeric values are a CLI usage error (exit non-zero). The `flag` label is
+ * used verbatim in the error message.
+ */
+function parseTurnsPageOption(flag, value) {
+    if (value === undefined) {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        process.stderr.write(`${flag} must be a non-negative integer\n`);
+        process.exit(1);
+    }
+    return Number.parseInt(trimmed, 10);
+}
+/**
+ * Resolve `thread list` pagination from both the canonical repo-wide
+ * `ListOptions` vocabulary (`--limit`/`--offset`, as used by `step turns`) and
+ * the backward-compatible legacy aliases (`--skip`/`--take`). The canonical
+ * flags map onto the existing `cmdThreadList` parameters: `--limit` → `take`
+ * (max items), `--offset` → `skip` (items skipped from the front of the
+ * newest-first list). When both a canonical flag and its legacy alias are
+ * supplied, the canonical flag wins and the alias is the fallback.
+ * `--limit`/`--offset` are validated via `parseTurnsPageOption` (same
+ * non-negative-integer rule and flag-named error as `step turns`); `--limit 0`
+ * is legal and yields no items (the `ListOptions` "no limit" convention treats
+ * an absent flag, not 0, as "all items").
+ */
+function resolveThreadListPagination(flags) {
+    const legacy = parsePaginationOptions(flags.skip, flags.take);
+    const limit = parseTurnsPageOption("--limit", flags.limit);
+    const offset = parseTurnsPageOption("--offset", flags.offset);
+    return {
+        skip: offset ?? legacy.skip,
+        take: limit ?? legacy.take,
+    };
+}
+// --- Positional arg helper (cli-kit workaround: custom missing-arg message) ---
+// cli-kit emits "Missing positional arguments" as NDJSON; tests expect a
+// plain "missing required argument" message on stderr. We don't declare
+// .arg() on commands and read positionals from the _positionals field that
+// cli-kit injects into the flags object.
+function getPositionals(flags) {
+    const p = flags._positionals;
+    return Array.isArray(p) ? p : [];
+}
+function requirePositional(flags, index, name) {
+    const positionals = getPositionals(flags);
+    const value = positionals[index];
+    if (value === undefined) {
+        process.stderr.write(`Error: missing required argument: ${name}\n`);
+        process.exit(1);
+    }
+    return value;
+}
+// --- Help text (cli-kit v0.2.1 workaround: no per-command --help) ---
+const TOP_LEVEL_HELP = `Usage: uwf <command> [options]
+
+Stateless workflow CLI
+
+Four-layer architecture:
+  workflow → thread → step → turn
+
+Commands:
+  workflow    Workflow definitions (layer 1: templates)
+  thread      Thread execution (layer 2: instances)
+  step        Step results (layer 3: single cycle)
+  prompt      Built-in prompt references for agents
+  setup       Configure the default agent
+  log         Process-level debug logs
+  config      Configuration management
+
+Standard flags:
+  --format <fmt>    Output format: text (default), json, yaml, raw-json, raw-yaml
+  -V, --version     Show version
+  -h, --help        Show this help
+`;
+const PROMPT_HELP = `Usage: uwf prompt <command>
+
+Built-in prompt references for agents
+
+Commands:
+  usage                Print the usage reference (CLI guide + typical workflows)
+  bootstrap            Print setup instructions for installing uwf skills
+  workflow-authoring   Print the workflow authoring reference (YAML design guide)
+  adapter-developing   Print the adapter developing reference (building agent adapters)
+  list                 List all available prompt names
+`;
+const WORKFLOW_HELP = `Usage: uwf workflow <command>
+
+Workflow definitions (layer 1: templates)
+
+Commands:
+  add       Register a workflow from YAML
+  validate  Validate a workflow YAML without registering it (CI-friendly)
+  show      Show a workflow by name or CAS hash
+  list      List registered workflows
+`;
+const WORKFLOW_ADD_HELP = `Usage: uwf workflow add <file>
+
+Register a workflow from YAML
+
+Arguments:
+  file  Workflow YAML file
+`;
+const WORKFLOW_VALIDATE_HELP = `Usage: uwf workflow validate <file>
+
+Validate a workflow YAML without registering it (CI-friendly)
+
+Arguments:
+  file  Workflow YAML file
+`;
+const WORKFLOW_SHOW_HELP = `Usage: uwf workflow show <id>
+
+Show a workflow by name or CAS hash
+
+Arguments:
+  id  Workflow name or hash
+`;
+const WORKFLOW_LIST_HELP = `Usage: uwf workflow list
+
+List registered workflows
+`;
+const THREAD_HELP = `Usage: uwf thread <command>
+
+Thread execution (layer 2: instances)
+
+Commands:
+  start    Create a thread without executing
+  exec     Execute one or more steps
+  show     Show thread head pointer
+  list     List threads (defaults to active: idle + running + corrupt)
+  resume   Resume a suspended thread and re-run the suspended role
+  poke     Re-run the head step's agent with a supplementary prompt
+  stop     Stop background execution of a thread (keep thread active)
+  cancel   Cancel a thread (stop execution and move to history)
+  join     Block until a running thread finishes, then return the final result
+  read     Read thread context as human-readable markdown
+`;
+const THREAD_START_HELP = `Usage: uwf thread start <workflow> [options]
+
+Create a thread without executing
+
+Arguments:
+  workflow  Workflow name or hash
+
+Options:
+  -p, --prompt <text>  User prompt (required)
+  --cwd <path>         Working directory for thread execution (default: process.cwd())
+`;
+const THREAD_EXEC_HELP = `Usage: uwf thread exec <thread-id> [options]
+
+Execute one or more steps
+
+Arguments:
+  thread-id  Thread ULID
+
+Options:
+  --agent <cmd>          Override agent command
+  -c, --count <number>   Number of steps to run (default: 1)
+  --background           Run in background and return immediately
+`;
+const THREAD_SHOW_HELP = `Usage: uwf thread show <thread-id>
+
+Show thread head pointer
+
+Arguments:
+  thread-id  Thread ULID
+`;
+const THREAD_LIST_HELP = `Usage: uwf thread list [options]
+
+List threads (defaults to active: idle + running + corrupt)
+
+Options:
+  --status <status>   Filter by status: idle, running, end, cancelled, active, or comma-separated
+  --all               Show all threads regardless of status
+  --after <date>      Filter threads created after this date
+  --before <date>     Filter threads created before this date
+  --limit <n>         Return at most n threads (newest first)
+  --offset <m>        Skip the first m threads (newest first)
+  --take <n>          Alias for --limit
+  --skip <n>          Alias for --offset
+`;
+const THREAD_RESUME_HELP = `Usage: uwf thread resume <thread-id> [options]
+
+Resume a suspended thread and re-run the suspended role
+
+Arguments:
+  thread-id  Thread ULID
+
+Options:
+  -p, --prompt <text>  Supplementary info to append to the resume prompt
+  --agent <cmd>        Override agent command
+`;
+const THREAD_POKE_HELP = `Usage: uwf thread poke <thread-id> [options]
+
+Re-run the head step's agent with a supplementary prompt (replaces head step)
+
+Arguments:
+  thread-id  Thread ULID
+
+Options:
+  -p, --prompt <text>  Supplementary prompt for the agent (required)
+  --agent <cmd>        Override agent command (defaults to head step's agent)
+`;
+const THREAD_STOP_HELP = `Usage: uwf thread stop <thread-id>
+
+Stop background execution of a thread (keep thread active)
+
+Arguments:
+  thread-id  Thread ULID
+`;
+const THREAD_CANCEL_HELP = `Usage: uwf thread cancel <thread-id>
+
+Cancel a thread (stop execution and move to history)
+
+Arguments:
+  thread-id  Thread ULID
+`;
+const THREAD_JOIN_HELP = `Usage: uwf thread join <thread-id> [options]
+
+Block until a running thread finishes, then return the final result
+
+Arguments:
+  thread-id  Thread ULID
+
+Options:
+  --timeout <seconds>  Max seconds to wait before giving up
+`;
+const THREAD_READ_HELP = `Usage: uwf thread read <thread-id> [options]
+
+Read thread context as human-readable markdown
+
+Arguments:
+  thread-id  Thread ULID
+
+Options:
+  --quota <chars>       Max output characters
+  --before <step-hash>  Load steps before this hash (exclusive)
+  --start               Include start step in output
+`;
+const STEP_HELP = `Usage: uwf step <command>
+
+Step results (layer 3: single cycle)
+
+Commands:
+  list   List all steps in a thread
+  show   Show details of a specific step
+  ask    Ask a follow-up question to a historical step's agent
+  read   Read a step's turns as human-readable markdown
+  turns  Show all turns across a thread's steps
+  fork   Fork a thread from a specific step
+`;
+const STEP_LIST_HELP = `Usage: uwf step list <thread-id>
+
+List all steps in a thread
+
+Arguments:
+  thread-id  Thread ULID
+`;
+const STEP_SHOW_HELP = `Usage: uwf step show <step-hash>
+
+Show details of a specific step
+
+Arguments:
+  step-hash  CAS hash of the StepNode
+`;
+const STEP_ASK_HELP = `Usage: uwf step ask <step-hash> [options]
+
+Ask a follow-up question to a historical step's agent (read-only; no thread mutation)
+
+Arguments:
+  step-hash  CAS hash of the StepNode to query
+
+Options:
+  -p, --prompt <text>  Question to ask the step's agent (required)
+  --agent <cmd>        Override agent command
+  --no-fork            Skip session-fork; spawn fresh ask session
+`;
+const STEP_READ_HELP = `Usage: uwf step read <step-hash> [options]
+
+Read a step's turns as human-readable markdown
+
+Arguments:
+  step-hash  CAS hash of the StepNode
+
+Options:
+  --quota <chars>  Max output characters (default: 4000)
+  --prompt         Show the assembled prompt sent to the agent
+`;
+const STEP_TURNS_HELP = `Usage: uwf step turns <thread-id> [options]
+
+Show all turns across a thread's steps (the whole-chain panorama)
+
+Arguments:
+  thread-id  Thread ULID
+
+Options:
+  --role <role>    Filter to one role's steps across the whole chain
+  --live           Follow the in-flight step's turns
+  --limit <n>      Max turns to show from the flattened cross-step sequence
+  --offset <n>     Skip the first N turns of the flattened cross-step sequence
+`;
+const STEP_FORK_HELP = `Usage: uwf step fork <step-hash>
+
+Fork a thread from a specific step
+
+Arguments:
+  step-hash  CAS hash of the StartNode or StepNode to fork from
+`;
+const SETUP_HELP = `Usage: uwf setup [options]
+
+Configure the default agent. Run without --agent for interactive wizard.
+
+Options:
+  --agent <name>  Default agent adapter (e.g. builtin, or a Sumeru gateway alias)
+`;
+const LOG_HELP = `Usage: uwf log <command>
+
+Process-level debug logs
+
+Commands:
+  list   List log files with sizes
+  show   Show and filter log entries
+  clean  Delete log files older than given date
+`;
+const LOG_LIST_HELP = `Usage: uwf log list
+
+List log files with sizes
+`;
+const LOG_SHOW_HELP = `Usage: uwf log show [options]
+
+Show and filter log entries
+
+Options:
+  --thread <thread-id>  Filter by thread ID
+  --process <pid>       Filter by process ID
+  --date <date>         Filter by date (YYYY-MM-DD)
+`;
+const LOG_CLEAN_HELP = `Usage: uwf log clean --before <date>
+
+Delete log files older than given date
+
+Options:
+  --before <date>  Delete files before this date (YYYY-MM-DD) (required)
+`;
+const CONFIG_HELP = `Usage: uwf config <command>
+
+Configuration management
+
+Commands:
+  list  Display all configuration values (masks API keys)
+  get   Get a specific configuration value
+  set   Set a specific configuration value
+`;
+const CONFIG_LIST_HELP = `Usage: uwf config list
+
+Display all configuration values (masks API keys)
+`;
+const CONFIG_GET_HELP = `Usage: uwf config get <key>
+
+Get a specific configuration value
+
+Arguments:
+  key  Dot-notation path to config value
+`;
+const CONFIG_SET_HELP = `Usage: uwf config set <key> <value>
+
+Set a specific configuration value
+
+Arguments:
+  key    Dot-notation path to config value
+  value  New value (use JSON array for 'args' key)
+`;
+const HELP_MAP = {
+    "": TOP_LEVEL_HELP,
+    prompt: PROMPT_HELP,
+    workflow: WORKFLOW_HELP,
+    "workflow add": WORKFLOW_ADD_HELP,
+    "workflow validate": WORKFLOW_VALIDATE_HELP,
+    "workflow show": WORKFLOW_SHOW_HELP,
+    "workflow list": WORKFLOW_LIST_HELP,
+    thread: THREAD_HELP,
+    "thread start": THREAD_START_HELP,
+    "thread exec": THREAD_EXEC_HELP,
+    "thread show": THREAD_SHOW_HELP,
+    "thread list": THREAD_LIST_HELP,
+    "thread resume": THREAD_RESUME_HELP,
+    "thread poke": THREAD_POKE_HELP,
+    "thread stop": THREAD_STOP_HELP,
+    "thread cancel": THREAD_CANCEL_HELP,
+    "thread join": THREAD_JOIN_HELP,
+    "thread read": THREAD_READ_HELP,
+    step: STEP_HELP,
+    "step list": STEP_LIST_HELP,
+    "step show": STEP_SHOW_HELP,
+    "step ask": STEP_ASK_HELP,
+    "step read": STEP_READ_HELP,
+    "step turns": STEP_TURNS_HELP,
+    "step fork": STEP_FORK_HELP,
+    setup: SETUP_HELP,
+    log: LOG_HELP,
+    "log list": LOG_LIST_HELP,
+    "log show": LOG_SHOW_HELP,
+    "log clean": LOG_CLEAN_HELP,
+    config: CONFIG_HELP,
+    "config list": CONFIG_LIST_HELP,
+    "config get": CONFIG_GET_HELP,
+    "config set": CONFIG_SET_HELP,
+};
+// --- Early intercepts (cli-kit v0.2.1 workarounds) ---
+/** Print help text for the command path extracted from argv, then exit. */
+function printHelp(argv) {
+    const helpIdx = argv.findIndex((t) => t === "--help" || t === "-h");
+    const tokens = helpIdx >= 0 ? argv.slice(0, helpIdx).filter((t) => !t.startsWith("-")) : [];
+    for (let len = tokens.length; len >= 0; len--) {
+        const path = tokens.slice(0, len).join(" ");
+        const text = HELP_MAP[path];
+        if (text !== undefined) {
+            process.stdout.write(text);
+            process.exit(0);
+        }
+    }
+    process.stdout.write(TOP_LEVEL_HELP);
+    process.exit(0);
+}
+/** Intercept deprecated commands before cli-kit parsing. Prints message + exit(1). */
+function handleDeprecated(argv) {
+    const [cmd, sub] = argv;
+    if (cmd === "workflow" && sub === "put") {
+        process.stderr.write(`Error: Command 'workflow put' has been removed.
+Use 'workflow add' instead.
+
+For more information, see: uwf help workflow add
+`);
+        process.exit(1);
+    }
+    if (cmd === "thread") {
+        if (sub === "step") {
+            process.stderr.write(`Error: Command 'thread step' has been removed.
+Use 'thread exec' instead.
+
+For more information, see: uwf help thread exec
+`);
+            process.exit(1);
+        }
+        if (sub === "steps") {
+            process.stderr.write(`Error: Command 'thread steps' has been removed.
+Use 'step list' instead.
+
+For more information, see: uwf help step list
+`);
+            process.exit(1);
+        }
+        if (sub === "step-details") {
+            process.stderr.write(`Error: Command 'thread step-details' has been removed.
+Use 'step show' instead.
+
+For more information, see: uwf help step show
+`);
+            process.exit(1);
+        }
+        if (sub === "fork") {
+            process.stderr.write(`Error: Command 'thread fork' has been removed.
+Use 'step fork' instead.
+
+For more information, see: uwf help step fork
+`);
+            process.exit(1);
+        }
+        if (sub === "kill") {
+            process.stderr.write(`Error: Command 'thread kill' has been removed.
+Use 'thread stop' to stop background execution (keep thread active),
+or 'thread cancel' to cancel and archive the thread.
+
+For more information, see:
+  uwf help thread stop
+  uwf help thread cancel
+`);
+            process.exit(1);
+        }
+        if (sub === "running") {
+            process.stderr.write(`Error: Command 'thread running' has been removed.
+Use 'thread list --status running' instead.
+
+For more information, see: uwf help thread list
+`);
+            process.exit(1);
+        }
+    }
+}
+/** Strip `--format <value>` / `--format=value` from argv, returning cleaned argv. */
+function stripFormatFlag(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--format") {
+            const value = argv[i + 1];
+            if (value !== undefined) {
+                formatOverride = value;
+                i++;
+            }
+            continue;
+        }
+        if (token.startsWith("--format=")) {
+            formatOverride = token.slice("--format=".length);
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+/** Strip `--count <value>` / `--count=value` / `-c <value>` from argv. */
+function stripCountFlag(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--count" || token === "-c") {
+            const value = argv[i + 1];
+            if (value !== undefined) {
+                countOverride = value;
+                i++;
+            }
+            continue;
+        }
+        if (token.startsWith("--count=")) {
+            countOverride = token.slice("--count=".length);
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+// --- Build CLI with @ocas/cli-kit ---
+const cli = createCLI({
+    name: "uwf",
+    version: VERSION,
+});
+const unknownSchema = z.unknown();
+// ── workflow group ───────────────────────────────────────────────────────────
+const workflow = cli.command("workflow");
+workflow
+    .command("add")
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const file = requirePositional(flags, 0, "file");
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const result = await cmdWorkflowAdd(storageRoot, file);
+        await writeOutput(toWorkflowAddPayload(result), "workflow-add", storageRoot);
+    });
+    return undefined;
+});
+workflow
+    .command("validate")
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const file = requirePositional(flags, 0, "file");
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const errors = await cmdWorkflowValidate(file);
+        await writeOutput(toValidateResultPayload(errors), "validate-result", storageRoot);
+        if (errors.length > 0) {
+            process.exit(1);
+        }
+    });
+    return undefined;
+});
+workflow
+    .command("show")
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const id = requirePositional(flags, 0, "id");
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const result = await cmdWorkflowShow(storageRoot, id, process.cwd());
+        await writeOutput(toWorkflowDetailPayload(result), "workflow-detail", storageRoot);
+    });
+    return undefined;
+});
+workflow
+    .command("list")
+    .returns(unknownSchema, "")
+    .action(async () => {
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const result = await cmdWorkflowList(storageRoot, process.cwd());
+        await writeOutput(toWorkflowListPayload(result), "workflow-list", storageRoot);
+    });
+    return undefined;
+});
+// ── thread group ─────────────────────────────────────────────────────────────
+const thread = cli.command("thread");
+thread
+    .command("start")
+    .flag("prompt", { type: "string" })
+    .flag("p", { type: "string" })
+    .flag("cwd", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const workflowName = requirePositional(flags, 0, "workflow");
+    const prompt = flags.prompt ?? flags.p;
+    if (prompt === undefined) {
+        process.stderr.write("Error: missing required option: -p, --prompt <text>\n");
+        process.exit(1);
+    }
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const result = await cmdThreadStart(storageRoot, workflowName, prompt, process.cwd(), flags.cwd ?? process.cwd());
+        await writeOutput(toThreadStartPayload(result), "thread-start", storageRoot);
+    });
+    return undefined;
+});
+thread
+    .command("exec")
+    .flag("agent", { type: "string" })
+    .flag("background", { type: "boolean", default: false })
+    .flag("_background-worker", { type: "boolean", default: false })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const agentOverride = flags.agent ?? null;
+        const count = countOverride !== null ? Number(countOverride) : 1;
+        const background = flags.background;
+        const backgroundWorker = flags["_background-worker"] ?? false;
+        const results = await cmdThreadExec(storageRoot, threadId, agentOverride, count, background, backgroundWorker);
+        await writeOutput(toThreadExecPayload(results), "thread-exec", storageRoot);
+    });
+    return undefined;
+});
+thread
+    .command("show")
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const result = await cmdThreadShow(storageRoot, threadId);
+        await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
+    });
+    return undefined;
+});
 thread
     .command("list")
-    .description("List threads (defaults to active: idle + running + corrupt)")
-    .option("--status <status>", "Filter by status: idle, running, end, cancelled, active (idle+running), or comma-separated values")
-    .option("--all", "Show all threads regardless of status (overrides default active-only filter)")
-    .option("--after <date>", "Filter threads created after this date (ISO or relative like '7d')")
-    .option("--before <date>", "Filter threads created before this date (ISO or relative like '7d')")
-    .option("--skip <n>", "Skip first n threads")
-    .option("--take <n>", "Return at most n threads")
-    .action((opts) => {
+    .flag("status", { type: "string" })
+    .flag("all", { type: "boolean", default: false })
+    .flag("after", { type: "string" })
+    .flag("before", { type: "string" })
+    .flag("skip", { type: "string" })
+    .flag("take", { type: "string" })
+    .flag("limit", { type: "string" })
+    .flag("offset", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const statusFilter = parseStatusFilter(opts.status);
+    await runAction(async () => {
+        const statusFilter = parseStatusFilter(flags.status);
         const nowMs = Date.now();
-        const { afterMs, beforeMs } = parseTimeFilters(opts.after, opts.before, nowMs);
-        const { skip, take } = parsePaginationOptions(opts.skip, opts.take);
-        const showAll = opts.all === true;
+        const { afterMs, beforeMs } = parseTimeFilters(flags.after, flags.before, nowMs);
+        const { skip, take } = resolveThreadListPagination({
+            skip: flags.skip,
+            take: flags.take,
+            limit: flags.limit,
+            offset: flags.offset,
+        });
+        const showAll = flags.all === true;
         const result = await cmdThreadList(storageRoot, statusFilter, afterMs, beforeMs, skip, take, showAll);
         await writeOutput(toThreadListPayload(result), "thread-list", storageRoot);
     });
+    return undefined;
 });
 thread
     .command("resume")
-    .description("Resume a suspended thread and re-run the suspended role")
-    .argument("<thread-id>", "Thread ULID")
-    .option("-p, --prompt <text>", "Supplementary info to append to the resume prompt")
-    .option("--agent <cmd>", "Override agent command")
-    .action((threadId, opts) => {
+    .flag("prompt", { type: "string" })
+    .flag("p", { type: "string" })
+    .flag("agent", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const supplement = opts.prompt ?? null;
-        const agentOverride = opts.agent ?? null;
+    const prompt = flags.prompt ?? flags.p;
+    await runAction(async () => {
+        const supplement = prompt ?? null;
+        const agentOverride = flags.agent ?? null;
         const result = await cmdThreadResume(storageRoot, threadId, supplement, agentOverride);
         await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
+    return undefined;
 });
 thread
     .command("poke")
-    .description("Re-run the head step's agent with a supplementary prompt (replaces head step)")
-    .argument("<thread-id>", "Thread ULID")
-    .requiredOption("-p, --prompt <text>", "Supplementary prompt for the agent")
-    .option("--agent <cmd>", "Override agent command (defaults to head step's agent)")
-    .action((threadId, opts) => {
+    .flag("prompt", { type: "string" })
+    .flag("p", { type: "string" })
+    .flag("agent", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
+    const prompt = flags.prompt ?? flags.p;
+    if (prompt === undefined) {
+        process.stderr.write("Error: missing required option: -p, --prompt <text>\n");
+        process.exit(1);
+    }
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const agentOverride = opts.agent ?? null;
-        const result = await cmdThreadPoke(storageRoot, threadId, opts.prompt, agentOverride);
+    await runAction(async () => {
+        const agentOverride = flags.agent ?? null;
+        const result = await cmdThreadPoke(storageRoot, threadId, prompt, agentOverride);
         await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
+    return undefined;
 });
 thread
     .command("stop")
-    .description("Stop background execution of a thread (keep thread active)")
-    .argument("<thread-id>", "Thread ULID")
-    .action((threadId) => {
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdThreadStop(storageRoot, threadId);
         writeRawOutput(result, "thread stop");
     });
+    return undefined;
 });
 thread
     .command("cancel")
-    .description("Cancel a thread (stop execution and move to history)")
-    .argument("<thread-id>", "Thread ULID")
-    .action((threadId) => {
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdThreadCancel(storageRoot, threadId);
         writeRawOutput(result, "thread cancel");
     });
+    return undefined;
 });
 thread
     .command("join")
-    .description("Block until a running thread finishes, then return the final result")
-    .argument("<thread-id>", "Thread ULID")
-    .option("--timeout <seconds>", "Max seconds to wait before giving up")
-    .action((threadId, opts) => {
+    .flag("timeout", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const timeoutMs = opts.timeout !== undefined ? Number(opts.timeout) * 1000 : null;
+    await runAction(async () => {
+        const timeoutRaw = flags.timeout;
+        const timeoutMs = timeoutRaw !== undefined ? Number(timeoutRaw) * 1000 : null;
         if (timeoutMs !== null && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
             process.stderr.write("invalid --timeout: must be a positive number\n");
             process.exit(1);
@@ -291,311 +869,299 @@ thread
         const results = await cmdThreadJoin(storageRoot, threadId, timeoutMs);
         await writeOutput(toThreadExecPayload(results), "thread-exec", storageRoot);
     });
+    return undefined;
 });
 thread
     .command("read")
-    .description("Read thread context as human-readable markdown")
-    .argument("<thread-id>", "Thread ULID")
-    .option("--quota <chars>", "Max output characters", String(THREAD_READ_DEFAULT_QUOTA))
-    .option("--before <step-hash>", "Load steps before this hash (exclusive)")
-    .option("--start", "Include start step in output")
-    .action((threadId, opts) => {
+    .flag("quota", { type: "string", default: String(THREAD_READ_DEFAULT_QUOTA) })
+    .flag("before", { type: "string" })
+    .flag("start", { type: "boolean", default: false })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const quota = Number.parseInt(opts.quota, 10);
+    await runAction(async () => {
+        const quota = Number.parseInt(flags.quota, 10);
         if (!Number.isFinite(quota) || quota < 1) {
             process.stderr.write("invalid --quota: must be a positive integer\n");
             process.exit(1);
         }
-        const before = opts.before ?? null;
-        const markdown = await cmdThreadRead(storageRoot, threadId, quota, before, opts.start ?? false);
+        const before = flags.before ?? null;
+        const markdown = await cmdThreadRead(storageRoot, threadId, quota, before, flags.start ?? false);
         process.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
     });
+    return undefined;
 });
-const step = program.command("step").description("Step results (layer 3: single cycle)");
+// ── step group ───────────────────────────────────────────────────────────────
+const step = cli.command("step");
 step
     .command("list")
-    .description("List all steps in a thread")
-    .argument("<thread-id>", "Thread ULID")
-    .action((threadId) => {
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdStepList(storageRoot, threadId);
         await writeOutput(toStepListPayload(result), "step-list", storageRoot);
     });
+    return undefined;
 });
 step
     .command("show")
-    .description("Show details of a specific step")
-    .argument("<step-hash>", "CAS hash of the StepNode")
-    .action((stepHash) => {
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const stepHash = requirePositional(flags, 0, "step-hash");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const detail = await cmdStepShow(storageRoot, stepHash);
         await writeOutput(toStepDetailPayload(stepHash, detail), "step-detail", storageRoot);
     });
+    return undefined;
 });
 step
     .command("ask")
-    .description("Ask a follow-up question to a historical step's agent (read-only; no thread mutation)")
-    .argument("<step-hash>", "CAS hash of the StepNode to query")
-    .requiredOption("-p, --prompt <text>", "Question to ask the step's agent")
-    .option("--agent <cmd>", "Override agent command (defaults to the step's recorded agent)")
-    .option("--no-fork", "Skip session-fork; spawn the agent in a fresh ask session and inject the step's detail ref for context")
-    .action((stepHash, opts) => {
+    .flag("prompt", { type: "string" })
+    .flag("p", { type: "string" })
+    .flag("agent", { type: "string" })
+    .flag("no-fork", { type: "boolean", default: false })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const stepHash = requirePositional(flags, 0, "step-hash");
+    const prompt = flags.prompt ?? flags.p;
+    if (prompt === undefined) {
+        process.stderr.write("Error: missing required option: -p, --prompt <text>\n");
+        process.exit(1);
+    }
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const stdout = await cmdStepAsk(storageRoot, stepHash, {
-            prompt: opts.prompt,
-            agentOverride: opts.agent ?? null,
-            fork: opts.fork,
+            prompt,
+            agentOverride: flags.agent ?? null,
+            fork: !flags["no-fork"],
         });
         process.stdout.write(stdout.endsWith("\n") ? stdout : `${stdout}\n`);
     });
+    return undefined;
 });
 step
     .command("read")
-    .description("Read a step's turns as human-readable markdown")
-    .argument("<step-hash>", "CAS hash of the StepNode")
-    .option("--quota <chars>", "Max output characters", "4000")
-    .option("--prompt", "Show the assembled prompt sent to the agent instead of turns")
-    .action((stepHash, opts) => {
+    .flag("quota", { type: "string", default: "4000" })
+    .flag("prompt", { type: "boolean", default: false })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const stepHash = requirePositional(flags, 0, "step-hash");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const quota = Number.parseInt(opts.quota, 10);
+    await runAction(async () => {
+        const quota = Number.parseInt(flags.quota, 10);
         if (!Number.isFinite(quota) || quota < 1) {
             process.stderr.write("invalid --quota: must be a positive integer\n");
             process.exit(1);
         }
-        const markdown = await cmdStepRead(storageRoot, stepHash, quota, opts.prompt === true);
+        const markdown = await cmdStepRead(storageRoot, stepHash, quota, flags.prompt === true);
         process.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
     });
+    return undefined;
+});
+step
+    .command("turns")
+    .flag("role", { type: "string" })
+    .flag("live", { type: "boolean", default: false })
+    .flag("limit", { type: "string" })
+    .flag("offset", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const threadId = requirePositional(flags, 0, "thread-id");
+    const storageRoot = resolveStorageRoot();
+    await runAction(async () => {
+        const limit = parseTurnsPageOption("--limit", flags.limit);
+        const offset = parseTurnsPageOption("--offset", flags.offset) ?? 0;
+        const markdown = await cmdStepTurns(storageRoot, threadId, {
+            role: flags.role ?? null,
+            live: flags.live === true,
+            limit,
+            offset,
+        });
+        if (markdown !== "") {
+            process.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
+        }
+    });
+    return undefined;
 });
 step
     .command("fork")
-    .description("Fork a thread from a specific step")
-    .argument("<step-hash>", "CAS hash of the StartNode or StepNode to fork from")
-    .action((stepHash) => {
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const stepHash = requirePositional(flags, 0, "step-hash");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdStepFork(storageRoot, stepHash);
         writeRawOutput(result);
     });
+    return undefined;
 });
-// ── Deprecation Handlers ──────────────────────────────────────────────────────
-// These commands have been removed. Show helpful error messages.
-workflow
-    .command("put")
-    .description("[DEPRECATED] Use 'workflow add' instead")
-    .argument("<file>", "Workflow YAML file")
-    .action(() => {
-    process.stderr.write(`Error: Command 'workflow put' has been removed.
-Use 'workflow add' instead.
-
-For more information, see: uwf help workflow add
-`);
-    process.exit(1);
-});
-thread
-    .command("step")
-    .description("[DEPRECATED] Use 'thread exec' instead")
-    .argument("<thread-id>", "Thread ULID")
-    .allowUnknownOption()
-    .action(() => {
-    process.stderr.write(`Error: Command 'thread step' has been removed.
-Use 'thread exec' instead.
-
-For more information, see: uwf help thread exec
-`);
-    process.exit(1);
-});
-thread
-    .command("steps")
-    .description("[DEPRECATED] Use 'step list' instead")
-    .argument("<thread-id>", "Thread ULID")
-    .action(() => {
-    process.stderr.write(`Error: Command 'thread steps' has been removed.
-Use 'step list' instead.
-
-For more information, see: uwf help step list
-`);
-    process.exit(1);
-});
-thread
-    .command("step-details")
-    .description("[DEPRECATED] Use 'step show' instead")
-    .argument("<step-hash>", "Step hash")
-    .action(() => {
-    process.stderr.write(`Error: Command 'thread step-details' has been removed.
-Use 'step show' instead.
-
-For more information, see: uwf help step show
-`);
-    process.exit(1);
-});
-thread
-    .command("fork")
-    .description("[DEPRECATED] Use 'step fork' instead")
-    .argument("<step-hash>", "Step hash")
-    .action(() => {
-    process.stderr.write(`Error: Command 'thread fork' has been removed.
-Use 'step fork' instead.
-
-For more information, see: uwf help step fork
-`);
-    process.exit(1);
-});
-thread
-    .command("kill")
-    .description("[DEPRECATED] Use 'thread stop' or 'thread cancel' instead")
-    .argument("<thread-id>", "Thread ULID")
-    .action(() => {
-    process.stderr.write(`Error: Command 'thread kill' has been removed.
-Use 'thread stop' to stop background execution (keep thread active),
-or 'thread cancel' to cancel and archive the thread.
-
-For more information, see:
-  uwf help thread stop
-  uwf help thread cancel
-`);
-    process.exit(1);
-});
-thread
-    .command("running")
-    .description("[DEPRECATED] Use 'thread list --status running' instead")
-    .action(() => {
-    process.stderr.write(`Error: Command 'thread running' has been removed.
-Use 'thread list --status running' instead.
-
-For more information, see: uwf help thread list
-`);
-    process.exit(1);
-});
-const prompt = program.command("prompt").description("Built-in prompt references for agents");
-prompt.addHelpCommand(false);
-prompt
+// ── prompt group ─────────────────────────────────────────────────────────────
+const promptGroup = cli.command("prompt");
+promptGroup
     .command("usage")
-    .description("Print the usage reference (CLI guide + typical workflows)")
-    .action(() => {
+    .returns(unknownSchema, "")
+    .action(async () => {
     console.log(cmdPromptUsage());
+    return undefined;
 });
-prompt
+promptGroup
     .command("bootstrap")
-    .description("Print setup instructions for installing uwf skills")
-    .action(() => {
+    .returns(unknownSchema, "")
+    .action(async () => {
     console.log(cmdPromptBootstrap());
+    return undefined;
 });
-prompt
+promptGroup
     .command("workflow-authoring")
-    .description("Print the workflow authoring reference (YAML design guide)")
-    .action(() => {
+    .returns(unknownSchema, "")
+    .action(async () => {
     console.log(cmdPromptWorkflowAuthoring());
+    return undefined;
 });
-prompt
+promptGroup
     .command("adapter-developing")
-    .description("Print the adapter developing reference (building agent adapters)")
-    .action(() => {
+    .returns(unknownSchema, "")
+    .action(async () => {
     console.log(cmdPromptAdapterDeveloping());
+    return undefined;
 });
-prompt
+promptGroup
     .command("list")
-    .description("List all available prompt names")
-    .action(() => {
+    .returns(unknownSchema, "")
+    .action(async () => {
     console.log(cmdPromptList().join("\n"));
+    return undefined;
 });
-program
+// ── setup (top-level) ────────────────────────────────────────────────────────
+cli
     .command("setup")
-    .description("Configure the default agent. Run without --agent for interactive wizard.\n" +
-    "Each adapter owns its own LLM configuration — the engine config is LLM-free.")
-    .option("--agent <name>", "Default agent adapter (e.g. hermes → uwf-hermes)")
-    .action((opts) => {
+    .flag("agent", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        if (opts.agent !== undefined && opts.agent !== "") {
-            const result = await cmdSetup({ agent: opts.agent, storageRoot });
+    const agent = flags.agent;
+    await runAction(async () => {
+        if (agent !== undefined && agent !== "") {
+            const result = await cmdSetup({ agent, storageRoot });
             writeRawOutput(result);
         }
         else {
             await cmdSetupInteractive(storageRoot);
         }
     });
+    return undefined;
 });
-const log = program.command("log").description("Process-level debug logs");
+// ── log group ────────────────────────────────────────────────────────────────
+const log = cli.command("log");
 log
     .command("list")
-    .description("List log files with sizes")
-    .action(() => {
+    .returns(unknownSchema, "")
+    .action(async () => {
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdLogList(storageRoot);
         writeRawOutput(result, "log list");
     });
+    return undefined;
 });
 log
     .command("show")
-    .description("Show and filter log entries")
-    .option("--thread <thread-id>", "Filter by thread ID")
-    .option("--process <pid>", "Filter by process ID")
-    .option("--date <date>", "Filter by date (YYYY-MM-DD)")
-    .action((opts) => {
+    .flag("thread", { type: "string" })
+    .flag("process", { type: "string" })
+    .flag("date", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdLogShow(storageRoot, {
-            thread: opts.thread ?? null,
-            process: opts.process ?? null,
-            date: opts.date ?? null,
+            thread: flags.thread ?? null,
+            process: flags.process ?? null,
+            date: flags.date ?? null,
         });
         writeRawOutput(result, "log show");
     });
+    return undefined;
 });
 log
     .command("clean")
-    .description("Delete log files older than given date")
-    .requiredOption("--before <date>", "Delete files before this date (YYYY-MM-DD)")
-    .action((opts) => {
+    .flag("before", { type: "string" })
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const before = flags.before;
+    if (before === undefined) {
+        process.stderr.write("Error: missing required option: --before <date>\n");
+        process.exit(1);
+    }
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-        const result = await cmdLogClean(storageRoot, opts.before);
+    await runAction(async () => {
+        const result = await cmdLogClean(storageRoot, before);
         writeRawOutput(result);
     });
+    return undefined;
 });
-const config = program.command("config").description("Configuration management");
+// ── config group ─────────────────────────────────────────────────────────────
+const config = cli.command("config");
 config
     .command("list")
-    .description("Display all configuration values (masks API keys)")
-    .action(() => {
+    .returns(unknownSchema, "")
+    .action(async () => {
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdConfigList(storageRoot);
         writeRawOutput(result, "config list");
     });
+    return undefined;
 });
 config
     .command("get")
-    .description("Get a specific configuration value")
-    .argument("<key>", "Dot-notation path to config value (e.g., defaultAgent, providers.dashscope.baseUrl)")
-    .action((key) => {
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const key = requirePositional(flags, 0, "key");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdConfigGet(storageRoot, key);
         writeRawOutput({ value: result }, "config get");
     });
+    return undefined;
 });
 config
     .command("set")
-    .description("Set a specific configuration value")
-    .argument("<key>", "Dot-notation path to config value")
-    .argument("<value>", "New value (use JSON array for 'args' key, e.g., '[\"--flag\"]')")
-    .action((key, value) => {
+    .returns(unknownSchema, "")
+    .action(async (_args, flags) => {
+    const key = requirePositional(flags, 0, "key");
+    const value = requirePositional(flags, 1, "value");
     const storageRoot = resolveStorageRoot();
-    runAction(async () => {
+    await runAction(async () => {
         const result = await cmdConfigSet(storageRoot, key, value);
         writeRawOutput(result, "config set");
     });
+    return undefined;
 });
-program.parseAsync(process.argv).catch((e) => {
-    const message = e instanceof Error ? e.message : String(e);
-    process.stderr.write(`${message}\n`);
-    process.exit(1);
-});
+// --- Main execution: early intercepts + cli.run() ---
+const rawArgv = process.argv.slice(2);
+// 1. --version / -V (cli-kit doesn't handle these)
+const firstToken = rawArgv[0];
+if (firstToken === "--version" || firstToken === "-V") {
+    process.stdout.write(`${VERSION}\n`);
+    process.exit(0);
+}
+// 2. Strip --format (cli-kit has no global --format; parse into module-level var)
+const argvNoFormat = stripFormatFlag(rawArgv);
+// 3. --help / -h / no args (cli-kit has no per-command --help)
+if (argvNoFormat.length === 0 || argvNoFormat.includes("--help") || argvNoFormat.includes("-h")) {
+    printHelp(argvNoFormat);
+}
+// 4. Deprecated commands (intercept before cli-kit parsing)
+handleDeprecated(argvNoFormat);
+// 5. Strip --count / -c (cli-kit rejects values starting with `-`)
+const argvNoCount = stripCountFlag(argvNoFormat);
+// 6. Run cli-kit
+const exitCode = await cli.run({ argv: argvNoCount });
+if (exitCode !== 0) {
+    process.exit(exitCode);
+}
 //# sourceMappingURL=cli.js.map