chore: release cli@0.3.0 util@0.1.3 agent-hermes@0.1.3 agent-claude-code@0.1.2 agent-builtin@0.1.2 agent-mock@0.1.2

Merge pull request 'fix: bootstrap — session restart hint + v0.2.1 migration note' (#125 ) from fix/123-session-restart-hint into main
fix: bootstrap — remind to restart session after skill install/update
2026-06-06 00:13:48 +00:00 · 2026-06-05 23:54:24 +00:00 · 2026-06-05 23:48:53 +00:00 · 2026-06-05 23:33:57 +00:00 · 2026-06-05 23:31:56 +00:00 · 2026-06-05 23:13:54 +00:00
74 changed files with 1081 additions and 596 deletions
@@ -0,0 +1,9 @@
+---
+"@united-workforce/cli": patch
+---
+
+fix: expand bootstrap prompt with full onboarding and upgrade guide
+
+Bootstrap now covers two scenarios:
+- Fresh install: CLI + adapter installation, `uwf setup` configuration, skill installation, end-to-end verification
+- Upgrade: package update, skill regeneration, breaking change migrations (e.g. $START new/resume)
@@ -0,0 +1,8 @@
+---
+"@united-workforce/cli": patch
+---
+
+fix: bootstrap adds Step 0 environment pre-flight check
+
+- Pre-flight checks for node, pnpm/npm, global bin PATH, hermes CLI with FIX instructions (#112)
+- Install commands changed from npm to pnpm (with npm fallback)
@@ -0,0 +1,9 @@
+---
+"@united-workforce/cli": patch
+"@united-workforce/util": patch
+---
+
+fix: workflow-authoring flat schema example uses enum, bootstrap adds PATH guidance
+
+- workflow-authoring: flat schema example uses `enum: [done]` instead of bare `const` (#110.3)
+- bootstrap: adds `which hermes` check and PATH guidance for venv installs (#110.4)
@@ -0,0 +1,14 @@
+---
+"@united-workforce/cli": patch
+---
+
+fix: improve bootstrap docs — agent discovery, pnpm/npm parity, preset provider table (#118, #120)
+
+- Step 1: detect installed agents (hermes/claude) before choosing adapter
+- Step 1: clarify adapter versions are independent from CLI — install @latest
+- Step 1: show pnpm and npm side-by-side
+- Step 1: add "adapter must be installed before `uwf setup --agent`" note
+- Step 1: add ACP verification step (hermes acp --help)
+- Step 2: `--agent` takes adapter command name (e.g. `uwf-hermes`), not npm package
+- Step 2: preset providers listed as a table with names and default base URLs
+- Remove uwf-builtin from supported adapters (not ready yet)
@@ -0,0 +1,10 @@
+---
+"@united-workforce/cli": patch
+---
+
+fix: preset provider base-url auto-fill, bootstrap ACP docs, friendlier name mismatch error
+
+- `uwf setup --provider dashscope` now auto-fills `--base-url` from preset list (#106)
+- Bootstrap guide documents uwf-hermes ACP dependency (`pip install hermes-agent[acp]`) (#107)
+- Bootstrap verify step uses inline workflow instead of missing `examples/eval-simple.yaml` (#107)
+- Workflow filename mismatch error now suggests how to fix it (#108)
@@ -0,0 +1,14 @@
+---
+"@united-workforce/cli": patch
+"@united-workforce/agent-hermes": patch
+"@united-workforce/agent-claude-code": patch
+"@united-workforce/agent-builtin": patch
+"@united-workforce/agent-mock": patch
+---
+
+fix: suppress ExperimentalWarning, PEP 668 pip guidance, setup help (#116)
+
+- All CLI bins use shebang `#!/usr/bin/env -S node --disable-warning=ExperimentalWarning`
+- Remove NODE_OPTIONS injection from spawn (shebang handles it)
+- Bootstrap pip install guidance covers venv/pipx/source options for PEP 668 systems
+- `uwf setup --help` mentions interactive wizard mode
@@ -0,0 +1,12 @@
+---
+"@united-workforce/cli": patch
+---
+
+fix: setup UX improvements (#114)
+
+- Setup validates adapter availability and prints install command if missing
+- Setup prints "Config saved to <path> ✓" on success
+- Spawn ENOENT gives actionable error ("not found in PATH" + which command)
+- SQLite ExperimentalWarning suppressed via NODE_OPTIONS in spawned processes
+- Bootstrap VERSION reads cli package version (was reading util version)
+- Bootstrap PATH guidance is shell-agnostic (no hardcoded .bashrc/.profile)
@@ -0,0 +1,9 @@
+---
+"@united-workforce/cli": minor
+"@united-workforce/util": patch
+---
+
+feat: replace $START `_` status with `new`/`resume` semantics
+
+BREAKING: All workflow YAML files must update `$START._` to `$START.new` + `$START.resume`.
+The `resume` edge prompt replaces the previously hardcoded resume message in the CLI.
@@ -0,0 +1,15 @@
+---
+"@united-workforce/cli": patch
+"@united-workforce/util": patch
+---
+
+fix: unify $status to const-only, drop enum support (#123)
+
+Breaking: `$status` in frontmatter now requires `const` everywhere.
+`enum` is no longer accepted and will be rejected by the validator.
+
+- Validator: `hasStatusConst()` / `getConstStatuses()` replace enum-based checks
+- Error message: "must define $status as const (or oneOf with const)"
+- workflow-authoring docs: all examples use `const`, enum explicitly noted as unsupported
+- bootstrap hello.yaml: `$status: { const: done }`
+- All test fixtures migrated from enum to const/oneOf
@@ -264,7 +264,8 @@ roles:

 graph:
  $START:
-    _: { role: "bootstrap", prompt: "Set up the Docker container and verify uwf is runnable." }
+    new: { role: "bootstrap", prompt: "Set up the Docker container and verify uwf is runnable." }
+    resume: { role: "bootstrap", prompt: "Review the previous run output and continue the walkthrough." }
  bootstrap:
    pass: { role: "config-and-registry", prompt: "Container {{{containerName}}} is ready. Validate config and workflow registration." }
    fail: { role: "$END", prompt: "Bootstrap failed: {{{error}}}. No container was created." }
@@ -227,7 +227,8 @@ roles:
          required: [$status, error]
 graph:
  $START:
-    _: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
+    new: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
+    resume: { role: "planner", prompt: "Review the previous run output and continue the work." }
  planner:
    insufficient_info: { role: "$SUSPEND", prompt: "信息不足，需要补充：{{{reason}}}" }
    ready: { role: "developer", prompt: "Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}. Repo remote: {{{repoRemote}}}." }
@@ -200,7 +200,7 @@ payload:

 - `roles` — 内联定义，每个 role 的 `meta` 是独立的 ocas_ref（指向 ocas 内置 JSON Schema 节点）
 - `graph` — `Record<Role | "$START", Record<Status, Target>>`，每个 Target = `{ role, prompt }`
- Status 来自上一个 role 输出的 `status` 字段，`$START` 用 `_` 作为初始 status
+- Status 来自上一个 role 输出的 `$status` 字段，`$START` 使用 `new`（首次启动）和 `resume`（恢复已完成的 thread）作为 status
 - Prompt 模板使用 Mustache 渲染，变量来自 lastOutput
 - 不含 agent binding — agent 配置在 `~/.uwf/config.yaml` 中管理

@@ -208,7 +208,7 @@ Moderator 的求值逻辑：

 ```typescript
 evaluate(graph, lastRole, lastOutput) → { role, prompt }
-// 1. status = lastRole === "$START" ? "_" : lastOutput.status
+// 1. status = lastOutput.$status (e.g. "new" for $START first run, "resume" for completed thread resume)
 // 2. target = graph[lastRole][status]
 // 3. prompt = mustache.render(target.prompt, lastOutput)
 ```
@@ -422,8 +422,8 @@ type StepNodePayload = StepRecord & {
 Moderator 使用 `evaluate(graph, lastRole, lastOutput)` 进行同步 status-based routing：

 ```typescript
-// graph[lastRole][lastOutput.status] → Target { role, prompt }
-// $START 角色使用 "_" 作为初始 status
+// graph[lastRole][lastOutput.$status] → Target { role, prompt }
+// $START 使用 "new"（首次启动）和 "resume"（恢复已完成 thread）作为 status
 // prompt 通过 Mustache 模板渲染，变量来自 lastOutput
 ```

@@ -35,6 +35,7 @@ roles:
      required: [$status, thesis, keyPoints]
 graph:
  $START:
-    _: { role: "analyst", prompt: "Analyze the topic in the task and produce a structured summary with key points." }
+    new: { role: "analyst", prompt: "Analyze the topic in the task and produce a structured summary with key points." }
+    resume: { role: "analyst", prompt: "Review the previous analysis output and continue with additional context." }
  analyst:
    done: { role: "$END", prompt: "Analysis complete. Finish the workflow." }
@@ -53,7 +53,8 @@ roles:
      required: [$status, argument]
 graph:
  $START:
-    _: { role: "against", prompt: "Present your opening argument against the proposition." }
+    new: { role: "against", prompt: "Present your opening argument against the proposition." }
+    resume: { role: "against", prompt: "Review the previous debate output and continue the argument against the proposition." }
  against:
    conceded: { role: "$END", prompt: "The against side conceded. Debate over." }
    continue: { role: "for", prompt: "Counter the opposing argument: {{{argument}}}" }
@@ -25,6 +25,7 @@ roles:
      required: [$status, summary]
 graph:
  $START:
-    _: { role: "fixer", prompt: "Fix the code issue described in the task prompt." }
+    new: { role: "fixer", prompt: "Fix the code issue described in the task prompt." }
+    resume: { role: "fixer", prompt: "Review the previous run output and continue fixing the code issue." }
  fixer:
    done: { role: "$END", prompt: "Fix complete." }
@@ -215,7 +215,8 @@ roles:
          required: [$status, error]
 graph:
  $START:
-    _: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
+    new: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
+    resume: { role: "planner", prompt: "Review the previous run output and continue the work." }
  planner:
    insufficient_info: { role: "$SUSPEND", prompt: "信息不足，需要补充：{{{reason}}}" }
    ready: { role: "developer", prompt: "Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}." }
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-builtin",
-  "version": "0.1.0",
+  "version": "0.1.2",
  "files": [
    "src",
    "dist",
@@ -1,4 +1,11 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+
+// eslint-disable-next-line -- dynamic import for version
+const pkg = await import("../package.json", { with: { type: "json" } });
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+  process.stdout.write(`${pkg.default.version}\n`);
+  process.exit(0);
+}

 import { createBuiltinAgent } from "./agent.js";

@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-claude-code",
-  "version": "0.1.0",
+  "version": "0.1.2",
  "files": [
    "src",
    "dist",
@@ -1,4 +1,11 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+
+// eslint-disable-next-line -- dynamic import for version
+const pkg = await import("../package.json", { with: { type: "json" } });
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+  process.stdout.write(`${pkg.default.version}\n`);
+  process.exit(0);
+}

 import { createClaudeCodeAgent } from "./claude-code.js";

@@ -0,0 +1,18 @@
+# @united-workforce/agent-hermes
+
+## 0.1.1
+
+### Patch Changes
+
+- 8085d1d: fix: read token usage from ACP PromptResponse instead of DB
+
+  Token counts (inputTokens, outputTokens) now come from the ACP
+  `PromptResponse.usage` field, which is populated synchronously from
+  `run_conversation()` return data — no WAL race condition.
+
+  Turns (assistant message count) still come from the DB via
+  `snapshotTurns()` before/after delta.
+
+  Previously both tokens and turns were read from the Hermes state DB
+  after the ACP prompt returned, but due to WAL write lag the DB often
+  had incomplete token data at read time (e.g. 235 vs actual 26,080).
@@ -15,7 +15,8 @@ describe("Issue #551 — bin entry & engines", () => {
    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
    const binPath = pkg.bin["uwf-hermes"];
    const content = readFileSync(join(PKG_ROOT, binPath), "utf-8");
-    expect(content.startsWith("#!/usr/bin/env node")).toBe(true);
+    expect(content.startsWith("#!/usr/bin/env")).toBe(true);
+    expect(content).toContain("node");
  });

  test("README.md explains uwf-hermes is an adapter", () => {
@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
-import { computeUsageDelta, snapshotUsage } from "../src/hermes.js";
+import type { AcpUsage } from "../src/acp-client.js";
+import { buildUsage, snapshotTurns } from "../src/hermes.js";
 import type { HermesSessionJson } from "../src/types.js";

 function makeSession(overrides: Partial<HermesSessionJson> = {}): HermesSessionJson {
@@ -14,19 +15,19 @@ function makeSession(overrides: Partial<HermesSessionJson> = {}): HermesSessionJ
  };
 }

-describe("snapshotUsage", () => {
-  test("returns zero snapshot for null session", () => {
-    const result = snapshotUsage(null);
-    expect(result).toEqual({ turns: 0, inputTokens: 0, outputTokens: 0 });
+describe("snapshotTurns", () => {
+  test("returns zero for null session", () => {
+    const result = snapshotTurns(null);
+    expect(result).toEqual({ turns: 0 });
  });

-  test("returns zero snapshot for empty session", () => {
-    const result = snapshotUsage(makeSession());
-    expect(result).toEqual({ turns: 0, inputTokens: 0, outputTokens: 0 });
+  test("returns zero for empty session", () => {
+    const result = snapshotTurns(makeSession());
+    expect(result).toEqual({ turns: 0 });
  });

  test("counts assistant messages as turns", () => {
-    const result = snapshotUsage(
+    const result = snapshotTurns(
      makeSession({
        messages: [
          { role: "user", content: "hello", reasoning: null, tool_calls: null },
@@ -39,11 +40,11 @@ describe("snapshotUsage", () => {
        outputTokens: 500,
      }),
    );
-    expect(result).toEqual({ turns: 2, inputTokens: 1000, outputTokens: 500 });
+    expect(result).toEqual({ turns: 2 });
  });

  test("ignores non-assistant messages for turn count", () => {
-    const result = snapshotUsage(
+    const result = snapshotTurns(
      makeSession({
        messages: [
          { role: "user", content: "hello", reasoning: null, tool_calls: null },
@@ -55,11 +56,13 @@ describe("snapshotUsage", () => {
  });
 });

-describe("computeUsageDelta", () => {
-  test("first visit: before is zero, after has all values", () => {
-    const before = { turns: 0, inputTokens: 0, outputTokens: 0 };
-    const after = { turns: 3, inputTokens: 5000, outputTokens: 2000 };
-    const result = computeUsageDelta(before, after, 12.5);
+describe("buildUsage", () => {
+  const acpUsage: AcpUsage = { inputTokens: 5000, outputTokens: 2000, totalTokens: 7000 };
+
+  test("first visit: tokens from ACP, turns from DB delta", () => {
+    const beforeTurns = { turns: 0 };
+    const afterTurns = { turns: 3 };
+    const result = buildUsage(acpUsage, beforeTurns, afterTurns, 12.5);
    expect(result).toEqual({
      turns: 3,
      inputTokens: 5000,
@@ -68,43 +71,52 @@ describe("computeUsageDelta", () => {
    });
  });

-  test("re-entry: computes delta correctly", () => {
-    const before = { turns: 2, inputTokens: 3000, outputTokens: 1000 };
-    const after = { turns: 4, inputTokens: 8000, outputTokens: 3500 };
-    const result = computeUsageDelta(before, after, 7.3);
+  test("re-entry: turn delta computed correctly, tokens from ACP", () => {
+    const beforeTurns = { turns: 2 };
+    const afterTurns = { turns: 4 };
+    const acpDelta: AcpUsage = { inputTokens: 8000, outputTokens: 3500, totalTokens: 11500 };
+    const result = buildUsage(acpDelta, beforeTurns, afterTurns, 7.3);
    expect(result).toEqual({
      turns: 2,
-      inputTokens: 5000,
-      outputTokens: 2500,
+      inputTokens: 8000,
+      outputTokens: 3500,
      duration: 7,
    });
  });

-  test("floors negative deltas at 0 (defensive)", () => {
-    const before = { turns: 5, inputTokens: 10000, outputTokens: 5000 };
-    const after = { turns: 3, inputTokens: 8000, outputTokens: 4000 };
-    const result = computeUsageDelta(before, after, 1.0);
+  test("floors negative turn deltas at 0, then defaults to 1", () => {
+    const beforeTurns = { turns: 5 };
+    const afterTurns = { turns: 3 };
+    const result = buildUsage(acpUsage, beforeTurns, afterTurns, 1.0);
    // turns would be negative (-2), floored to 0, then || 1 gives 1
    expect(result.turns).toBe(1);
-    expect(result.inputTokens).toBe(0);
-    expect(result.outputTokens).toBe(0);
  });

  test("zero turns delta defaults to 1 (at least one turn happened)", () => {
-    const before = { turns: 3, inputTokens: 1000, outputTokens: 500 };
-    const after = { turns: 3, inputTokens: 2000, outputTokens: 1000 };
-    const result = computeUsageDelta(before, after, 5.0);
+    const beforeTurns = { turns: 3 };
+    const afterTurns = { turns: 3 };
+    const result = buildUsage(acpUsage, beforeTurns, afterTurns, 5.0);
    // turns delta is 0, || 1 gives 1
    expect(result.turns).toBe(1);
-    expect(result.inputTokens).toBe(1000);
-    expect(result.outputTokens).toBe(500);
+  });
+
+  test("null ACP usage yields zero tokens", () => {
+    const beforeTurns = { turns: 0 };
+    const afterTurns = { turns: 2 };
+    const result = buildUsage(null, beforeTurns, afterTurns, 10.0);
+    expect(result).toEqual({
+      turns: 2,
+      inputTokens: 0,
+      outputTokens: 0,
+      duration: 10,
+    });
  });

  test("duration is rounded", () => {
-    const before = { turns: 0, inputTokens: 0, outputTokens: 0 };
-    const after = { turns: 1, inputTokens: 100, outputTokens: 50 };
-    expect(computeUsageDelta(before, after, 3.7).duration).toBe(4);
-    expect(computeUsageDelta(before, after, 3.2).duration).toBe(3);
-    expect(computeUsageDelta(before, after, 0.0).duration).toBe(0);
+    const beforeTurns = { turns: 0 };
+    const afterTurns = { turns: 1 };
+    expect(buildUsage(acpUsage, beforeTurns, afterTurns, 3.7).duration).toBe(4);
+    expect(buildUsage(acpUsage, beforeTurns, afterTurns, 3.2).duration).toBe(3);
+    expect(buildUsage(acpUsage, beforeTurns, afterTurns, 0.0).duration).toBe(0);
  });
 });
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-hermes",
-  "version": "0.1.0",
+  "version": "0.1.3",
  "files": [
    "src",
    "dist",
@@ -1,6 +1,16 @@
 import type { ChildProcess } from "node:child_process";
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OWN_VERSION = (
+  JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")) as {
+    version: string;
+  }
+).version;

 const HERMES_COMMAND = "hermes";
 const PROTOCOL_VERSION = 1;
@@ -17,9 +27,17 @@ type PendingRequest = {
  reject: (reason: Error) => void;
 };

+/** Token usage returned by ACP PromptResponse. */
+export type AcpUsage = {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+};
+
 export type AcpPromptResult = {
  text: string;
  sessionId: string;
+  usage: AcpUsage | null;
 };

 export class HermesAcpClient {
@@ -96,9 +114,25 @@ export class HermesAcpClient {
      );
    }

+    // Extract token usage from ACP PromptResponse.result.usage (camelCase wire format)
+    const result = (response as { result?: Record<string, unknown> }).result;
+    const rawUsage = result?.usage as Record<string, unknown> | undefined;
+    const usage: AcpUsage | null =
+      rawUsage !== undefined &&
+      typeof rawUsage.inputTokens === "number" &&
+      typeof rawUsage.outputTokens === "number" &&
+      typeof rawUsage.totalTokens === "number"
+        ? {
+            inputTokens: rawUsage.inputTokens,
+            outputTokens: rawUsage.outputTokens,
+            totalTokens: rawUsage.totalTokens,
+          }
+        : null;
+
    return {
      text: this.messageChunks.join(""),
      sessionId: this.sessionId,
+      usage,
    };
  }

@@ -275,7 +309,7 @@ export class HermesAcpClient {
  private async initialize(): Promise<void> {
    const initResponse = await this.sendRequest("initialize", {
      protocolVersion: PROTOCOL_VERSION,
-      clientInfo: { name: "uwf", version: "0.1.0" },
+      clientInfo: { name: "uwf-hermes", version: OWN_VERSION },
      capabilities: {},
    });

@@ -1,4 +1,11 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+
+// eslint-disable-next-line -- dynamic import for version
+const pkg = await import("../package.json", { with: { type: "json" } });
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+  process.stdout.write(`${pkg.default.version}\n`);
+  process.exit(0);
+}

 import { createHermesAgent } from "./hermes.js";
 import { isResumeDisabled } from "./session-cache.js";
@@ -8,7 +8,7 @@ import {
  buildRolePrompt,
  createAgent,
 } from "@united-workforce/util-agent";
-
+import type { AcpUsage } from "./acp-client.js";
 import { HermesAcpClient } from "./acp-client.js";
 import { getCachedSessionId, setCachedSessionId } from "./session-cache.js";
 import { loadHermesSession, storeHermesSessionDetail } from "./session-detail.js";
@@ -17,36 +17,37 @@ import type { HermesSessionJson } from "./types.js";
 const log = createLogger({ sink: { kind: "stderr" } });

 /** Snapshot of session metrics taken before and after a prompt call. */
-type UsageSnapshot = {
+type TurnsSnapshot = {
  turns: number;
-  inputTokens: number;
-  outputTokens: number;
 };

-const ZERO_SNAPSHOT: UsageSnapshot = { turns: 0, inputTokens: 0, outputTokens: 0 };
+const ZERO_TURNS: TurnsSnapshot = { turns: 0 };

-/** Extract usage metrics from a session. Returns zeros for null sessions. */
-export function snapshotUsage(session: HermesSessionJson | null): UsageSnapshot {
+/** Extract assistant turn count from a session. Returns zero for null sessions. */
+export function snapshotTurns(session: HermesSessionJson | null): TurnsSnapshot {
  if (session === null) {
-    return ZERO_SNAPSHOT;
+    return ZERO_TURNS;
  }
  return {
    turns: session.messages.filter((m) => m.role === "assistant").length,
-    inputTokens: session.inputTokens,
-    outputTokens: session.outputTokens,
  };
 }

-/** Compute the delta between two snapshots (after minus before). Floors at 0. */
-export function computeUsageDelta(
-  before: UsageSnapshot,
-  after: UsageSnapshot,
+/**
+ * Build Usage from ACP token data + DB turn delta.
+ * Tokens come from ACP PromptResponse (synchronous, accurate).
+ * Turns come from DB before/after snapshots (may have WAL lag, but acceptable).
+ */
+export function buildUsage(
+  acpUsage: AcpUsage | null,
+  beforeTurns: TurnsSnapshot,
+  afterTurns: TurnsSnapshot,
  durationSec: number,
 ): Usage {
  return {
-    turns: Math.max(0, after.turns - before.turns) || 1,
-    inputTokens: Math.max(0, after.inputTokens - before.inputTokens),
-    outputTokens: Math.max(0, after.outputTokens - before.outputTokens),
+    turns: Math.max(0, afterTurns.turns - beforeTurns.turns) || 1,
+    inputTokens: acpUsage?.inputTokens ?? 0,
+    outputTokens: acpUsage?.outputTokens ?? 0,
    duration: Math.round(durationSec),
  };
 }
@@ -148,12 +149,12 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
  async function runPrompt(
    ctx: AgentContext,
    useContinuation: boolean,
-    beforeSnapshot: UsageSnapshot,
+    beforeTurns: TurnsSnapshot,
  ): Promise<AgentRunResult> {
    const effectiveCtx = useContinuation ? ctx : { ...ctx, isFirstVisit: true };
    const fullPrompt = buildHermesPrompt(effectiveCtx);
    const startMs = Date.now();
-    const { text, sessionId } = await client.prompt(fullPrompt);
+    const { text, sessionId, usage: acpUsage } = await client.prompt(fullPrompt);
    const durationSec = (Date.now() - startMs) / 1000;
    const { detailHash } = await storePromptResult(ctx.store, sessionId);

@@ -161,9 +162,10 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
      await setCachedSessionId(ctx.threadId, ctx.role, sessionId, ctx.storageRoot);
    }

+    // Turns from DB (may lag slightly due to WAL, but acceptable)
    const afterSession = await loadHermesSession(sessionId);
-    const afterSnapshot = snapshotUsage(afterSession);
-    const usage = computeUsageDelta(beforeSnapshot, afterSnapshot, durationSec);
+    const afterTurns = snapshotTurns(afterSession);
+    const usage = buildUsage(acpUsage, beforeTurns, afterTurns, durationSec);

    return { output: text, detailHash, sessionId, assembledPrompt: fullPrompt, usage };
  }
@@ -173,16 +175,16 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
    const attempt = await prepareSession(client, ctx, cwd, resumeDisabled);

    // Snapshot before prompt: for resumed sessions, captures cumulative state
-    // so we can compute the delta. For new sessions, this is ZERO_SNAPSHOT.
+    // so we can compute the turn delta. For new sessions, this is ZERO_TURNS.
    const currentSessionId = client.getSessionId();
    const beforeSession =
      attempt.resumed && currentSessionId !== null
        ? await loadHermesSession(currentSessionId)
        : null;
-    const beforeSnapshot = snapshotUsage(beforeSession);
+    const beforeTurns = snapshotTurns(beforeSession);

    try {
-      return await runPrompt(ctx, attempt.useContinuation, beforeSnapshot);
+      return await runPrompt(ctx, attempt.useContinuation, beforeTurns);
    } catch (error) {
      if (!attempt.resumed) {
        throw error;
@@ -193,7 +195,7 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
      await client.close();
      await client.connect(cwd);
      // Fresh session after retry — reset snapshot to zero
-      return runPrompt(ctx, false, ZERO_SNAPSHOT);
+      return runPrompt(ctx, false, ZERO_TURNS);
    }
  }

@@ -204,20 +206,20 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
  ): Promise<AgentRunResult> {
    // Client is already connected from runHermes — same ACP session,
    // so the agent sees the full conversation history (crucial for retries).
-    // Snapshot before the continuation prompt for delta computation.
+    // Snapshot turns before the continuation prompt for delta computation.
    const currentSessionId = client.getSessionId();
    const beforeSession =
      currentSessionId !== null ? await loadHermesSession(currentSessionId) : null;
-    const beforeSnapshot = snapshotUsage(beforeSession);
+    const beforeTurns = snapshotTurns(beforeSession);

    const startMs = Date.now();
-    const { text, sessionId } = await client.prompt(message);
+    const { text, sessionId, usage: acpUsage } = await client.prompt(message);
    const durationSec = (Date.now() - startMs) / 1000;
    const { detailHash } = await storePromptResult(store, sessionId);

    const afterSession = await loadHermesSession(sessionId);
-    const afterSnapshot = snapshotUsage(afterSession);
-    const usage = computeUsageDelta(beforeSnapshot, afterSnapshot, durationSec);
+    const afterTurns = snapshotTurns(afterSession);
+    const usage = buildUsage(acpUsage, beforeTurns, afterTurns, durationSec);

    return { output: text, detailHash, sessionId, assembledPrompt: "", usage };
  }
@@ -1,7 +1,8 @@
+export type { AcpUsage } from "./acp-client.js";
 export { HermesAcpClient } from "./acp-client.js";
 export {
  buildHermesPrompt,
-  computeUsageDelta,
+  buildUsage,
  createHermesAgent,
-  snapshotUsage,
+  snapshotTurns,
 } from "./hermes.js";
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-mock",
-  "version": "0.1.0",
+  "version": "0.1.2",
  "files": [
    "src",
    "dist",
@@ -1,4 +1,11 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+
+// eslint-disable-next-line -- dynamic import for version
+const pkg = await import("../package.json", { with: { type: "json" } });
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+  process.stdout.write(`${pkg.default.version}\n`);
+  process.exit(0);
+}

 import { createMockAgent } from "./mock-agent.js";

@@ -0,0 +1,9 @@
+# @united-workforce/cli
+
+## 0.1.1
+
+### Patch Changes
+
+- 850a3b2: fix: resolve --agent override via config alias before raw command
+
+  `resolveAgentConfig()` now checks `config.agents[alias]` first before falling back to `parseAgentOverride()`. Eval CLI default `--agent` changed from `"hermes"` to `"uwf-hermes"`.
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
  "files": [
    "src",
    "dist",
@@ -58,7 +58,10 @@ describe("C1: adapter JSON round-trip integration", () => {
        },
      },
      graph: {
-        $START: { _: { role: "worker", prompt: "Do the work", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Do the work", location: null },
+          resume: { role: "worker", prompt: "Resume the work", location: null },
+        },
        worker: { done: { role: "$END", prompt: "completed", location: null } },
      },
    });
@@ -28,9 +28,13 @@ roles:
      $status: "ready"
    frontmatter:
      type: object
-      required: ["$status"]
-      properties:
-        $status: { type: string, enum: ["ready", "not-ready"] }
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+          required: ["$status"]
+        - properties:
+            $status: { const: "not-ready" }
+          required: ["$status"]
  roleB:
    description: Second role
    goal: Do B
@@ -42,13 +46,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
 graph:
  $START:
-    _:
+    new:
      role: roleA
      prompt: "Do A"
      location: null
+    resume:
+      role: roleA
+      prompt: "Resume A"
+      location: null
  roleA:
    ready:
      role: roleB
@@ -78,9 +86,13 @@ roles:
      $status: "pass"
    frontmatter:
      type: object
-      required: ["$status"]
-      properties:
-        $status: { type: string, enum: ["pass", "fail"] }
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+          required: ["$status"]
+        - properties:
+            $status: { const: "fail" }
+          required: ["$status"]
  roleB:
    description: Pass role
    goal: Do B
@@ -92,7 +104,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
  roleC:
    description: Fail role
    goal: Do C
@@ -104,13 +116,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
 graph:
  $START:
-    _:
+    new:
      role: roleA
      prompt: "Do A"
      location: null
+    resume:
+      role: roleA
+      prompt: "Resume A"
+      location: null
  roleA:
    pass:
      role: roleB
@@ -147,13 +163,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
 graph:
  $START:
-    _:
+    new:
      role: worker
      prompt: "Work"
      location: null
+    resume:
+      role: worker
+      prompt: "Resume work"
+      location: null
  worker:
    done:
      role: $END
@@ -36,7 +36,8 @@ roles:
          required: [$status]
 graph:
  $START:
-    _: { role: analyst, prompt: 'Analyze the task' }
+    new: { role: analyst, prompt: 'Analyze the task' }
+    resume: { role: analyst, prompt: 'Review the previous run output and continue the work.' }
  analyst:
    analyzed: { role: developer, prompt: 'Implement the change' }
  developer:
@@ -25,7 +25,8 @@ roles:
          required: [$status]
 graph:
  $START:
-    _: { role: planner, prompt: 'Plan the task' }
+    new: { role: planner, prompt: 'Plan the task' }
+    resume: { role: planner, prompt: 'Review the previous run output and continue the work.' }
  planner:
    ready: { role: worker, prompt: 'Do the work' }
  worker:
@@ -28,7 +28,8 @@ roles:
          required: [$status]
 graph:
  $START:
-    _: { role: developer, prompt: 'Implement the change' }
+    new: { role: developer, prompt: 'Implement the change' }
+    resume: { role: developer, prompt: 'Review the previous run output and continue the work.' }
  developer:
    review_needed: { role: reviewer, prompt: 'Review the change' }
  reviewer:
@@ -27,7 +27,8 @@ roles:
          required: [$status]
 graph:
  $START:
-    _: { role: planner, prompt: 'Plan the task' }
+    new: { role: planner, prompt: 'Plan the task' }
+    resume: { role: planner, prompt: 'Review the previous run output and continue the work.' }
  planner:
    ready: { role: worker, prompt: 'Work on branch {{{branch}}} in {{{repoPath}}}' }
  worker:
@@ -18,7 +18,8 @@ roles:
          required: [$status]
 graph:
  $START:
-    _: { role: planner, prompt: 'Analyze the task' }
+    new: { role: planner, prompt: 'Analyze the task' }
+    resume: { role: planner, prompt: 'Review the previous run output and continue the work.' }
  planner:
    insufficient_info: { role: '$SUSPEND', prompt: 'Need more info: {{{reason}}}' }
    ready: { role: '$END', prompt: 'Done' }
@@ -5,7 +5,12 @@ import { evaluate } from "../moderator/evaluate.js";

 const solveIssueGraph: WorkflowPayload["graph"] = {
  $START: {
-    _: { role: "planner", prompt: "Start planning from the issue in the task.", location: null },
+    new: { role: "planner", prompt: "Start planning from the issue in the task.", location: null },
+    resume: {
+      role: "planner",
+      prompt: "Review the previous run output and continue the work.",
+      location: null,
+    },
  },
  planner: {
    planned: { role: "developer", prompt: "Implement the plan: {{plan}}", location: null },
@@ -20,8 +25,8 @@ const solveIssueGraph: WorkflowPayload["graph"] = {
 };

 describe("evaluate", () => {
-  test("$START → first role (unit status _)", () => {
-    const result = evaluate(solveIssueGraph, "$START", { $status: "_" });
+  test("$START → first role (status new)", () => {
+    const result = evaluate(solveIssueGraph, "$START", { $status: "new" });
    expect(result).toEqual({
      ok: true,
      value: {
@@ -32,6 +37,18 @@ describe("evaluate", () => {
    });
  });

+  test("$START → first role (status resume)", () => {
+    const result = evaluate(solveIssueGraph, "$START", { $status: "resume" });
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        role: "planner",
+        prompt: "Review the previous run output and continue the work.",
+        location: null,
+      },
+    });
+  });
+
  test("status-based routing (reviewer rejected → developer)", () => {
    const result = evaluate(solveIssueGraph, "reviewer", {
      $status: "rejected",
@@ -95,7 +112,7 @@ describe("evaluate", () => {
  });

  test("missing role in graph → error", () => {
-    const result = evaluate(solveIssueGraph, "unknown-role", { $status: "_" });
+    const result = evaluate(solveIssueGraph, "unknown-role", { $status: "new" });
    expect(result.ok).toBe(false);
    if (!result.ok) {
      expect(result.error.message).toBe('no transitions defined for role "unknown-role"');
@@ -9,31 +9,25 @@ import {
  cmdPromptAdapterDeveloping,
  cmdPromptBootstrap,
  cmdPromptList,
-  cmdPromptSetup,
  cmdPromptUsage,
-  cmdPromptUsageReference,
  cmdPromptWorkflowAuthoring,
 } from "../commands/prompt.js";

 describe("prompt commands", () => {
-  test("prompt list returns new prompt names", () => {
+  test("prompt list returns prompt names (no bootstrap)", () => {
    const result = cmdPromptList();
    expect(result).toBeInstanceOf(Array);
    expect(result).toContain("usage");
    expect(result).toContain("workflow-authoring");
    expect(result).toContain("adapter-developing");
-    expect(result).toContain("bootstrap");
-    expect(result).not.toContain("user");
-    expect(result).not.toContain("author");
-    expect(result).not.toContain("developer");
-    expect(result).not.toContain("adapter");
+    expect(result).not.toContain("bootstrap");
    for (const name of result) {
      expect(name).toMatch(/^\S+$/);
    }
  });

-  test("prompt usage-reference returns non-empty markdown string with frontmatter", () => {
-    const result = cmdPromptUsageReference();
+  test("prompt usage returns only the usage reference with frontmatter", () => {
+    const result = cmdPromptUsage();
    expect(typeof result).toBe("string");
    expect(result).toContain("uwf");
    expect(result).toContain("thread");
@@ -42,6 +36,9 @@ describe("prompt commands", () => {
    expect(result).toContain("---");
    expect(result).toContain("name:");
    expect(result).toContain("version:");
+    // Should NOT contain other references
+    expect(result).not.toContain("Workflow Authoring Reference");
+    expect(result).not.toContain("Adapter Developing Reference");
    expect(result.length).toBeGreaterThan(500);
  });

@@ -71,44 +68,29 @@ describe("prompt commands", () => {
    expect(result.length).toBeGreaterThan(500);
  });

-  test("prompt bootstrap returns non-empty skill with frontmatter", () => {
+  test("prompt bootstrap returns framework-agnostic setup instructions", () => {
    const result = cmdPromptBootstrap();
    expect(typeof result).toBe("string");
-    expect(result).toContain("uwf");
-    expect(result).toContain("---");
-    expect(result.length).toBeGreaterThan(100);
-  });
-
-  test("prompt usage combines remaining references (no developer)", () => {
-    const result = cmdPromptUsage();
-    expect(typeof result).toBe("string");
-    expect(result).toContain("Usage Reference");
-    expect(result).toContain("Workflow Authoring Reference");
-    expect(result).toContain("Adapter Developing Reference");
-    expect(result).not.toContain("Developer Reference");
-    expect(result).toContain("---");
-    expect(result.length).toBeGreaterThan(2000);
-  });
-
-  test("prompt setup returns simplified setup instructions", () => {
-    const result = cmdPromptSetup();
-    expect(typeof result).toBe("string");
-    expect(result).toContain("uwf Skill Setup");
-    expect(result).toContain("uwf prompt bootstrap");
-    expect(result).toContain("SKILL.md");
-    expect(result).toContain("version");
-    expect(result).not.toMatch(/\bbun (install|run|test|changeset|version|release)\b/);
-  });
-
-  test("prompt setup references new subcommand names", () => {
-    const result = cmdPromptSetup();
+    // Skills installation
    expect(result).toContain("uwf prompt usage");
    expect(result).toContain("uwf prompt workflow-authoring");
    expect(result).toContain("uwf prompt adapter-developing");
-    expect(result).not.toContain("uwf prompt user");
-    expect(result).not.toContain("uwf prompt author");
-    expect(result).not.toContain("uwf prompt developer");
-    expect(result).not.toMatch(/uwf prompt adapter\b(?!-developing)/);
+    expect(result).toContain("uwf-usage");
+    expect(result).toContain("uwf-workflow-authoring");
+    expect(result).toContain("uwf-adapter-developing");
+    // Fresh install scenario
+    expect(result).toContain("Fresh Install");
+    expect(result).toContain("uwf setup");
+    expect(result).toContain("--provider");
+    expect(result).toContain("--api-key");
+    expect(result).toContain("agent adapter");
+    // Upgrade scenario
+    expect(result).toContain("Upgrade");
+    expect(result).toContain("Migrate");
+    // Should NOT contain Hermes-specific paths
+    expect(result).not.toContain("~/.hermes/skills/");
+    expect(result).not.toContain("> ~/.hermes/");
+    expect(result.length).toBeGreaterThan(100);
  });

  test("prompt help subcommand is suppressed", { timeout: 30_000 }, () => {
@@ -119,11 +101,12 @@ describe("prompt commands", () => {
    });
    expect(output).not.toMatch(/help\s+\[command\]/i);
    expect(output).toContain("usage");
-    expect(output).toContain("setup");
+    expect(output).toContain("bootstrap");
    expect(output).toContain("workflow-authoring");
    expect(output).toContain("adapter-developing");
-    expect(output).toContain("bootstrap");
    expect(output).toContain("list");
-    expect(output).not.toContain("developer");
+    // Removed subcommands should not appear as command names
+    expect(output).not.toMatch(/^\s+setup\s/m);
+    expect(output).not.toContain("usage-reference");
  });
 });
@@ -253,7 +253,10 @@ describe("thread read timing", () => {
        },
      },
      graph: {
-        $START: { _: { role: "worker", prompt: "go", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "go", location: null },
+          resume: { role: "worker", prompt: "resume", location: null },
+        },
        worker: { done: { role: "$END", prompt: "", location: null } },
      },
    });
@@ -319,7 +322,10 @@ describe("thread read timing", () => {
        },
      },
      graph: {
-        $START: { _: { role: "worker", prompt: "go", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "go", location: null },
+          resume: { role: "worker", prompt: "resume", location: null },
+        },
        worker: { done: { role: "$END", prompt: "", location: null } },
      },
    });
@@ -54,13 +54,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
  $START:
-    _:
+    new:
      role: planner
      prompt: "Plan the work"
      location: null
+    resume:
+      role: planner
+      prompt: "Resume the work"
+      location: null
  planner:
    ready:
      role: $END
@@ -110,13 +114,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
  $START:
-    _:
+    new:
      role: planner
      prompt: "Plan"
      location: null
+    resume:
+      role: planner
+      prompt: "Resume"
+      location: null
  planner:
    ready:
      role: $END
@@ -153,13 +161,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
  $START:
-    _:
+    new:
      role: planner
      prompt: "Plan"
      location: null
+    resume:
+      role: planner
+      prompt: "Resume"
+      location: null
  planner:
    ready:
      role: $END
@@ -70,7 +70,10 @@ async function setupSuspendedThread(mode: MockAgentMode): Promise<{
      },
    },
    graph: {
-      $START: { _: { role: "worker", prompt: "Start work", location: null } },
+      $START: {
+        new: { role: "worker", prompt: "Start work", location: null },
+        resume: { role: "worker", prompt: "Resume the work", location: null },
+      },
      worker: {
        needs_input: {
          role: "$SUSPEND",
@@ -233,7 +236,10 @@ describe("uwf thread resume", () => {
        },
      },
      graph: {
-        $START: { _: { role: "worker", prompt: "Start", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start", location: null },
+          resume: { role: "worker", prompt: "Resume", location: null },
+        },
        worker: { done: { role: "$END", prompt: "Done", location: null } },
      },
    });
@@ -479,7 +485,10 @@ describe("uwf thread resume - completed threads", () => {
        },
      },
      graph: {
-        $START: { _: { role: "worker", prompt: "Start work", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start work", location: null },
+          resume: { role: "worker", prompt: "Resume the work", location: null },
+        },
        worker: { done: { role: "reviewer", prompt: "Review the work", location: null } },
        reviewer: { done: { role: "$END", prompt: "Done", location: null } },
      },
@@ -610,7 +619,7 @@ echo '${adapterJson}'
    expect(cliOutput.done).toBe(false);

    const capturedPrompt = await readFile(promptCapturePath, "utf8");
-    expect(capturedPrompt).toContain("Previous run completed");
+    expect(capturedPrompt).toContain("Resume the work");
    expect(capturedPrompt).toContain("Additional context");

    const storeModule = await import("../store.js");
@@ -640,7 +649,10 @@ echo '${adapterJson}'
        },
      },
      graph: {
-        $START: { _: { role: "worker", prompt: "Start", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start", location: null },
+          resume: { role: "worker", prompt: "Resume", location: null },
+        },
        worker: { done: { role: "$END", prompt: "Done", location: null } },
      },
    });
@@ -688,7 +700,10 @@ echo '${adapterJson}'
        },
      },
      graph: {
-        $START: { _: { role: "worker", prompt: "Start", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start", location: null },
+          resume: { role: "worker", prompt: "Resume", location: null },
+        },
        worker: { done: { role: "$END", prompt: "Done", location: null } },
      },
    });
@@ -31,13 +31,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
  $START:
-    _:
+    new:
      role: planner
      prompt: "Plan the work"
      location: null
+    resume:
+      role: planner
+      prompt: "Resume the work"
+      location: null
  planner:
    ready:
      role: $END
@@ -66,10 +70,14 @@ roles:
            question: { type: string }
 graph:
  $START:
-    _:
+    new:
      role: worker
      prompt: "Start work"
      location: null
+    resume:
+      role: worker
+      prompt: "Resume work"
+      location: null
  worker:
    needs_input:
      role: $SUSPEND
@@ -54,13 +54,17 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
  $START:
-    _:
+    new:
      role: planner
      prompt: "Plan the work"
      location: null
+    resume:
+      role: planner
+      prompt: "Resume the work"
+      location: null
  planner:
    ready:
      role: $END
@@ -58,7 +58,10 @@ describe("suspend step CAS chain and threads.yaml metadata", () => {
          },
        },
        graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
          worker: {
            needs_input: {
              role: "$SUSPEND",
@@ -55,7 +55,10 @@ describe("suspended thread display", () => {
          },
        },
        graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
          worker: {
            needs_input: {
              role: "$SUSPEND",
@@ -162,7 +165,10 @@ describe("suspended thread display", () => {
          },
        },
        graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
          worker: {
            needs_input: {
              role: "$SUSPEND",
@@ -248,7 +254,10 @@ describe("suspended thread display", () => {
          },
        },
        graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
        },
      });

@@ -17,7 +17,7 @@ function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
        frontmatter: {
          type: "object",
          properties: {
-            $status: { enum: ["done"] },
+            $status: { const: "done" },
            plan: { type: "string" },
          },
          required: ["$status", "plan"],
@@ -51,7 +51,10 @@ function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
      },
    },
    graph: {
-      $START: { _: { role: "writer", prompt: "Begin writing", location: null } },
+      $START: {
+        new: { role: "writer", prompt: "Begin writing", location: null },
+        resume: { role: "writer", prompt: "Review previous output and continue", location: null },
+      },
      writer: { done: { role: "reviewer", prompt: "Review this: {{{plan}}}", location: null } },
      reviewer: {
        approved: { role: "$END", prompt: "Done: {{{summary}}}", location: null },
@@ -82,7 +85,7 @@ describe("Suite 1: Role Reference Integrity", () => {
      output: "None",
      frontmatter: {
        type: "object",
-        properties: { $status: { enum: ["done"] } },
+        properties: { $status: { const: "done" } },
        required: ["$status"],
      } as unknown as string,
    };
@@ -135,27 +138,38 @@ describe("Suite 2: Graph Structure", () => {
    expect(errors.some((e) => e.includes("$START must be defined in graph"))).toBe(true);
  });

-  test("2.2 $START has multiple status keys", () => {
+  test("2.2 $START missing resume edge", () => {
    const wf = makeWorkflow();
    wf.graph.$START = {
-      _: { role: "writer", prompt: "Begin", location: null },
-      other: { role: "reviewer", prompt: "Also", location: null },
+      new: { role: "writer", prompt: "Begin", location: null },
    };
    const errors = validateWorkflow(wf);
    expect(
-      errors.some((e) => e.includes('$START must have exactly one edge with status "_"')),
+      errors.some((e) => e.includes('$START must have edges with statuses "new" and "resume"')),
    ).toBe(true);
  });

-  test("2.3 $START edge uses non-_ status", () => {
+  test("2.3 $START missing new edge", () => {
    const wf = makeWorkflow();
-    wf.graph.$START = { ready: { role: "writer", prompt: "Begin", location: null } };
+    wf.graph.$START = {
+      resume: { role: "writer", prompt: "Resume", location: null },
+    };
    const errors = validateWorkflow(wf);
    expect(
-      errors.some((e) => e.includes('$START must have exactly one edge with status "_"')),
+      errors.some((e) => e.includes('$START must have edges with statuses "new" and "resume"')),
    ).toBe(true);
  });

+  test("2.3b $START with new and resume passes", () => {
+    const wf = makeWorkflow();
+    wf.graph.$START = {
+      new: { role: "writer", prompt: "Begin", location: null },
+      resume: { role: "writer", prompt: "Resume", location: null },
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes("$START must have edges"))).toBe(false);
+  });
+
  test("2.4 $END has outgoing edges", () => {
    const wf = makeWorkflow();
    wf.graph.$END = { _: { role: "writer", prompt: "Loop", location: null } };
@@ -173,7 +187,7 @@ describe("Suite 2: Graph Structure", () => {
      output: "Isolated",
      frontmatter: {
        type: "object",
-        properties: { $status: { enum: ["done"] } },
+        properties: { $status: { const: "done" } },
        required: ["$status"],
      } as unknown as string,
    };
@@ -193,15 +207,18 @@ describe("Suite 2: Graph Structure", () => {
 });

 describe("Suite 3: Status-Edge Consistency", () => {
-  test("3.1 user role using _ graph key is rejected", () => {
+  test("3.1 user role using _ graph key is treated as an unknown status", () => {
+    // "_" is no longer special-cased — it's just a status key that does not
+    // match the role's $status enum, so it surfaces as extra/missing keys.
    const wf = makeWorkflow();
    wf.graph.writer = { _: { role: "reviewer", prompt: "Review", location: null } };
    const errors = validateWorkflow(wf);
-    expect(
-      errors.some((e) =>
-        e.includes('role "writer" must use explicit $status keys in graph, not "_"'),
-      ),
-    ).toBe(true);
+    expect(errors.some((e) => e.includes('role "writer" graph has extra status keys: _'))).toBe(
+      true,
+    );
+    expect(errors.some((e) => e.includes('role "writer" graph is missing status keys: done'))).toBe(
+      true,
+    );
  });

  test("3.2 user role graph key not matching $status enum", () => {
@@ -240,20 +257,23 @@ describe("Suite 3: Status-Edge Consistency", () => {
    ).toBe(true);
  });

-  test("3.5 multi-exit role with _ key", () => {
+  test("3.5 multi-exit role with _ key is treated as an unknown status", () => {
    const wf = makeWorkflow();
    wf.graph.reviewer = { _: { role: "$END", prompt: "Done", location: null } };
    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('role "reviewer" graph has extra status keys: _'))).toBe(
+      true,
+    );
    expect(
      errors.some((e) =>
-        e.includes('role "reviewer" must use explicit $status keys in graph, not "_"'),
+        e.includes('role "reviewer" graph is missing status keys: approved, rejected'),
      ),
    ).toBe(true);
  });
 });

-describe("Suite 3b: Enum-Based Multi-Exit", () => {
-  test("3b.1 enum multi-exit passes with matching graph keys", () => {
+describe("Suite 3b: Enum-Based $status is Rejected", () => {
+  test("3b.1 enum multi-exit is rejected (must use oneOf + const)", () => {
    const wf = makeWorkflow();
    wf.roles.reviewer = {
      ...wf.roles.reviewer,
@@ -271,52 +291,10 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
      rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
    };
    const errors = validateWorkflow(wf);
-    expect(errors).toEqual([]);
+    expect(errors.some((e) => e.includes("must define") && e.includes("const"))).toBe(true);
  });

-  test("3b.2 enum multi-exit with extra graph key", () => {
-    const wf = makeWorkflow();
-    wf.roles.reviewer = {
-      ...wf.roles.reviewer,
-      frontmatter: {
-        type: "object",
-        properties: {
-          $status: { enum: ["approved", "rejected"] },
-          comments: { type: "string" },
-        },
-        required: ["$status", "comments"],
-      } as unknown as string,
-    };
-    wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done", location: null },
-      rejected: { role: "writer", prompt: "Fix", location: null },
-      timeout: { role: "$END", prompt: "Timed out", location: null },
-    };
-    const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("extra status keys: timeout"))).toBe(true);
-  });
-
-  test("3b.3 enum multi-exit with missing graph key", () => {
-    const wf = makeWorkflow();
-    wf.roles.reviewer = {
-      ...wf.roles.reviewer,
-      frontmatter: {
-        type: "object",
-        properties: {
-          $status: { enum: ["approved", "rejected"] },
-          comments: { type: "string" },
-        },
-        required: ["$status", "comments"],
-      } as unknown as string,
-    };
-    wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done", location: null },
-    };
-    const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("missing status keys: rejected"))).toBe(true);
-  });
-
-  test("3b.4 enum with single explicit value passes", () => {
+  test("3b.2 enum single-exit is rejected (must use const)", () => {
    const wf = makeWorkflow();
    wf.roles.writer = {
      ...wf.roles.writer,
@@ -331,28 +309,71 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
    };
    wf.graph.writer = { ready: { role: "reviewer", prompt: "Review: {{{plan}}}", location: null } };
    const errors = validateWorkflow(wf);
-    expect(errors).toEqual([]);
+    expect(errors.some((e) => e.includes("must define") && e.includes("const"))).toBe(true);
  });
+});

-  test("3b.5 enum multi-exit mustache var not in frontmatter", () => {
+describe("Suite 3c: Const-Based Flat Schema", () => {
+  test("3c.1 flat schema with const $status passes validation", () => {
    const wf = makeWorkflow();
-    wf.roles.reviewer = {
-      ...wf.roles.reviewer,
+    wf.roles.writer = {
+      ...wf.roles.writer,
      frontmatter: {
        type: "object",
        properties: {
-          $status: { enum: ["approved", "rejected"] },
-          comments: { type: "string" },
+          $status: { const: "done" },
+          plan: { type: "string" },
        },
-        required: ["$status", "comments"],
+        required: ["$status", "plan"],
      } as unknown as string,
    };
-    wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done: {{{nonexistent}}}", location: null },
-      rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
+    const errors = validateWorkflow(wf);
+    expect(errors).toEqual([]);
+  });
+
+  test("3c.2 flat schema with const $status detects extra graph key", () => {
+    const wf = makeWorkflow();
+    wf.roles.writer = {
+      ...wf.roles.writer,
+      frontmatter: {
+        type: "object",
+        properties: {
+          $status: { const: "done" },
+          plan: { type: "string" },
+        },
+        required: ["$status", "plan"],
+      } as unknown as string,
+    };
+    wf.graph.writer = {
+      done: { role: "reviewer", prompt: "Review.", location: null },
+      extra: { role: "$END", prompt: "Nope.", location: null },
    };
    const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("nonexistent") && e.includes("not found"))).toBe(true);
+    expect(errors.some((e) => e.includes("extra status keys") && e.includes("extra"))).toBe(true);
+  });
+
+  test("3c.3 flat schema with const $status validates mustache vars", () => {
+    const wf = makeWorkflow();
+    wf.roles.writer = {
+      ...wf.roles.writer,
+      frontmatter: {
+        type: "object",
+        properties: {
+          $status: { const: "done" },
+          plan: { type: "string" },
+        },
+        required: ["$status", "plan"],
+      } as unknown as string,
+    };
+    wf.graph.writer = {
+      done: { role: "reviewer", prompt: "Review: {{{nonexistent}}}", location: null },
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some(
+        (e) => e.includes('prompt variable "nonexistent"') && e.includes('role "writer"'),
+      ),
+    ).toBe(true);
  });
 });

@@ -460,7 +481,7 @@ describe("Suite 6: Multiple Errors Collection", () => {
      output: "None",
      frontmatter: {
        type: "object",
-        properties: { $status: { enum: ["done"] } },
+        properties: { $status: { const: "done" } },
        required: ["$status"],
      } as unknown as string,
    };
@@ -31,14 +31,17 @@ function makeMinimalPayload(name: string, description: string): WorkflowPayload
        frontmatter: {
          type: "object",
          properties: {
-            $status: { type: "string", enum: ["done"] },
+            $status: { const: "done" },
          },
          required: ["$status"],
        } as unknown as CasRef,
      },
    },
    graph: {
-      $START: { _: { role: "worker", prompt: "start working", location: null } },
+      $START: {
+        new: { role: "worker", prompt: "start working", location: null },
+        resume: { role: "worker", prompt: "resume working", location: null },
+      },
      worker: { done: { role: "$END", prompt: "done", location: null } },
    },
  };
@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning

 import type { CasRef, ThreadId, ThreadStatus } from "@united-workforce/protocol";
 import { Command } from "commander";
@@ -8,12 +8,10 @@ import {
  cmdPromptAdapterDeveloping,
  cmdPromptBootstrap,
  cmdPromptList,
-  cmdPromptSetup,
  cmdPromptUsage,
-  cmdPromptUsageReference,
  cmdPromptWorkflowAuthoring,
 } from "./commands/prompt.js";
-import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import { cmdSetup, cmdSetupInteractive, resolvePresetBaseUrl } from "./commands/setup.js";
 import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
  cmdThreadCancel,
@@ -509,23 +507,16 @@ prompt.addHelpCommand(false);

 prompt
  .command("usage")
-  .description("Print the complete skill content (all references combined)")
+  .description("Print the usage reference (CLI guide + typical workflows)")
  .action(() => {
    console.log(cmdPromptUsage());
  });

 prompt
-  .command("setup")
-  .description("Print setup instructions for installing the uwf skill")
+  .command("bootstrap")
+  .description("Print setup instructions for installing uwf skills")
  .action(() => {
-    console.log(cmdPromptSetup());
-  });
-
-prompt
-  .command("usage-reference")
-  .description("Print the usage reference (CLI guide + typical workflows)")
-  .action(() => {
-    console.log(cmdPromptUsageReference());
+    console.log(cmdPromptBootstrap());
  });

 prompt
@@ -542,13 +533,6 @@ prompt
    console.log(cmdPromptAdapterDeveloping());
  });

-prompt
-  .command("bootstrap")
-  .description("Print the bootstrap skill YAML for Hermes agents")
-  .action(() => {
-    console.log(cmdPromptBootstrap());
-  });
-
 prompt
  .command("list")
  .description("List all available prompt names")
@@ -558,7 +542,7 @@ prompt

 program
  .command("setup")
-  .description("Configure provider, model, and agent")
+  .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")
@@ -574,10 +558,14 @@ program
    }) => {
      const storageRoot = resolveStorageRoot();
      runAction(async () => {
-        if (opts.provider && opts.baseUrl && opts.apiKey && opts.model) {
+        // 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: opts.baseUrl,
+            baseUrl: resolvedBaseUrl,
            apiKey: opts.apiKey,
            model: opts.model,
            agent: opts.agent ?? undefined,
@@ -588,7 +576,7 @@ program
          await cmdSetupInteractive(storageRoot);
        } else {
          throw new Error(
-            "Non-interactive setup requires all of: --provider, --base-url, --api-key, --model",
+            "Non-interactive setup requires: --provider, --api-key, --model (--base-url is optional for preset providers)",
          );
        }
      });
@@ -1,14 +1,38 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
  generateAdapterDevelopingReference,
-  generateBootstrapReference,
  generateUsageReference,
  generateWorkflowAuthoringReference,
 } from "@united-workforce/util";

+// CLI package version (for bootstrap prompt — uwf --version prints this)
+// Walk up from __dirname to find the nearest package.json (works from both src/ and dist/)
+function _findCliVersion(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync(candidate, "utf-8")) as {
+        name?: string;
+        version?: string;
+      };
+      if (pkg.name === "@united-workforce/cli") {
+        return pkg.version ?? "0.0.0";
+      }
+    } catch {
+      // not found, keep walking
+    }
+    dir = dirname(dir);
+  }
+  return "0.0.0";
+}
+const CLI_VERSION = _findCliVersion();
+
 export {
  generateAdapterDevelopingReference as cmdPromptAdapterDeveloping,
-  generateBootstrapReference as cmdPromptBootstrap,
-  generateUsageReference as cmdPromptUsageReference,
+  generateUsageReference as cmdPromptUsage,
  generateWorkflowAuthoringReference as cmdPromptWorkflowAuthoring,
 };

@@ -16,66 +40,291 @@ const PROMPT_ENTRIES: ReadonlyArray<{ name: string; generate: () => string }> =
  { name: "usage", generate: generateUsageReference },
  { name: "workflow-authoring", generate: generateWorkflowAuthoringReference },
  { name: "adapter-developing", generate: generateAdapterDevelopingReference },
-  { name: "bootstrap", generate: generateBootstrapReference },
 ];

 export function cmdPromptList(): ReadonlyArray<string> {
  return PROMPT_ENTRIES.map((e) => e.name);
 }

-export function cmdPromptUsage(): string {
-  return PROMPT_ENTRIES.filter((e) => e.name !== "bootstrap")
-    .map((e) => e.generate())
-    .join("\n\n---\n\n");
-}
+export function cmdPromptBootstrap(): string {
+  return `# uwf Bootstrap

-export function cmdPromptSetup(): string {
-  return `# uwf Skill Setup
+Set up or upgrade uwf (United Workforce) — from zero to running your first workflow.

-You are being asked to install or update the uwf (United Workforce) skill
-so that you know how to use the \`uwf\` CLI for workflow orchestration.
+## Scenario A: Fresh Install

-## Steps
+### Step 0 — Environment pre-flight check

-1. **Check if uwf CLI is installed:**
-   \`\`\`bash
-   uwf --help
-   \`\`\`
-   If not installed: \`npm install -g @united-workforce/cli\`
-
-2. **Clean up old versions of the skill** (if any exist):
-   - Look for any existing uwf/workflow skill files in your skill directories
-     (e.g. \`~/.hermes/skills/uwf/SKILL.md\` or similar paths).
-   - If a skill exists, read its \`version\` from the YAML frontmatter.
-   - If the version matches the current CLI version (\`uwf --version\`), you're done — no update needed.
-   - If the version is older, **delete the old skill file** before proceeding.
-
-3. **Install the bootstrap skill:**
-   \`\`\`bash
-   uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md
-   \`\`\`
-   The bootstrap prompt already includes complete YAML frontmatter — no editing needed.
-
-4. **Verify** the skill is loadable by your agent framework.
-
-## Individual prompts
-
-Each prompt outputs a complete SKILL.md with frontmatter — pipe directly to a file:
+Run ALL checks below BEFORE installing anything. If any check fails, fix it first — do NOT skip ahead.

 \`\`\`bash
-uwf prompt list                                              # list available prompt names
-uwf prompt usage > ~/.hermes/skills/uwf-usage/SKILL.md      # CLI usage guide
-uwf prompt workflow-authoring > ~/.hermes/skills/uwf-workflow-authoring/SKILL.md
-uwf prompt adapter-developing > ~/.hermes/skills/uwf-adapter-developing/SKILL.md
-uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md        # bootstrap skill
+# 1. Node.js
+node --version   # need v20+
+# FIX: install via nvm (https://github.com/nvm-sh/nvm) or your OS package manager
+
+# 2. Package manager — pnpm (preferred) or npm
+pnpm --version || npm --version
+# FIX for pnpm: corepack enable pnpm   (Node 20+)
+#   or: npm install -g pnpm
+# If pnpm is not an option, npm works too — adjust install commands below
+
+# 3. Global bin directory is in PATH
+# For pnpm:
+pnpm bin -g       # prints the global bin directory
+# For npm:
+npm prefix -g     # global prefix; bin is <prefix>/bin
+# The directory printed above MUST be in your PATH.
+# Test: echo \\$PATH | tr ':' '\\\\n'
+# FIX: add the missing directory to your shell's startup file
+#   (e.g. ~/.bashrc, ~/.zshrc, ~/.profile, or fish config):
+#   export PATH="<global-bin-dir>:$PATH"
 \`\`\`

-## Notes
+**All checks must pass before continuing.** If you had to modify PATH, verify the change persists by opening a new shell or sourcing your shell config.

- The skill content is bundled with the CLI and versioned with it — always use
-  \`uwf prompt usage\` to get the content matching your installed version.
- Do NOT hand-edit the skill body. If the CLI is updated, re-run \`uwf prompt setup\`
-  and follow the steps again.
- When upgrading, always delete the old skill first to avoid stale instructions.
+### Step 1 — Discover agents and install adapter
+
+**First, detect which supported agents are already installed on the user's machine:**
+
+\`\`\`bash
+# Check for Hermes Agent
+which hermes 2>/dev/null && hermes --version
+
+# Check for Claude Code
+which claude 2>/dev/null && claude --version   # should show "X.Y.Z (Claude Code)"
+\`\`\`
+
+**Based on the results:**
+
+- **Only hermes found** → install \`uwf-hermes\` adapter
+- **Only claude found** → install \`uwf-claude-code\` adapter
+- **Both found** → ask the user which agent they want uwf to use as default
+- **Neither found** → the user must install at least one agent first:
+  - Hermes Agent: https://hermes-agent.nousresearch.com/docs
+  - Claude Code: \`npm install -g @anthropic-ai/claude-code\`
+
+**Install the uwf CLI and the chosen adapter** using pnpm or npm:
+
+\`\`\`bash
+# CLI (required)
+pnpm add -g @united-workforce/cli       # or: npm install -g @united-workforce/cli
+
+# Adapter — install the one matching the detected agent:
+pnpm add -g @united-workforce/agent-hermes       # or: npm i -g @united-workforce/agent-hermes
+pnpm add -g @united-workforce/agent-claude-code   # or: npm i -g @united-workforce/agent-claude-code
+\`\`\`
+
+**⚠ Adapter versions are independent from CLI versions.** Do NOT try to match adapter version to CLI version. Just install \`@latest\` (the default).
+
+**After installing, verify that \`uwf\` and the adapter are available in PATH:**
+
+\`\`\`bash
+uwf --version          # should print ${CLI_VERSION}
+uwf-hermes --version   # or: uwf-claude-code --version
+\`\`\`
+
+If either command is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:**
+
+1. Find where the binary was installed:
+   \`\`\`bash
+   find ~/.local ~/.hermes /usr/local -name uwf -type f 2>/dev/null
+   npm prefix -g    # global prefix — bin is <prefix>/bin
+   \`\`\`
+2. Add the directory to PATH permanently by appending to the user's shell config (e.g. \`~/.bashrc\`, \`~/.zshrc\`, \`~/.profile\`, or fish config):
+   \`\`\`bash
+   export PATH="<global-bin-dir>:$PATH"
+   \`\`\`
+3. Source the updated config or open a new shell, then re-verify the commands work.
+
+**uwf-hermes** also requires the Hermes ACP plugin. Verify with \`hermes acp --help\`. If not available, install it:
+\`\`\`bash
+# Option A: install into hermes venv (recommended)
+source ~/.hermes/hermes-agent/.venv/bin/activate && pip install hermes-agent[acp]
+
+# Option B: pipx
+pipx install 'hermes-agent[acp]'
+
+# Option C: if installed from source
+pip install -e '.[acp]'
+\`\`\`
+
+### Step 2 — Configure provider and model
+
+uwf needs an LLM provider to run agents. **Ask the user** for their provider, API key, and model, then run:
+
+\`\`\`bash
+uwf setup --provider <name> --api-key <key> --model <model> --agent <adapter-command>
+\`\`\`
+
+**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:
+\`\`\`bash
+uwf setup --provider openrouter --api-key sk-or-... --model anthropic/claude-sonnet-4 --agent uwf-hermes
+\`\`\`
+
+If the user doesn't know what to choose, suggest \`openrouter\` with \`anthropic/claude-sonnet-4\` as a sensible default.
+
+Config is saved to \`~/.uwf/config.yaml\`. Verify with \`cat ~/.uwf/config.yaml\`.
+
+### Step 3 — Install skills
+
+Run each command and create a skill from its output:
+
+\`\`\`bash
+uwf prompt usage               # → save as skill "uwf-usage"
+uwf prompt workflow-authoring  # → save as skill "uwf-workflow-authoring"
+uwf prompt adapter-developing  # → save as skill "uwf-adapter-developing"
+\`\`\`
+
+Each command outputs a complete SKILL.md with YAML frontmatter. Use your agent framework's skill creation API to save them (e.g. \`skill_manage(action='create', name='uwf-usage', content=<output>)\`).
+
+Verify skills are installed by listing them (e.g. \`skills_list()\`) and confirming all three appear.
+
+**⚠ After saving all skills, start a new session** so the agent loads the updated skill content. Skills saved in the current session are not active until the next session.
+
+### Step 4 — Verify end-to-end
+
+Create a minimal workflow file to test your setup:
+
+\`\`\`bash
+cat > /tmp/hello.yaml << 'YAML'
+name: hello
+description: Minimal smoke test
+roles:
+  greeter:
+    description: "Greet the user"
+    goal: "Respond with a friendly greeting"
+    capabilities: []
+    procedure: "Write a short greeting based on the prompt."
+    output: "A greeting message."
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        message: { type: string }
+      required: [$status, message]
+graph:
+  $START:
+    new: { role: greeter, prompt: "Say hello to the user." }
+    resume: { role: greeter, prompt: "Greet the user again." }
+  greeter:
+    done: { role: "$END", prompt: "Done." }
+YAML
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+uwf thread start /tmp/hello.yaml -p "Hello, world!"
+uwf thread exec <thread-id>
+uwf thread show <thread-id>
+\`\`\`
+
+If the thread reaches \`$END\` with status \`completed\`, the setup is working.
+
+## Scenario B: Upgrade from Previous Version
+
+### Step 1 — Update packages
+
+\`\`\`bash
+# Using pnpm
+pnpm add -g @united-workforce/cli@latest
+
+# Using npm
+npm install -g @united-workforce/cli@latest
+\`\`\`
+
+\`\`\`bash
+uwf --version   # should print ${CLI_VERSION}
+\`\`\`
+
+Also update your adapter(s):
+
+\`\`\`bash
+# pnpm
+pnpm add -g @united-workforce/agent-hermes@latest
+
+# npm
+npm install -g @united-workforce/agent-hermes@latest
+\`\`\`
+
+### Step 2 — Regenerate skills
+
+Skill content is bundled with the CLI — always regenerate after upgrading:
+
+\`\`\`bash
+uwf prompt usage               # → update skill "uwf-usage"
+uwf prompt workflow-authoring  # → update skill "uwf-workflow-authoring"
+uwf prompt adapter-developing  # → update skill "uwf-adapter-developing"
+\`\`\`
+
+**⚠ After updating skills, start a new session** to load the new skill content.
+
+### Step 3 — Migrate workflow YAML files (if needed)
+
+Check the changelog for breaking changes. Known migrations:
+
+- **v0.2.0**: \`$START._\` → \`$START.new\` + \`$START.resume\`. All workflow YAML files must be updated:
+  \`\`\`yaml
+  # Before (v0.1.x)
+  $START:
+    _: { role: planner, prompt: "..." }
+
+  # After (v0.2.0+)
+  $START:
+    new: { role: planner, prompt: "..." }
+    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.
+
+- **v0.2.1**: \`$status: { enum: [value] }\` → \`$status: { const: "value" }\`. The validator no longer accepts \`enum\` for \`$status\`. Update all workflow YAML files:
+  \`\`\`yaml
+  # Before (v0.2.0)
+  $status: { enum: [done] }
+  $status: { type: string, enum: ["ready", "failed"] }
+
+  # After (v0.2.1+)
+  $status: { const: "done" }
+  # For multi-exit, use oneOf with const (unchanged)
+  \`\`\`
+
+### Step 4 — Verify
+
+\`\`\`bash
+uwf thread start <your-workflow> -p "upgrade test"
+uwf thread exec <thread-id>
+\`\`\`
+
+## Available prompts
+
+\`\`\`bash
+uwf prompt list                # list available prompt names
+uwf prompt usage               # CLI usage guide
+uwf prompt workflow-authoring  # workflow YAML design guide
+uwf prompt adapter-developing  # building agent adapters
+uwf prompt bootstrap           # this guide
+\`\`\`
 `;
 }
@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
@@ -72,6 +73,12 @@ const PRESET_PROVIDERS = [
  { name: "ollama", label: "Ollama (local)", baseUrl: "http://localhost:11434/v1" },
 ] as const;

+/** Look up the base URL for a preset provider name. Returns null if not a preset. */
+export function resolvePresetBaseUrl(providerName: string): string | null {
+  const preset = PRESET_PROVIDERS.find((p) => p.name === providerName);
+  return preset !== undefined ? preset.baseUrl : null;
+}
+
 type SetupArgs = {
  provider: string;
  baseUrl: string;
@@ -175,7 +182,6 @@ export async function _discoverAgents(): Promise<string[]> {

 async function _tryWhichDiscovery(): Promise<string[] | null> {
  try {
-    const { execFileSync } = await import("node:child_process");
    const text = execFileSync("which", ["-a", "uwf-hermes", "uwf-claude-code", "uwf-cursor"], {
      encoding: "utf-8",
      stdio: ["pipe", "pipe", "pipe"],
@@ -391,6 +397,37 @@ function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record
  };
 }

+/**
+ * Check if the configured adapter binary (and its dependencies) are in PATH.
+ * Returns warnings array — empty means all good.
+ */
+export function _checkAdapterAvailability(agentName: string): string[] {
+  const warnings: string[] = [];
+  const binary = `uwf-${agentName}`;
+
+  try {
+    execFileSync("which", [binary], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  } catch {
+    warnings.push(
+      `${binary} not found in PATH. Install it: pnpm add -g @united-workforce/agent-${agentName}`,
+    );
+    return warnings; // skip dependency check if adapter itself is missing
+  }
+
+  // uwf-hermes depends on hermes CLI
+  if (agentName === "hermes") {
+    try {
+      execFileSync("which", ["hermes"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+    } catch {
+      warnings.push(
+        'hermes CLI not found in PATH (required by uwf-hermes). Fix: export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH"',
+      );
+    }
+  }
+
+  return warnings;
+}
+
 /**
 * Non-interactive setup. All required args provided via CLI flags.
 */
@@ -405,15 +442,26 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>

  writeFileSync(configPath, stringify(merged, { indent: 2 }), "utf8");

+  // Print config path to stderr (stdout is reserved for JSON output)
+  console.error(`Config saved to ${configPath} ✓`);
+
  // Validate model connectivity
  const validation = await validateModel(args.baseUrl, args.apiKey, args.model);

+  // Check adapter availability
+  const agentName = _agentNameFromBinary(args.agent ?? "hermes");
+  const adapterWarnings = _checkAdapterAvailability(agentName);
+  for (const w of adapterWarnings) {
+    console.error(`⚠ ${w}`);
+  }
+
  return {
    configPath,
    provider: args.provider,
    model: args.model,
    defaultAgent: merged.defaultAgent,
    validation,
+    adapterWarnings,
  };
 }

@@ -911,7 +911,7 @@ function resolveEvaluateArgs(
  chain: ChainState,
 ): { lastRole: string; lastOutput: EvaluateLastOutput } {
  if (chain.headIsStart) {
-    return { lastRole: START_ROLE, lastOutput: { [STATUS_KEY]: "_" } };
+    return { lastRole: START_ROLE, lastOutput: { [STATUS_KEY]: "new" } };
  }

  const lastStep = chain.stepsNewestFirst[0];
@@ -961,6 +961,12 @@ function resolveAgentConfig(
  agentOverride: string | null,
 ): AgentConfig {
  if (agentOverride !== null) {
+    // Try config alias first (e.g. "hermes" → config.agents.hermes),
+    // then fall back to raw command name (e.g. "uwf-hermes" or "/usr/bin/agent").
+    const fromAlias = config.agents[agentOverride as AgentAlias];
+    if (fromAlias !== undefined) {
+      return fromAlias;
+    }
    return parseAgentOverride(agentOverride);
  }

@@ -998,6 +1004,12 @@ function spawnAgent(
    });
  } catch (e) {
    const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string | null };
+    if (err.code === "ENOENT") {
+      failStep(
+        plog,
+        `"${agent.command}" not found in PATH. Install it or check your PATH config. Run: which ${agent.command}`,
+      );
+    }
    const stderr =
      err.stderr == null
        ? ""
@@ -1031,7 +1043,6 @@ function archiveThread(uwf: UwfStore, threadId: ThreadId, _workflow: CasRef, _he
  completeThread(uwf.varStore, threadId, "completed");
 }

-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: orchestration function with inherent branching
 export async function cmdThreadResume(
  storageRoot: string,
  threadId: ThreadId,
@@ -1095,7 +1106,7 @@ export async function cmdThreadResume(

  // status === "completed"
  const workflow = loadWorkflowPayload(uwf, workflowHash);
-  const startResult = evaluate(workflow.graph, START_ROLE, {});
+  const startResult = evaluate(workflow.graph, START_ROLE, { [STATUS_KEY]: "resume" });
  if (!startResult.ok) {
    fail(`failed to evaluate $START: ${startResult.error.message}`);
  }
@@ -1107,11 +1118,7 @@ export async function cmdThreadResume(
  }

  const startRole = startResult.value.role;
-  const completedPromptPrefix = "Previous run completed. Resuming with additional context.";
-  const completedResumePrompt =
-    supplement !== null && supplement !== ""
-      ? `${completedPromptPrefix}\n\n${supplement}`
-      : completedPromptPrefix;
+  const completedResumePrompt = buildResumePrompt(startResult.value.prompt, supplement);

  const updatedEntry = { ...entry, status: "idle" as const, completedAt: null };
  setThread(uwf.varStore, threadId, updatedEntry);
@@ -6,11 +6,11 @@ describe("Edge prompt template variable resolution", () => {
  test("returns error when rendered prompt is empty string", () => {
    const graph = {
      $START: {
-        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+        new: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
      },
    };

-    const result = evaluate(graph, "$START", {});
+    const result = evaluate(graph, "$START", { $status: "new" });

    expect(result.ok).toBe(false);
    if (!result.ok) {
@@ -22,11 +22,11 @@ describe("Edge prompt template variable resolution", () => {
  test("returns error when rendered prompt is whitespace-only", () => {
    const graph = {
      $START: {
-        _: { role: "classifier", prompt: "  {{{userPrompt}}}  ", location: null },
+        new: { role: "classifier", prompt: "  {{{userPrompt}}}  ", location: null },
      },
    };

-    const result = evaluate(graph, "$START", {});
+    const result = evaluate(graph, "$START", { $status: "new" });

    expect(result.ok).toBe(false);
    if (!result.ok) {
@@ -38,11 +38,11 @@ describe("Edge prompt template variable resolution", () => {
  test("succeeds when all template variables resolve to non-empty values", () => {
    const graph = {
      $START: {
-        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+        new: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
      },
    };

-    const result = evaluate(graph, "$START", { userPrompt: "Fix the bug" });
+    const result = evaluate(graph, "$START", { $status: "new", userPrompt: "Fix the bug" });

    expect(result.ok).toBe(true);
    if (result.ok) {
@@ -53,11 +53,11 @@ describe("Edge prompt template variable resolution", () => {
  test("succeeds with static (no-variable) prompt", () => {
    const graph = {
      $START: {
-        _: { role: "classifier", prompt: "Classify this input", location: null },
+        new: { role: "classifier", prompt: "Classify this input", location: null },
      },
    };

-    const result = evaluate(graph, "$START", {});
+    const result = evaluate(graph, "$START", { $status: "new" });

    expect(result.ok).toBe(true);
    if (result.ok) {
@@ -68,11 +68,11 @@ describe("Edge prompt template variable resolution", () => {
  test("succeeds when prompt has mix of static text and unresolved variables", () => {
    const graph = {
      $START: {
-        _: { role: "classifier", prompt: "Please handle: {{{userPrompt}}}", location: null },
+        new: { role: "classifier", prompt: "Please handle: {{{userPrompt}}}", location: null },
      },
    };

-    const result = evaluate(graph, "$START", {});
+    const result = evaluate(graph, "$START", { $status: "new" });

    expect(result.ok).toBe(true);
    if (result.ok) {
@@ -83,11 +83,11 @@ describe("Edge prompt template variable resolution", () => {
  test("returns error when ALL variables missing and no static text remains", () => {
    const graph = {
      $START: {
-        _: { role: "classifier", prompt: "{{{a}}}{{{b}}}", location: null },
+        new: { role: "classifier", prompt: "{{{a}}}{{{b}}}", location: null },
      },
    };

-    const result = evaluate(graph, "$START", {});
+    const result = evaluate(graph, "$START", { $status: "new" });

    expect(result.ok).toBe(false);
  });
@@ -6,10 +6,7 @@ import type { EvaluateResult, Result } from "./types.js";
 // Disable HTML escaping — prompts are plain text, not HTML.
 mustache.escape = (text: string) => text;

-const START_ROLE = "$START";
 const SUSPEND_ROLE = "$SUSPEND";
-// $START is a special entry node with no agent output — it always uses this key.
-const START_STATUS = "_";

 type LastOutput = Record<string, unknown>;

@@ -21,9 +18,7 @@ export function evaluate(
  lastOutput: LastOutput,
 ): Result<EvaluateResult, Error> {
  let status: string;
-  if (lastRole === START_ROLE) {
-    status = START_STATUS;
-  } else if (typeof lastOutput[STATUS_KEY] === "string") {
+  if (typeof lastOutput[STATUS_KEY] === "string") {
    status = lastOutput[STATUS_KEY] as string;
  } else {
    return {
@@ -24,22 +24,22 @@ function isOneOfSchema(fm: unknown): fm is SchemaObj & { oneOf: SchemaObj[] } {
  return Array.isArray(obj.oneOf);
 }

-/** Check if a frontmatter schema declares "$status" as an enum (the required form for user roles). */
-function hasStatusEnum(fm: unknown): boolean {
+/** Check if a frontmatter schema declares "$status" as const (flat schema form). */
+function hasStatusConst(fm: unknown): boolean {
  if (typeof fm !== "object" || fm === null) return false;
  const obj = fm as SchemaObj;
  const props = obj.properties as Record<string, SchemaObj> | undefined;
  if (!props?.$status) return false;
-  return Array.isArray(props.$status.enum);
+  return typeof props.$status.const === "string";
 }

-/** Extract status values from an enum-based $status field. */
-function getEnumStatuses(fm: SchemaObj): string[] {
+/** Extract status values from a const-based $status field. */
+function getConstStatuses(fm: SchemaObj): string[] {
  const props = fm.properties as Record<string, SchemaObj> | undefined;
  if (!props?.$status) return [];
  const statusDef = props.$status;
-  if (!Array.isArray(statusDef.enum)) return [];
-  return statusDef.enum as string[];
+  if (typeof statusDef.const === "string") return [statusDef.const];
+  return [];
 }

 /** Get property names from a schema object. */
@@ -97,9 +97,9 @@ function checkGraphStructure(payload: WorkflowPayload, errors: string[]): void {
  if (!graphNodes.has("$START")) {
    errors.push("$START must be defined in graph");
  } else {
-    const startKeys = Object.keys(payload.graph.$START);
-    if (startKeys.length !== 1 || startKeys[0] !== "_") {
-      errors.push('$START must have exactly one edge with status "_"');
+    const startKeys = new Set(Object.keys(payload.graph.$START));
+    if (!startKeys.has("new") || !startKeys.has("resume")) {
+      errors.push('$START must have edges with statuses "new" and "resume"');
    }
  }

@@ -190,22 +190,13 @@ function checkOneOfDiscriminant(
  }
 }

-/** Check status-edge consistency for a user role. "_" is reserved for $START and rejected here. */
+/** Check status-edge consistency for a user role. */
 function checkStatusEdges(
  roleName: string,
  graphKeys: Set<string>,
  statusSet: Set<string>,
  errors: string[],
 ): void {
-  if (graphKeys.has("_")) {
-    errors.push(`role "${roleName}" must use explicit $status keys in graph, not "_"`);
-    return;
-  }
-  if (statusSet.has("_")) {
-    errors.push(`role "${roleName}" $status enum must use explicit values, not "_"`);
-    return;
-  }
-
  const extraKeys = [...graphKeys].filter((k) => !statusSet.has(k));
  const missingKeys = [...statusSet].filter((k) => !graphKeys.has(k));
  if (extraKeys.length > 0) {
@@ -257,21 +248,21 @@ function checkRoleConsistency(payload: WorkflowPayload, errors: string[]): void
      checkOneOfDiscriminant(roleName, variants, statuses, errors);
      checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
      checkMultiExitMustache(roleName, graphEntry, variants, errors);
-    } else if (hasStatusEnum(fm)) {
-      const statuses = getEnumStatuses(fm as SchemaObj);
+    } else if (hasStatusConst(fm)) {
+      const statuses = getConstStatuses(fm as SchemaObj);
      checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
-      // For enum-based schemas, mustache vars come from the flat properties
-      checkEnumMustache(roleName, graphEntry, fm as SchemaObj, errors);
+      // For const-based flat schemas, mustache vars come from the flat properties
+      checkFlatMustache(roleName, graphEntry, fm as SchemaObj, errors);
    } else {
      errors.push(
-        `role "${roleName}" must define "$status" as an enum (or oneOf const) in frontmatter`,
+        `role "${roleName}" must define "$status" as const (or oneOf with const) in frontmatter`,
      );
    }
  }
 }

 /** Check mustache vars in all edge prompts against flat schema properties. */
-function checkEnumMustache(
+function checkFlatMustache(
  roleName: string,
  graphEntry: Record<string, { role: string; prompt: string }>,
  fm: SchemaObj,
@@ -57,13 +57,13 @@ function isGraph(value: unknown): boolean {
  if (!isRecord(value)) {
    return false;
  }
-  return Object.entries(value).every(([node, statusMap]) => {
+  return Object.values(value).every((statusMap) => {
    if (!isRecord(statusMap)) {
      return false;
    }
    return Object.entries(statusMap).every(([status, target]) => {
-      // "_" is only valid as a status key for the $START entry node.
-      if (status === "_" && node !== "$START") {
+      // "_" is no longer a valid status key anywhere — $START uses "new"/"resume".
+      if (status === "_") {
        return false;
      }
      return isTarget(target);
@@ -99,7 +99,7 @@ export function checkWorkflowFilenameConsistency(
 ): string | null {
  const expected = workflowNameFromPath(filePath);
  if (payload.name !== expected) {
-    return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}"`;
+    return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}". Either rename the file to "${payload.name}.yaml" or change the YAML \`name\` field to "${expected}"`;
  }
  return null;
 }
@@ -0,0 +1,9 @@
+# @united-workforce/eval
+
+## 0.1.2
+
+### Patch Changes
+
+- 850a3b2: fix: resolve --agent override via config alias before raw command
+
+  `resolveAgentConfig()` now checks `config.agents[alias]` first before falling back to `parseAgentOverride()`. Eval CLI default `--agent` changed from `"hermes"` to `"uwf-hermes"`.
@@ -91,6 +91,29 @@ describe("frontmatter-compliance judge", () => {
    const result = await runFrontmatterJudge("T4");
    expect(result.score).toBe(0);
  });
+
+  test("parsed object output with $status → score 1.0", async () => {
+    mockedReadSteps.mockReturnValue([
+      makeStep({ role: "a", output: { $status: "done", summary: "fixed" } as unknown as string }),
+      makeStep({ role: "b", output: { $status: "reviewed" } as unknown as string }),
+    ]);
+
+    const result = await runFrontmatterJudge("T5");
+    const data = result.data as { stepsTotal: number; stepsValid: number; invalidSteps: unknown[] };
+
+    expect(result.score).toBe(1.0);
+    expect(data.stepsTotal).toBe(2);
+    expect(data.stepsValid).toBe(2);
+  });
+
+  test("parsed object output missing $status → score 0", async () => {
+    mockedReadSteps.mockReturnValue([
+      makeStep({ role: "a", output: { summary: "no status field" } as unknown as string }),
+    ]);
+
+    const result = await runFrontmatterJudge("T6");
+    expect(result.score).toBe(0);
+  });
 });

 describe("token-stats judge", () => {
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/eval",
-  "version": "0.1.0",
+  "version": "0.1.3",
  "private": false,
  "files": [
    "src",
@@ -7,12 +7,15 @@ import {
  registerRunCommand,
 } from "./commands/index.js";

+// eslint-disable-next-line -- dynamic import for version
+const pkg = await import("../package.json", { with: { type: "json" } });
+
 const program = new Command();

 program
  .name("uwf-eval")
  .description("Evaluate uwf workflow quality with real agents")
-  .version("0.1.0");
+  .version(pkg.default.version, "-V, --version");

 registerRunCommand(program);
 registerReportCommand(program);
@@ -52,7 +52,7 @@ export function registerRunCommand(program: Command): void {
  program
    .command("run <task>")
    .description("Run eval on a task directory or tarball")
-    .option("--agent <name>", "agent adapter to use", "hermes")
+    .option("--agent <name>", "agent adapter to use", "uwf-hermes")
    .option("--model <model>", "model override")
    .option("--count <n>", "number of eval runs", "1")
    .action(async (task: string, opts: RunCliOptions) => {
@@ -39,6 +39,16 @@ function extractFrontmatterYaml(output: unknown): string | null {

 /** Validate a single step's frontmatter, returning a list of errors (empty = valid). */
 function validateStepFrontmatter(output: unknown): string[] {
+  // CAS stores the extracted output as a JSON object after the extract pipeline.
+  // Accept both: parsed object (from step.output) or raw markdown string.
+  if (typeof output === "object" && output !== null && !Array.isArray(output)) {
+    const status = (output as Record<string, unknown>).$status;
+    if (typeof status !== "string" || status.trim() === "") {
+      return ["$status field is missing or not a non-empty string"];
+    }
+    return [];
+  }
+
  const yaml = extractFrontmatterYaml(output);
  if (yaml === null) {
    return ["output does not begin with a valid '---' frontmatter block"];
@@ -143,7 +143,7 @@ describe("buildOutputFormatInstruction", () => {
        {
          type: "object",
          properties: {
-            $status: { type: "string", enum: ["approved"] },
+            $status: { const: "approved" },
            branch: { type: "string" },
          },
          required: ["$status"],
@@ -151,7 +151,7 @@ describe("buildOutputFormatInstruction", () => {
        {
          type: "object",
          properties: {
-            $status: { type: "string", enum: ["rejected"] },
+            $status: { const: "rejected" },
            comments: { type: "string" },
          },
          required: ["$status"],
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/util",
-  "version": "0.1.0",
+  "version": "0.1.3",
  "files": [
    "src",
    "dist",
@@ -1,40 +0,0 @@
-export function generateBootstrapReference(): string {
-  return `---
-name: uwf
-description: "United Workforce (uwf) — YAML 状态机工作流引擎。任务涉及 workflow 时加载此 skill。"
-tags: [workflow, uwf]
-triggers:
-  - uwf
-  - workflow
-  - 工作流
---
-
-# uwf (United Workforce)
-
-YAML 状态机工作流引擎。当用户提到「workflow」「工作流」时，指的是 **uwf workflow**（YAML 定义的状态机），不是 Hermes skill。用 \`uwf\` CLI 操作，不要混淆。
-
-## 首次使用
-
-运行以下命令获取完整用法：
-
-\`\`\`bash
-uwf prompt usage                 # 完整用法文档（所有引用合并）
-uwf prompt workflow-authoring    # workflow 编写指南（role 定义、graph 路由、schema）
-uwf prompt adapter-developing    # adapter 开发指南（构建新的 agent adapter）
-\`\`\`
-
-## 快速参考
-
-\`\`\`bash
-uwf workflow list                          # 查看已注册 workflow
-uwf workflow add <file.yaml>               # 注册 workflow
-uwf thread start <workflow> -p "prompt"    # 创建 thread
-uwf thread exec <thread-id> -c 10          # 执行最多 10 步
-uwf thread list                            # 查看所有 thread
-\`\`\`
-
-## 示例 workflow
-
-参考项目 \`examples/\` 目录下的 YAML 文件（analyze-topic、debate、solve-issue）。
-`;
-}
@@ -2,7 +2,6 @@ export { generateActorReference } from "./actor-reference.js";
 export { generateAdapterDevelopingReference } from "./adapter-developing-reference.js";
 export { generateArchitectureReference } from "./architecture-reference.js";
 export { encodeUint64AsCrockford } from "./base32.js";
-export { generateBootstrapReference } from "./bootstrap-reference.js";
 export { generateCliReference } from "./cli-reference.js";
 export { env } from "./env.js";
 export type {
@@ -16,7 +15,7 @@ export {
  validateFrontmatter,
 } from "./frontmatter-markdown/index.js";
 export { createLogger } from "./logger.js";
-export { generateModeratorReference } from "./moderator-reference.js";
+
 export type {
  CreateProcessLoggerOptions,
  ProcessLogFn,
@@ -36,4 +35,3 @@ export { extractUlidTimestamp, generateUlid } from "./ulid.js";
 export { generateUsageReference } from "./usage-reference.js";
 export { VERSION } from "./version.js";
 export { generateWorkflowAuthoringReference } from "./workflow-authoring-reference.js";
-export { generateYamlReference } from "./yaml-reference.js";
@@ -1,56 +0,0 @@
-export function generateModeratorReference(): string {
-  return `# Moderator Reference
-
-## Overview
-
-The moderator is the workflow engine's routing component. It evaluates the directed graph defined in the workflow YAML to determine the next role (or \`$END\`) after each step — with zero LLM cost.
-
-## Status-Based Routing
-
-The moderator uses **status-based routing**: it inspects the previous step's extracted output (specifically the \`$status\` field) and looks up the corresponding edge in the graph.
-
-### Graph Structure
-
-The graph is a nested map: \`Record<Role | "$START", Record<Status, Target>>\`. Each role maps its possible \`$status\` values to a target with a \`role\` and \`prompt\`:
-
-\`\`\`yaml
-graph:
-  $START:
-    _: { role: planner, prompt: "Analyze the issue." }
-  planner:
-    ready: { role: developer, prompt: "Implement the plan (CAS hash: {{{plan}}})." }
-    insufficient_info: { role: $END, prompt: "Not enough info." }
-  developer:
-    done: { role: reviewer, prompt: "Review branch {{{branch}}} at {{{worktree}}}." }
-    failed: { role: $END, prompt: "Developer failed: {{{reason}}}." }
-  reviewer:
-    approved: { role: tester, prompt: "Run tests on {{{branch}}} at {{{worktree}}}." }
-    rejected: { role: developer, prompt: "Fix issues: {{{comments}}}." }
-\`\`\`
-
-### Routing Algorithm
-
-1. Look up \`graph[lastRole]\` to get the status map for the current role
-2. Look up \`statusMap[lastOutput.$status]\` to get the target
-3. If target role is \`$END\`, mark thread as completed
-4. Otherwise, render the edge prompt (Mustache templates with \`{{{field}}}\` from output) and spawn the next agent
-
-### Edge Prompts and Mustache Templates
-
-Edge prompts use triple-brace Mustache syntax (\`{{{field}}}\`) to interpolate values from the previous step's output into the next agent's task prompt. This passes structured data (branch names, file paths, CAS hashes) between roles without manual wiring.
-
-## Special Nodes
-
- \`$START\` — entry point; uses status key \`_\` (unconditional) since there is no previous output
- \`$END\` — terminal node; thread completes when reached and is moved to history
-
-## Integration with Steps
-
-Each \`uwf thread exec\` cycle:
-1. Moderator reads the thread's head step output
-2. Looks up \`graph[lastRole][output.$status]\` to pick the next role
-3. If next is \`$END\`, marks thread as completed
-4. Otherwise, renders the edge prompt and spawns the agent for the selected role
-5. Extract pipeline parses agent output → new step node → append to CAS chain
-`;
-}
@@ -1,2 +1,9 @@
-// This version is kept in sync with package.json during releases.
-export const VERSION = "0.1.0";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")) as {
+  version: string;
+};
+export const VERSION = pkg.version;
@@ -28,6 +28,7 @@ roles:                         # named actors
      2. Do that
    output: "..."              # what the agent should produce
    frontmatter:               # JSON Schema for structured output
+      type: object
      oneOf:
        - properties:
            $status: { const: "ready" }
@@ -40,7 +41,8 @@ roles:                         # named actors

 graph:                         # status-based routing
  $START:
-    _: { role: planner, prompt: "Analyze the issue." }
+    new: { role: planner, prompt: "Analyze the issue." }
+    resume: { role: planner, prompt: "Review the previous run output and continue." }
  planner:
    ready: { role: developer, prompt: "Implement {{{plan}}}." }
    failed: { role: $END, prompt: "Failed: {{{error}}}" }
@@ -70,10 +72,13 @@ The \`frontmatter\` field is a standard JSON Schema. It defines the structured f

 ### \`$status\` Field

-\`$status\` is the only standard field. Its value determines which graph edge the moderator follows. Use \`const\` to constrain each variant:
+\`$status\` is the only standard field. Its value determines which graph edge the moderator follows.
+
+**Multi-exit (oneOf)** — use \`const\` to constrain each variant:

 \`\`\`yaml
 frontmatter:
+  type: object
  oneOf:
    - properties:
        $status: { const: "done" }
@@ -85,22 +90,26 @@ frontmatter:
      required: [$status, error]
 \`\`\`

-### Custom Fields
-
-Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
-
-### Flat Schema (Single Status)
-
-When a role has only one outcome:
+**Single-exit (flat schema)** — same syntax, just no \`oneOf\` wrapper:

 \`\`\`yaml
 frontmatter:
+  type: object
  properties:
    $status: { const: "done" }
    summary: { type: string }
  required: [$status, summary]
 \`\`\`

+**Important rules:**
+- \`type: object\` is **required** at the top level of frontmatter (both flat and oneOf)
+- \`$status\` always uses \`const: "value"\` — simple and consistent
+- \`enum\` is **not supported** for \`$status\` — the validator will reject it
+
+### Custom Fields
+
+Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
+
 ## Graph Routing

 The graph maps each role's \`$status\` values to the next role:
@@ -113,7 +122,7 @@ graph[role][$status] → { role: nextRole, prompt: edgePrompt }

 | Node | Purpose |
 |------|---------|
-| \`$START\` | Entry point — status key is always \`_\` (unconditional) |
+| \`$START\` | Entry point — status keys \`new\` (first start) and \`resume\` (resuming a completed thread) |
 | \`$END\` | Terminal — thread completes and is archived |

 ### Edge Prompts
@@ -178,7 +187,7 @@ ocas get <output-hash>
 1. Every \`$status\` value in a role's frontmatter has a matching edge in the graph
 2. Every field referenced in edge prompts (\`{{{field}}}\`) exists in the source role's schema
 3. Every role referenced in the graph exists in \`roles\`
-4. \`$START\` has exactly one edge with key \`_\`
+4. \`$START\` has edges with keys \`new\` and \`resume\`
 5. At least one path leads to \`$END\`
 6. No orphan roles (defined but never routed to)

@@ -1,82 +0,0 @@
-export function generateYamlReference(): string {
-  return `# Workflow YAML Schema Reference
-
-## Top-Level Structure
-
-A workflow YAML file defines the complete workflow specification:
-
-\`\`\`yaml
-name: solve-issue          # verb-first kebab-case identifier
-description: "..."         # human-readable description
-
-roles:                     # named actors in the workflow
-  planner:
-    description: "Analyzes issue and outputs a plan"
-    goal: "You are a planning agent."
-    capabilities:
-      - issue-analysis
-      - planning
-    procedure: |
-      1. Read the issue
-      2. Produce a test spec
-    output: "Output the plan summary. Set $status to ready or insufficient_info."
-    frontmatter:           # JSON Schema for structured output (drives routing)
-      oneOf:
-        - properties:
-            $status: { const: ready }
-            plan: { type: string }
-          required: [$status, plan]
-        - properties:
-            $status: { const: insufficient_info }
-          required: [$status]
-
-graph:                     # status-based routing (nested map)
-  $START:
-    _: { role: planner, prompt: "Analyze the issue." }
-  planner:
-    ready: { role: developer, prompt: "Implement plan {{{plan}}}." }
-    insufficient_info: { role: $END, prompt: "Not enough info." }
-\`\`\`
-
-## roles
-
-Each role defines an actor in the workflow:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| \`description\` | string | Short description of the role's purpose |
-| \`goal\` | string | System-level goal statement for the agent |
-| \`capabilities\` | string[] | Tags describing what the role can do |
-| \`procedure\` | string | Step-by-step instructions for the agent |
-| \`output\` | string | Description of expected output format |
-| \`frontmatter\` | JSON Schema | Defines the structured output the agent must produce |
-
-### frontmatter
-
-The \`frontmatter\` field is a standard JSON Schema object. The extract pipeline validates agent output against it. Key conventions:
- \`$status\` field drives routing decisions in the graph
- Use \`const\` or \`enum\` to constrain status values
- Use \`oneOf\` to define multiple valid output shapes (one per status)
- All \`required\` fields must appear in the agent's frontmatter output
-
-## graph
-
-The graph is a nested map defining status-based routing:
-
-\`\`\`
-Record<Role | "$START", Record<Status, { role: string, prompt: string }>>
-\`\`\`
-
-| Level | Key | Value |
-|-------|-----|-------|
-| Outer | Role name or \`$START\` | Status map for that role |
-| Inner | \`$status\` value (or \`_\` for unconditional) | Target: \`{ role, prompt }\` |
-
-### Special Nodes
- \`$START\` — entry point; uses status key \`_\` (unconditional, no previous output)
- \`$END\` — terminal node; thread completes when reached
-
-### Edge Prompts
-Prompts use triple-brace Mustache templates (\`{{{field}}}\`) to interpolate values from the previous step's output. Example: \`"Implement plan {{{plan}}} in repo {{{repoPath}}}."\`
-`;
-}
@@ -21,9 +21,12 @@ graph:
      role: package-metadata
      prompt: Biome setup failed ({{{reason}}}), but continue. Standardize package metadata for repo at {{{repoPath}}}.
  $START:
-    _:
+    new:
      role: workspace
      prompt: Set up bun workspace structure for repo at {{{repoPath}}}.
+    resume:
+      role: workspace
+      prompt: Review the previous run output and continue setting up the bun workspace structure for repo at {{{repoPath}}}.
  release:
    done:
      role: testing
@@ -283,9 +283,12 @@ roles:
        - error
 graph:
  $START:
-    _:
+    new:
      role: planner
      prompt: Analyze the issue and produce an implementation plan.
+    resume:
+      role: planner
+      prompt: Review the previous run output and continue the work.
  planner:
    insufficient_info:
      role: $SUSPEND
Author	SHA1	Message	Date
xiaoju	d97840cf8d	chore: release cli@0.3.0 util@0.1.3 agent-hermes@0.1.3 agent-claude-code@0.1.2 agent-builtin@0.1.2 agent-mock@0.1.2 CI / check (push) Successful in 1m46s Details	2026-06-06 00:13:48 +00:00
xiaomo	b560818f1a	Merge pull request 'fix: bootstrap — session restart hint + v0.2.1 migration note' (#125 ) from fix/123-session-restart-hint into main CI / check (push) Successful in 1m42s Details	2026-06-05 23:54:24 +00:00
xiaoju	f989dee85b	fix: bootstrap — remind to restart session after skill install/update CI / check (pull_request) Successful in 1m42s Details - Step 3 (fresh install): warn skills not active until new session - Step 2 (upgrade): same reminder after regenerating skills - Step 3 (upgrade): add v0.2.1 migration note for enum → const Refs #123	2026-06-05 23:48:53 +00:00
xiaomo	7e4a59de7e	Merge pull request 'fix: workflow-authoring docs — type:object + const vs enum clarity (#123 )' (#124 ) from fix/123-workflow-authoring-docs into main CI / check (push) Successful in 1m42s Details	2026-06-05 23:33:57 +00:00
xiaoju	68079cc003	fix: unify $status to const-only, drop enum support (#123 ) CI / check (pull_request) Successful in 1m43s Details - Validator: hasStatusConst/getConstStatuses replace enum checks - enum in $status is now rejected with clear error message - All docs/examples/tests migrated from enum to const/oneOf - bootstrap hello.yaml updated Fixes #123	2026-06-05 23:31:56 +00:00
xiaoju	1a37928bb9	fix: workflow-authoring docs — type:object + const vs enum clarity (#123 ) CI / check (pull_request) Successful in 1m41s Details - Add type:object to all frontmatter examples (flat and oneOf) - Restructure $status section: Multi-exit (oneOf/const) vs Single-exit (flat/enum) - Add Important rules box clarifying validation requirements - Restore Custom Fields subsection Fixes #123	2026-06-05 23:13:54 +00:00
xiaomo	57511a93fe	Merge pull request 'fix: bootstrap agent discovery + adapter version independence (#120 )' (#122 ) from fix/120-agent-discovery into main CI / check (push) Successful in 1m44s Details	2026-06-05 22:35:54 +00:00
xiaoju	adc3982a4a	fix: bootstrap agent discovery + adapter version independence (#120 ) CI / check (pull_request) Successful in 1m42s Details - Step 1: detect hermes/claude before choosing adapter - Adapter versions independent from CLI — install @latest - ACP verification: hermes acp --help - Remove uwf-builtin (not ready) Refs #120	2026-06-05 22:29:35 +00:00
xiaomo	4580388270	Merge pull request 'fix: bootstrap docs — pnpm/npm parity, adapter order, preset table (#118 )' (#119 ) from fix/118-bootstrap-ux into main CI / check (push) Successful in 2m29s Details	2026-06-05 16:48:47 +00:00
xiaoju	caba82fe36	fix: bootstrap PATH fix guidance — find binary location + update shell config (#118 #1 ) CI / check (pull_request) Successful in 1m44s Details	2026-06-05 16:45:33 +00:00
xiaoju	6aee2ed5ef	fix: bootstrap docs — pnpm/npm parity, adapter order, preset table (#118 ) CI / check (pull_request) Successful in 2m27s Details - Show pnpm and npm install commands side-by-side - Clarify adapter must be installed before uwf setup --agent - Add version verification steps with PATH troubleshooting - --agent takes adapter command name (uwf-hermes), not npm package - Preset providers shown as table with default base URLs - Non-preset providers must specify --base-url manually Fixes #118 (#2, #3, #4, #5)	2026-06-05 16:41:35 +00:00
xiaomo	709b9dc1e5	Merge pull request 'fix: suppress ExperimentalWarning, PEP 668 guidance, setup help (#116 )' (#117 ) from fix/116-setup-ux-2 into main CI / check (push) Successful in 2m21s Details	2026-06-05 16:15:27 +00:00
xiaoju	7a788a9d90	fix: suppress ExperimentalWarning, PEP 668 guidance, setup help CI / check (pull_request) Successful in 2m31s Details - All 5 CLI bins: shebang --disable-warning=ExperimentalWarning - Remove NODE_OPTIONS injection from thread.ts spawn (redundant now) - Bootstrap pip install: venv (recommended) / pipx / source options - setup --help mentions interactive wizard mode - Update shebang test to accept -S flag Fixes #116	2026-06-05 16:12:06 +00:00
xiaomo	e5af5e9027	Merge pull request 'fix: setup UX improvements (#114 )' (#115 ) from fix/114-setup-ux into main CI / check (push) Successful in 2m43s Details	2026-06-05 15:45:02 +00:00
xiaoju	fde87b6274	fix: setup UX improvements — adapter check, ENOENT, SQLite warning, VERSION, PATH docs CI / check (pull_request) Successful in 2m24s Details - setup validates adapter binary availability, prints install command if missing - setup prints 'Config saved to <path> ✓' on success - spawn ENOENT gives actionable error with which command - SQLite ExperimentalWarning suppressed via NODE_OPTIONS - bootstrap VERSION reads cli package.json (was reading util) - bootstrap PATH guidance is shell-agnostic Fixes #114	2026-06-05 15:42:22 +00:00
xiaomo	a33f12c74f	Merge pull request 'fix: bootstrap adds Step 0 environment pre-flight check' (#113 ) from fix/112-bootstrap-preflight into main CI / check (push) Successful in 3m35s Details	2026-06-05 14:34:12 +00:00
xiaoju	0ad10b9b6d	chore: add changeset for #112 CI / check (pull_request) Successful in 6m2s Details	2026-06-05 14:11:47 +00:00
xiaoju	3be92bfac2	fix: bootstrap adds Step 0 environment pre-flight check CI / check (pull_request) Successful in 3m44s Details - Node.js, pnpm/npm, global bin PATH, hermes CLI checks with FIX instructions - Agent must pass all checks before proceeding to install - Install commands changed from npm to pnpm (with npm fallback) - hermes PATH guidance moved from Step 1 to Step 0 Fixes #112	2026-06-05 14:09:33 +00:00
xiaomo	8d6f480b0f	Merge pull request 'fix: workflow-authoring flat schema, bootstrap PATH guidance' (#111 ) from fix/110-bootstrap-workflow-fixes into main CI / check (push) Successful in 2m31s Details	2026-06-05 11:49:48 +00:00
xiaoju	5450bc1230	fix: workflow-authoring flat schema, bootstrap PATH guidance CI / check (pull_request) Successful in 2m18s Details - #110.3: flat schema example uses enum: [done] instead of bare const (bare const fails validate-semantic hasStatusEnum check) - #110.4: bootstrap adds 'which hermes' PATH check and venv guidance - #110.1: already fixed in rc.1 (inline hello.yaml) - #110.2: already fixed in rc.1 (capabilities: [] present) Fixes #110	2026-06-05 11:44:20 +00:00
xiaomo	f1f122b0b1	Merge pull request 'fix: preset base-url auto-fill, bootstrap ACP docs, friendlier errors' (#109 ) from fix/106-107-108-bootstrap-ux into main CI / check (push) Successful in 2m49s Details	2026-06-05 11:16:31 +00:00
xiaoju	57ae6d1755	fix: preset base-url auto-fill, bootstrap ACP docs, friendlier errors CI / check (pull_request) Successful in 2m26s Details - #106: uwf setup --provider <preset> now auto-fills --base-url - #107: bootstrap documents hermes ACP dependency (pip install hermes-agent[acp]) - #107: verify step uses inline hello.yaml instead of missing examples/eval-simple.yaml - #108: workflow name mismatch error suggests how to fix (rename file or change YAML name) Fixes #106, Fixes #107, Fixes #108	2026-06-05 11:06:35 +00:00
xiaomo	d64d150071	Merge pull request 'fix: expand bootstrap prompt with full onboarding and upgrade guide' (#105 ) from fix/104-bootstrap-onboarding into main CI / check (push) Successful in 2m20s Details	2026-06-05 10:39:18 +00:00
xiaoju	c5eb8b79d1	fix: expand bootstrap prompt with full onboarding and upgrade guide CI / check (pull_request) Successful in 2m56s Details - Fresh install: CLI + adapter install, uwf setup, skills, e2e verify - Upgrade: update packages, regenerate skills, migrate workflows - Explicitly tells agent to ask user for provider/api-key/model - Lists all available adapters with install commands - Documents v0.2.0 $START migration Fixes #104	2026-06-05 10:35:01 +00:00
xiaoju	36a3ca6a08	chore: bump cli@0.2.0, util@0.1.2 CI / check (push) Successful in 2m25s Details	2026-06-05 10:11:19 +00:00
xiaomo	eb0b7b514f	Merge pull request 'docs: update wf-stateless-design.md for new/resume $START semantics' (#103 ) from docs/101-stateless-design-update into main CI / check (push) Successful in 2m9s Details	2026-06-05 09:49:23 +00:00
xiaoju	a47871ec4e	chore: remove unused moderator-reference and yaml-reference CI / check (pull_request) Successful in 2m1s Details These generate* functions were exported from util but never consumed by any code. Dead exports are maintenance burden. Refs #101	2026-06-05 09:44:50 +00:00
xiaoju	5851e5d162	docs: update wf-stateless-design.md to reflect new/resume semantics CI / check (pull_request) Successful in 2m23s Details Refs #101	2026-06-05 09:38:01 +00:00
xiaomo	61dfb40933	Merge pull request 'feat: replace $START `_` status with `new`/`resume` semantics' (#102 ) from feat/101-start-new-resume into main CI / check (push) Successful in 2m42s Details	2026-06-05 09:35:35 +00:00
xiaoju	fbfd31a042	feat: replace $START `_` status with `new`/`resume` semantics CI / check (pull_request) Successful in 2m27s Details BREAKING: All workflow YAML files must update $START._ to $START.new + $START.resume. The resume edge prompt replaces the previously hardcoded resume message. - evaluate.ts: remove START_ROLE/START_STATUS special case, use $status like all nodes - thread.ts: resolveEvaluateArgs passes 'new', cmdThreadResume passes 'resume' - validate.ts: reject '_' everywhere (no longer valid) - validate-semantic.ts: require 'new' and 'resume' edges on $START - All workflow YAMLs and test fixtures updated Fixes #101	2026-06-05 09:30:09 +00:00
xiaomo	d99a376b60	Merge pull request 'fix: simplify prompt subcommands, framework-agnostic bootstrap' (#100 ) from fix/99-prompt-cleanup into main CI / check (push) Successful in 3m19s Details	2026-06-05 09:03:56 +00:00
xiaoju	a536efee00	fix: simplify prompt subcommands, framework-agnostic bootstrap CI / check (pull_request) Successful in 3m24s Details - `uwf prompt usage` now outputs only the usage skill (was three combined) - `uwf prompt bootstrap` replaces `setup` with framework-agnostic instructions - Remove `usage-reference` and `setup` subcommands - Remove `generateBootstrapReference` from util (moved to cli) Fixes #99 小橘 🍊（NEKO Team）	2026-06-05 08:52:35 +00:00
xiaoju	9260d81084	chore: version bump for --version fix CI / check (push) Successful in 3m2s Details agent-hermes@0.1.2 agent-claude-code@0.1.1 agent-builtin@0.1.1 agent-mock@0.1.1 eval@0.1.3 util@0.1.1 小橘 🍊（NEKO Team）	2026-06-05 08:12:50 +00:00
xiaomo	c8d884072a	Merge pull request 'fix: acp-client reports agent-hermes own version in MCP clientInfo' (#98 ) from fix/acp-client-own-version into main CI / check (push) Successful in 2m27s Details	2026-06-05 08:10:57 +00:00
xiaoju	abeb465f46	fix: acp-client reports own package version, not util VERSION CI / check (pull_request) Successful in 2m36s Details Address review nit from PR #97: clientInfo.version should be agent-hermes's own version for correct identification under independent versioning. 小橘 🍊（NEKO Team）	2026-06-05 07:50:03 +00:00
xiaomo	28427a973f	Merge pull request 'fix: add --version to adapter CLIs, read VERSION from package.json' (#97 ) from fix/adapter-version into main CI / check (push) Successful in 3m3s Details	2026-06-05 07:36:15 +00:00
xiaoju	794f9db568	fix: add --version to adapter CLIs, read VERSION from package.json CI / check (pull_request) Successful in 3m29s Details - All uwf-* adapter CLIs now support --version / -V - util VERSION constant reads from package.json at runtime - agent-hermes ACP clientInfo uses dynamic VERSION 小橘 🍊（NEKO Team）	2026-06-05 07:29:54 +00:00
xiaoju	cd585a26f1	Merge pull request 'fix: read eval CLI version from package.json' (#96 ) from fix/95-eval-version into main CI / check (push) Successful in 3m28s Details	2026-06-05 06:46:32 +00:00
xiaoju	1cf8f350d0	fix: read eval CLI version from package.json CI / check (pull_request) Successful in 3m30s Details Fixes #95 小橘 🍊（NEKO Team）	2026-06-05 06:43:27 +00:00
xiaoju	427568a21d	chore: version bump agent-hermes@0.1.1 cli@0.1.1 eval@0.1.2 CI / check (push) Successful in 2m37s Details 小橘 🍊（NEKO Team）	2026-06-05 06:29:25 +00:00
xiaomo	d3a2353acf	Merge pull request 'fix: read token usage from ACP response instead of DB' (#94 ) from fix/usage-tokens-from-acp into main CI / check (push) Successful in 3m25s Details	2026-06-05 06:18:05 +00:00
xiaoju	8085d1d6e0	fix: read token usage from ACP response instead of DB CI / check (pull_request) Successful in 3m10s Details Tokens (inputTokens, outputTokens) now come from ACP PromptResponse.usage which is populated synchronously from run_conversation() — no WAL race. Turns still come from DB before/after snapshot. Previously both were read from hermes state.db after ACP prompt returned, but WAL write lag caused incomplete token data (e.g. 235 vs actual 26,080). Refs #91	2026-06-05 06:08:11 +00:00
xiaomo	8764d7bda3	Merge pull request 'chore: add changeset for #92 agent override alias fix' (#93 ) from chore/changeset-agent-override into main CI / check (push) Successful in 3m33s Details	2026-06-05 05:17:36 +00:00
xiaoju	850a3b2f25	chore: add changeset for #92 agent override alias fix CI / check (pull_request) Successful in 3m8s Details	2026-06-05 04:36:41 +00:00
xiaomo	3d6a517e83	Merge pull request 'fix: resolve --agent override via config alias before raw command' (#92 ) from fix/agent-override-alias into main CI / check (push) Successful in 3m30s Details	2026-06-05 04:31:50 +00:00
xiaoju	825f0c641a	fix: resolve --agent override via config alias before raw command CI / check (pull_request) Successful in 3m37s Details When --agent is passed to uwf thread exec, try config.agents[alias] first (e.g. 'hermes' → config.agents.hermes = {command: 'uwf-hermes'}), then fall back to parseAgentOverride for raw command names. Also change eval CLI default --agent from 'hermes' to 'uwf-hermes' so it works without config alias lookup. Refs #91	2026-06-05 04:20:09 +00:00
xiaoju	81bbe1178f	chore: release @united-workforce/eval@0.1.1 CI / check (push) Successful in 2m45s Details	2026-06-05 03:02:05 +00:00
xiaoju	a0e139935e	Merge pull request 'fix: frontmatter judge handles parsed object output' (#90 ) from fix/frontmatter-judge-object-output into main CI / check (push) Successful in 2m12s Details	2026-06-05 03:01:30 +00:00
xiaoju	a08775896f	fix: frontmatter judge handles parsed object output CI / check (pull_request) Successful in 2m38s Details The extract pipeline stores step output as a JSON object in CAS, but the frontmatter judge only checked for raw markdown strings. Now accepts both formats: parsed objects check $status directly, raw strings go through YAML frontmatter extraction. Fixes eval frontmatter-compliance scoring 0 on valid outputs.	2026-06-05 02:55:58 +00:00