fix: setup UX improvements — adapter check, ENOENT, SQLite warning, VERSION, PATH docs

- 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

.changeset/bootstrap-onboarding.md

@@ -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)

.changeset/bootstrap-preflight.md

@@ -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)

.changeset/bootstrap-schema-path.md

@@ -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)

.changeset/bootstrap-ux-fixes.md

@@ -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)

.changeset/setup-ux-improvements.md

@@ -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)

packages/cli/src/__tests__/prompt.test.ts

@@ -71,12 +71,22 @@ describe("prompt commands", () => {
   test("prompt bootstrap returns framework-agnostic setup instructions", () => {
     const result = cmdPromptBootstrap();
     expect(typeof result).toBe("string");
+    // Skills installation
     expect(result).toContain("uwf prompt usage");
     expect(result).toContain("uwf prompt workflow-authoring");
     expect(result).toContain("uwf prompt adapter-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/");

packages/cli/src/cli.ts

@@ -11,7 +11,7 @@ import {
   cmdPromptUsage,
   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,
@@ -558,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,
@@ -572,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)",
           );
         }
       });

packages/cli/src/commands/prompt.ts

@@ -1,10 +1,35 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   generateAdapterDevelopingReference,
   generateUsageReference,
   generateWorkflowAuthoringReference,
-  VERSION,
 } 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,
   generateUsageReference as cmdPromptUsage,
@@ -22,33 +47,189 @@ export function cmdPromptList(): ReadonlyArray<string> {
 }
 
 export function cmdPromptBootstrap(): string {
-  return `# uwf Skill Bootstrap
+  return `# uwf Bootstrap
 
-Install or update the uwf (United Workforce) skills for your agent.
+Set up or upgrade uwf (United Workforce) — from zero to running your first workflow.
 
-## Steps
+## Scenario A: Fresh Install
+
+### Step 0 — Environment pre-flight check
+
+Run ALL checks below BEFORE installing anything. If any check fails, fix it first — do NOT skip ahead.
 
-1. **Check if uwf CLI is installed:**
 \`\`\`bash
-   uwf --help
+# 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"
+
+# 4. (uwf-hermes only) hermes CLI
+which hermes
+# FIX: if hermes is in a virtualenv, add it to PATH:
+#   export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH"
+#   or create a symlink: ln -s ~/.hermes/hermes-agent/.venv/bin/hermes ~/.local/bin/hermes
 \`\`\`
-   If not installed: \`npm install -g @united-workforce/cli\`
-   Current version: ${VERSION}
 
-2. **Install the skills** by running each command below and creating a skill from its output:
-   - Run \`uwf prompt usage\` → create a skill named \`uwf-usage\`
-   - Run \`uwf prompt workflow-authoring\` → create a skill named \`uwf-workflow-authoring\`
-   - Run \`uwf prompt adapter-developing\` → create a skill named \`uwf-adapter-developing\`
+**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.
 
-   Each command outputs a complete SKILL.md with YAML frontmatter — use your agent framework's skill creation API to save them.
+### Step 1 — Install CLI and agent adapter
 
-3. **Verify** the skills are loadable by your agent framework.
+\`\`\`bash
+pnpm add -g @united-workforce/cli    # or: npm install -g @united-workforce/cli
+uwf --version   # should print ${CLI_VERSION}
+\`\`\`
 
-## Updating
+Install an agent adapter (at least one is required):
 
-When \`uwf\` is upgraded, re-run \`uwf prompt bootstrap\` and follow the steps again.
-The skill content is bundled with the CLI — always use \`uwf prompt <name>\` to get
-content matching your installed version.
+| Adapter | Install | When to use |
+|---------|---------|-------------|
+| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent |
+| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly |
+| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) |
+
+**uwf-hermes** also requires the Hermes ACP plugin. After installing \`hermes-agent\`, run:
+\`\`\`bash
+pip install hermes-agent[acp]   # or: pip install -e .[acp] if installed from source
+\`\`\`
+
+Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose).
+
+### 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> --base-url <url> --api-key <key> --model <model> [--agent <adapter>]
+\`\`\`
+
+Preset providers (base-url is auto-filled when using a preset name):
+openai, xai, openrouter, venice, dashscope, deepseek, siliconflow, volcengine, kimi, glm, stepfun, minimax, ollama
+
+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.
+
+### 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: { enum: [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
+pnpm add -g @united-workforce/cli@latest    # or: npm install -g @united-workforce/cli@latest
+uwf --version   # should print ${CLI_VERSION}
+
+# Also update your adapter(s)
+pnpm add -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"
+\`\`\`
+
+### 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.
+
+### Step 4 — Verify
+
+\`\`\`bash
+uwf thread start <your-workflow> -p "upgrade test"
+uwf thread exec <thread-id>
+\`\`\`
 
 ## Available prompts
 
@@ -57,6 +238,7 @@ 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
 \`\`\`
 `;
 }

packages/cli/src/commands/setup.ts

@@ -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,
   };
 }
 

packages/cli/src/commands/thread.ts

@@ -1001,9 +1001,21 @@ function spawnAgent(
       stdio: ["ignore", "pipe", "pipe"],
       maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
       cwd,
+      env: {
+        ...process.env,
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"]
+          .filter(Boolean)
+          .join(" "),
+      },
     });
   } 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
         ? ""
@@ -1242,6 +1254,12 @@ async function cmdThreadStepBackground(
   const child = spawn(scriptPath, args, {
     detached: true,
     stdio: "ignore",
+    env: {
+      ...process.env,
+      NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"]
+        .filter(Boolean)
+        .join(" "),
+    },
   });
 
   child.unref();

packages/cli/src/validate.ts

@@ -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;
 }

packages/util/src/workflow-authoring-reference.ts

@@ -92,16 +92,21 @@ Add any fields you need for data passing between roles. These are available in e
 
 ### Flat Schema (Single Status)
 
-When a role has only one outcome:
+When a role has only one outcome, use \`enum\` with a single value:
 
 \`\`\`yaml
 frontmatter:
+  type: object
   properties:
-    $status: { const: "done" }
+    $status:
+      type: string
+      enum: [done]
     summary: { type: string }
   required: [$status, summary]
 \`\`\`
 
+Note: \`$status: { const: "done" }\` is **not** valid in flat schemas — the validator requires \`enum\` or \`oneOf\` with \`const\`. Use \`const\` only inside \`oneOf\` variants.
+
 ## Graph Routing
 
 The graph maps each role's \`$status\` values to the next role: