@united-workforce/cli 0.3.0 → 0.5.0

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
-import type { CasRef, ThreadId, ThreadStatus } from "@united-workforce/protocol";
+import type { CasRef, OutputSchemaName, ThreadId, ThreadStatus } from "@united-workforce/protocol";
 import { Command } from "commander";
 import { cmdConfigGet, cmdConfigList, cmdConfigSet } from "./commands/config.js";
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
@@ -11,12 +11,13 @@ import {
   cmdPromptUsage,
   cmdPromptWorkflowAuthoring,
 } from "./commands/prompt.js";
-import { cmdSetup, cmdSetupInteractive, resolvePresetBaseUrl } from "./commands/setup.js";
-import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
+import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import { cmdStepAsk, cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
   cmdThreadCancel,
   cmdThreadExec,
   cmdThreadList,
+  cmdThreadPoke,
   cmdThreadRead,
   cmdThreadResume,
   cmdThreadShow,
@@ -25,13 +26,67 @@ import {
   THREAD_READ_DEFAULT_QUOTA,
 } from "./commands/thread.js";
 import { parseTimeInput } from "./commands/thread-time-parser.js";
-import { cmdWorkflowAdd, cmdWorkflowList, cmdWorkflowShow } from "./commands/workflow.js";
-import { formatOutput, type OutputFormat } from "./format.js";
-import { resolveStorageRoot } from "./store.js";
+import {
+  cmdWorkflowAdd,
+  cmdWorkflowList,
+  cmdWorkflowShow,
+  cmdWorkflowValidate,
+} from "./commands/workflow.js";
+import {
+  formatOutput,
+  isOutputFormat,
+  type OutputFormat,
+  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";
+
+function getFormat(): OutputFormat {
+  const raw = program.opts().format as string;
+  if (!isOutputFormat(raw)) {
+    process.stderr.write(
+      `Invalid --format: ${raw}. Must be one of: ${SUPPORTED_FORMATS.join(", ")}\n`,
+    );
+    process.exit(1);
+  }
+  return raw;
+}
+
+async function writeOutput(
+  payload: unknown,
+  schemaName: OutputSchemaName,
+  storageRoot: string,
+): Promise<void> {
+  const fmt = getFormat();
+  const uwf = await createUwfStore(storageRoot);
+  await writeEnvelope(payload, schemaName, {
+    format: fmt,
+    store: uwf.store,
+    schemas: uwf.schemas,
+  });
+}
 
-function writeOutput(data: unknown): void {
-  const fmt = program.opts().format as OutputFormat;
-  process.stdout.write(`${formatOutput(data, fmt)}\n`);
+/**
+ * Legacy raw output for commands without an output schema (log/config/setup).
+ * Always emits text/JSON/YAML based on the active --format. For `text`
+ * (the default) it renders via the per-command registry when available
+ * and falls back to JSON.
+ */
+function writeRawOutput(data: unknown, commandPath?: string): void {
+  const fmt = getFormat();
+  process.stdout.write(`${formatOutput(data, fmt, commandPath)}\n`);
 }
 
 function runAction(action: () => Promise<void>): void {
@@ -54,7 +109,11 @@ program
       "  workflow → thread → step → turn",
   )
   .version(pkg.default.version, "-V, --version");
-program.option("--format <fmt>", "Output format: json or yaml", "json");
+program.option(
+  "--format <fmt>",
+  "Output format: text (default), json, yaml, raw-json, raw-yaml",
+  "text",
+);
 
 const workflow = program
   .command("workflow")
@@ -68,7 +127,22 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowAdd(storageRoot, file);
-      writeOutput(result);
+      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: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const errors = await cmdWorkflowValidate(file);
+      await writeOutput(toValidateResultPayload(errors), "validate-result", storageRoot);
+      if (errors.length > 0) {
+        process.exit(1);
+      }
     });
   });
 
@@ -79,8 +153,8 @@ workflow
   .action((id: string) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdWorkflowShow(storageRoot, id);
-      writeOutput(result);
+      const result = await cmdWorkflowShow(storageRoot, id, process.cwd());
+      await writeOutput(toWorkflowDetailPayload(result), "workflow-detail", storageRoot);
     });
   });
 
@@ -91,7 +165,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowList(storageRoot, process.cwd());
-      writeOutput(result);
+      await writeOutput(toWorkflowListPayload(result), "workflow-list", storageRoot);
     });
   });
 
@@ -113,7 +187,7 @@ thread
         process.cwd(),
         opts.cwd ?? process.cwd(),
       );
-      writeOutput(result);
+      await writeOutput(toThreadStartPayload(result), "thread-start", storageRoot);
     });
   });
 
@@ -150,11 +224,7 @@ thread
           background,
           backgroundWorker,
         );
-        if (results.length === 1) {
-          writeOutput(results[0]);
-        } else {
-          writeOutput(results);
-        }
+        await writeOutput(toThreadExecPayload(results), "thread-exec", storageRoot);
       });
     },
   );
@@ -167,7 +237,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadShow(storageRoot, threadId);
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -178,11 +248,18 @@ function parseStatusFilter(status: string | undefined): ThreadStatus[] | null {
   if (raw === "active") return ["idle", "running"];
 
   const parts = raw.split(",").map((s) => s.trim());
-  const validStatuses: ThreadStatus[] = ["idle", "running", "suspended", "completed", "cancelled"];
+  const validStatuses: ThreadStatus[] = [
+    "idle",
+    "running",
+    "suspended",
+    "end",
+    "cancelled",
+    "corrupt",
+  ];
   for (const part of parts) {
     if (!validStatuses.includes(part as ThreadStatus)) {
       process.stderr.write(
-        `Invalid status: ${part}. Must be one of: idle, running, suspended, completed, cancelled, active\n`,
+        `Invalid status: ${part}. Must be one of: idle, running, suspended, end, cancelled, active\n`,
       );
       process.exit(1);
     }
@@ -232,11 +309,12 @@ function parsePaginationOptions(
 
 thread
   .command("list")
-  .description("List threads")
+  .description("List threads (defaults to active: idle + running + corrupt)")
   .option(
     "--status <status>",
-    "Filter by status: idle, running, completed, cancelled, active (idle+running), or comma-separated values",
+    "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")
@@ -244,6 +322,7 @@ thread
   .action(
     (opts: {
       status: string | undefined;
+      all: boolean | undefined;
       after: string | undefined;
       before: string | undefined;
       skip: string | undefined;
@@ -255,6 +334,7 @@ thread
         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 result = await cmdThreadList(
           storageRoot,
@@ -263,8 +343,9 @@ thread
           beforeMs,
           skip,
           take,
+          showAll,
         );
-        writeOutput(result);
+        await writeOutput(toThreadListPayload(result), "thread-list", storageRoot);
       });
     },
   );
@@ -286,7 +367,27 @@ thread
         supplement,
         agentOverride,
       );
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
+    });
+  });
+
+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: string, opts: { prompt: string; agent: string | undefined }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const agentOverride = opts.agent ?? null;
+      const result = await cmdThreadPoke(
+        storageRoot,
+        threadId as ThreadId,
+        opts.prompt,
+        agentOverride,
+      );
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -298,7 +399,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadStop(storageRoot, threadId);
-      writeOutput(result);
+      writeRawOutput(result, "thread stop");
     });
   });
 
@@ -310,7 +411,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadCancel(storageRoot, threadId);
-      writeOutput(result);
+      writeRawOutput(result, "thread cancel");
     });
   });
 
@@ -353,7 +454,7 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdStepList(storageRoot, threadId);
-      writeOutput(result);
+      await writeOutput(toStepListPayload(result), "step-list", storageRoot);
     });
   });
 
@@ -365,10 +466,40 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const detail = await cmdStepShow(storageRoot, stepHash as CasRef);
-      writeOutput(detail);
+      await writeOutput(
+        toStepDetailPayload(stepHash as CasRef, detail),
+        "step-detail",
+        storageRoot,
+      );
     });
   });
 
+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: string, opts: { prompt: string; agent: string | undefined; fork: boolean }) => {
+      const storageRoot = resolveStorageRoot();
+      runAction(async () => {
+        const stdout = await cmdStepAsk(storageRoot, stepHash as CasRef, {
+          prompt: opts.prompt,
+          agentOverride: opts.agent ?? null,
+          fork: opts.fork,
+        });
+        process.stdout.write(stdout.endsWith("\n") ? stdout : `${stdout}\n`);
+      });
+    },
+  );
+
 step
   .command("read")
   .description("Read a step's turns as human-readable markdown")
@@ -401,7 +532,7 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdStepFork(storageRoot, stepHash as CasRef);
-      writeOutput(result);
+      writeRawOutput(result);
     });
   });
 
@@ -542,46 +673,22 @@ prompt
 
 program
   .command("setup")
-  .description("Configure provider, model, and agent. Run without options for interactive wizard.")
-  .option("--provider <name>", "Provider name")
-  .option("--base-url <url>", "OpenAI-compatible API base URL")
-  .option("--api-key <key>", "API key")
-  .option("--model <name>", "Default model name")
+  .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: {
-      provider?: string;
-      baseUrl?: string;
-      apiKey?: string;
-      model?: string;
-      agent?: string;
-    }) => {
-      const storageRoot = resolveStorageRoot();
-      runAction(async () => {
-        // Resolve preset base-url when provider is known but --base-url is omitted
-        const resolvedBaseUrl =
-          opts.baseUrl ??
-          (opts.provider !== undefined ? resolvePresetBaseUrl(opts.provider) : null);
-        if (opts.provider && resolvedBaseUrl && opts.apiKey && opts.model) {
-          const result = await cmdSetup({
-            provider: opts.provider,
-            baseUrl: resolvedBaseUrl,
-            apiKey: opts.apiKey,
-            model: opts.model,
-            agent: opts.agent ?? undefined,
-            storageRoot,
-          });
-          writeOutput(result);
-        } else if (!opts.provider && !opts.baseUrl && !opts.apiKey && !opts.model) {
-          await cmdSetupInteractive(storageRoot);
-        } else {
-          throw new Error(
-            "Non-interactive setup requires: --provider, --api-key, --model (--base-url is optional for preset providers)",
-          );
-        }
-      });
-    },
-  );
+  .action((opts: { agent?: string }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      if (opts.agent !== undefined && opts.agent !== "") {
+        const result = await cmdSetup({ agent: opts.agent, storageRoot });
+        writeRawOutput(result);
+      } else {
+        await cmdSetupInteractive(storageRoot);
+      }
+    });
+  });
 
 const log = program.command("log").description("Process-level debug logs");
 
@@ -592,7 +699,7 @@ log
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdLogList(storageRoot);
-      writeOutput(result);
+      writeRawOutput(result, "log list");
     });
   });
 
@@ -615,7 +722,7 @@ log
           process: opts.process ?? null,
           date: opts.date ?? null,
         });
-        writeOutput(result);
+        writeRawOutput(result, "log show");
       });
     },
   );
@@ -628,7 +735,7 @@ log
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdLogClean(storageRoot, opts.before);
-      writeOutput(result);
+      writeRawOutput(result);
     });
   });
 
@@ -641,7 +748,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigList(storageRoot);
-      writeOutput(result);
+      writeRawOutput(result, "config list");
     });
   });
 
@@ -656,7 +763,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigGet(storageRoot, key);
-      writeOutput({ value: result });
+      writeRawOutput({ value: result }, "config get");
     });
   });
 
@@ -669,7 +776,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigSet(storageRoot, key, value);
-      writeOutput(result);
+      writeRawOutput(result, "config set");
     });
   });
 

package/src/commands/config.ts

@@ -3,20 +3,14 @@ import { join } from "node:path";
 import { parse, stringify } from "yaml";
 
 /**
- * Valid configuration key schema
+ * Valid configuration key schema. Engine config is LLM-free — providers,
+ * models, defaultModel, and modelOverrides are no longer accepted here.
+ * Each adapter owns its own LLM configuration.
  */
 const VALID_CONFIG_KEYS: Record<
   string,
   { nested: boolean; knownFields?: string[]; minDepth?: number }
 > = {
-  providers: {
-    nested: true,
-    knownFields: ["baseUrl", "apiKey"],
-  },
-  models: {
-    nested: true,
-    knownFields: ["provider", "name"],
-  },
   agents: {
     nested: true,
     knownFields: ["command", "args"],
@@ -26,14 +20,12 @@ const VALID_CONFIG_KEYS: Record<
     // agentOverrides.<workflowName>.<roleName> = agentAlias (string value)
     // No knownFields — workflow/role names are user-defined
   },
-  modelOverrides: {
+  defaultAgent: { nested: false },
+  concurrency: {
     nested: true,
+    knownFields: ["maxRunning"],
     minDepth: 2,
-    // modelOverrides.<scenario> = modelAlias (string value)
-    // No knownFields — scenarios are user-defined
   },
-  defaultAgent: { nested: false },
-  defaultModel: { nested: false },
 };
 
 /**
@@ -175,27 +167,12 @@ export function setNestedValue(obj: Record<string, unknown>, path: string[], val
 }
 
 /**
- * Deep clone and mask all apiKey values in providers section
+ * Deep clone the config. Engine config is LLM-free, so there are no apiKey
+ * fields to mask — this function is preserved as a defensive deep-clone
+ * boundary used by `cmdConfigList`.
  */
 export function maskApiKeys(config: Record<string, unknown>): Record<string, unknown> {
-  // Deep clone
-  const cloned = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
-
-  // Mask apiKey values in providers
-  if (cloned.providers && typeof cloned.providers === "object") {
-    const providers = cloned.providers as Record<string, unknown>;
-    for (const providerName of Object.keys(providers)) {
-      const provider = providers[providerName];
-      if (provider && typeof provider === "object") {
-        const providerObj = provider as Record<string, unknown>;
-        if ("apiKey" in providerObj) {
-          providerObj.apiKey = "***MASKED***";
-        }
-      }
-    }
-  }
-
-  return cloned;
+  return JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
 }
 
 /**
@@ -292,6 +269,12 @@ export async function cmdConfigSet(
   let parsedValue: unknown = value;
   if (lastSegment === "args") {
     parsedValue = parseArgsValue(value);
+  } else if (lastSegment === "maxRunning") {
+    const num = Number(value);
+    if (!Number.isInteger(num) || num < 1) {
+      throw new Error("Value for 'maxRunning' must be a positive integer");
+    }
+    parsedValue = num;
   }
 
   // Validate we're not setting a property on a non-object

package/src/commands/prompt.ts

@@ -148,44 +148,36 @@ pipx install 'hermes-agent[acp]'
 pip install -e '.[acp]'
 \`\`\`
 
-### Step 2 — Configure provider and model
+### Step 2 — Configure default agent
 
-uwf needs an LLM provider to run agents. **Ask the user** for their provider, API key, and model, then run:
+Run the interactive wizard:
 
 \`\`\`bash
-uwf setup --provider <name> --api-key <key> --model <model> --agent <adapter-command>
+uwf setup
 \`\`\`
 
-**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`), not the npm package name.
-
-**Preset providers** — when using a preset name, \`--base-url\` is auto-filled and can be omitted:
-
-| Provider | Name | Default base URL |
-|----------|------|-----------------|
-| OpenAI | \`openai\` | https://api.openai.com/v1 |
-| xAI | \`xai\` | https://api.x.ai/v1 |
-| OpenRouter | \`openrouter\` | https://openrouter.ai/api/v1 |
-| Venice | \`venice\` | https://api.venice.ai/api/v1 |
-| Dashscope | \`dashscope\` | https://dashscope.aliyuncs.com/compatible-mode/v1 |
-| DeepSeek | \`deepseek\` | https://api.deepseek.com/v1 |
-| SiliconFlow | \`siliconflow\` | https://api.siliconflow.cn/v1 |
-| VolcEngine | \`volcengine\` | https://ark.cn-beijing.volces.com/api/v3 |
-| Kimi (Moonshot) | \`kimi\` | https://api.moonshot.cn/v1 |
-| GLM (Zhipu AI) | \`glm\` | https://open.bigmodel.cn/api/paas/v4 |
-| StepFun | \`stepfun\` | https://api.stepfun.com/v1 |
-| MiniMax | \`minimax\` | https://api.minimax.io/v1 |
-| Ollama (local) | \`ollama\` | http://localhost:11434/v1 |
-
-For **non-preset providers**, you must specify \`--base-url\` manually.
-
-Example:
+Or configure non-interactively:
+
 \`\`\`bash
-uwf setup --provider openrouter --api-key sk-or-... --model anthropic/claude-sonnet-4 --agent uwf-hermes
+uwf setup --agent <adapter-command>
+\`\`\`
+
+**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`, \`uwf-claude-code\`), not the npm package name.
+
+Config is saved to \`~/.uwf/config.yaml\`:
+
+\`\`\`yaml
+agents:
+  hermes:
+    command: uwf-hermes
+    args: []
+defaultAgent: hermes
+agentOverrides: {}
 \`\`\`
 
-If the user doesn't know what to choose, suggest \`openrouter\` with \`anthropic/claude-sonnet-4\` as a sensible default.
+**LLM configuration** is per-adapter — each adapter manages its own provider, model, and API key settings independently (typically via environment variables like \`CLAUDE_MODEL\`, \`ANTHROPIC_API_KEY\`, etc.). The engine config (\`~/.uwf/config.yaml\`) is LLM-free.
 
-Config is saved to \`~/.uwf/config.yaml\`. Verify with \`cat ~/.uwf/config.yaml\`.
+Verify with \`cat ~/.uwf/config.yaml\`.
 
 ### Step 3 — Install skills
 
@@ -241,7 +233,17 @@ uwf thread exec <thread-id>
 uwf thread show <thread-id>
 \`\`\`
 
-If the thread reaches \`$END\` with status \`completed\`, the setup is working.
+If the thread reaches \`$END\` with status \`end\`, the setup is working.
+
+To verify suspend/resume and poke:
+
+\`\`\`bash
+# After a role yields with $status: "$SUSPEND", resume the suspended thread:
+uwf thread resume <thread-id> -p "Additional context for the agent"
+
+# Re-run the head step's agent with a supplementary prompt (replaces head step):
+uwf thread poke <thread-id> -p "Try again with this hint"
+\`\`\`
 
 ## Scenario B: Upgrade from Previous Version
 
@@ -297,7 +299,7 @@ Check the changelog for breaking changes. Known migrations:
     resume: { role: planner, prompt: "Review previous run and continue." }
   \`\`\`
 
-Update all \`.workflow/\` and \`.workflows/\` YAML files in your projects. \`uwf workflow add\` will reject files with the old \`_\` syntax.
+Update all \`.workflows/\` and \`.workflow/\` YAML files in your projects. \`uwf workflow add\` will reject files with the old \`_\` syntax.
 
 - **v0.2.1**: \`$status: { enum: [value] }\` → \`$status: { const: "value" }\`. The validator no longer accepts \`enum\` for \`$status\`. Update all workflow YAML files:
   \`\`\`yaml
@@ -310,6 +312,9 @@ Update all \`.workflow/\` and \`.workflows/\` YAML files in your projects. \`uwf
   # For multi-exit, use oneOf with const (unchanged)
   \`\`\`
 
+- **v0.4.0**: Thread status \`completed\` → \`end\`. Update scripts that filter \`--status completed\` to use \`--status end\`. Legacy on-disk \`status: completed\` is normalized to \`end\` on read.
+- **v0.4.0**: \`$SUSPEND\` is now an engine-level coroutine yield, not a graph target. Workflows that routed to \`role: "$SUSPEND"\` must emit \`$status: "$SUSPEND"\` with a \`reason\` from the role output instead. The thread becomes \`suspended\`; continue with \`uwf thread resume\`.
+
 ### Step 4 — Verify
 
 \`\`\`bash
@@ -326,5 +331,26 @@ uwf prompt workflow-authoring  # workflow YAML design guide
 uwf prompt adapter-developing  # building agent adapters
 uwf prompt bootstrap           # this guide
 \`\`\`
+
+## What's next — introduce uwf to the user
+
+After setup is complete, give the user a brief introduction to what uwf can do
+and invite them to try it. Cover these three things:
+
+1. **Run workflows** — execute pre-built workflows to automate multi-step tasks.
+   Setup auto-registers example workflows, ready to use immediately.
+2. **Create workflows** — design custom YAML workflows for their own recurring tasks
+   (code review, issue triage, release pipelines, etc.). Use \`uwf prompt workflow-authoring\`
+   for the authoring guide.
+3. **Debug & improve workflows** — iterate on workflow definitions, inspect thread state
+   with \`uwf thread show\`, replay failed steps with \`uwf thread poke\`, and refine
+   role procedures based on real execution results.
+
+**Discover & try built-in examples:**
+
+Run \`uwf workflow list\` to see which workflows are registered (setup auto-registers
+several built-in examples). Show the user what's available, then invite them to try
+one — for instance, suggest a fun debate topic like "AI 是否会抢了人类的工作？" and
+offer to kick it off for them.
 `;
 }