From 3be92bfac29d2175adab14b942f6556edd5473a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= <xiaoju@shazhou.work>
Date: Fri, 5 Jun 2026 14:09:33 +0000
Subject: [PATCH 1/2] fix: bootstrap adds Step 0 environment pre-flight check

- 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
---
 packages/cli/src/commands/prompt.ts | 52 +++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts
index 7daee8b..8a325a4 100644
--- a/packages/cli/src/commands/prompt.ts
+++ b/packages/cli/src/commands/prompt.ts
@@ -28,10 +28,45 @@ Set up or upgrade uwf (United Workforce) — from zero to running your first wor
 
 ## 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.
+
+\`\`\`bash
+# 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 root -g 2>/dev/null && pnpm bin -g
+# For npm:
+npm prefix -g
+# The "bin" directory printed above MUST be in your PATH.
+# Test: echo $PATH | tr ':' '\\n' | grep -E "(pnpm|npm|node)"
+# FIX: add the bin directory to ~/.profile or ~/.bashrc:
+#   export PATH="$(pnpm bin -g):$PATH"   # pnpm
+#   export PATH="$(npm prefix -g)/bin:$PATH"  # npm
+
+# 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
+\`\`\`
+
+**All checks must pass before continuing.** If you had to modify PATH, verify the change persists by opening a new shell or sourcing your profile.
+
 ### Step 1 — Install CLI and agent adapter
 
 \`\`\`bash
-npm install -g @united-workforce/cli
+pnpm add -g @united-workforce/cli    # or: npm install -g @united-workforce/cli
 uwf --version   # should print ${VERSION}
 \`\`\`
 
@@ -39,20 +74,15 @@ Install an agent adapter (at least one is required):
 
 | Adapter | Install | When to use |
 |---------|---------|-------------|
-| uwf-hermes | \`npm install -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent |
-| uwf-claude-code | \`npm install -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly |
-| uwf-builtin | \`npm install -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) |
+| 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 \`hermes\` is in your PATH: \`which hermes\`. If Hermes is installed in a virtualenv (e.g. \`~/.hermes/hermes-agent/.venv/\`), activate it or add the bin directory to PATH:
-\`\`\`bash
-export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH"
-\`\`\`
-
 Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose).
 
 ### Step 2 — Configure provider and model
@@ -134,11 +164,11 @@ If the thread reaches \`$END\` with status \`completed\`, the setup is working.
 ### Step 1 — Update packages
 
 \`\`\`bash
-npm install -g @united-workforce/cli@latest
+pnpm add -g @united-workforce/cli@latest    # or: npm install -g @united-workforce/cli@latest
 uwf --version   # should print ${VERSION}
 
 # Also update your adapter(s)
-npm install -g @united-workforce/agent-hermes@latest
+pnpm add -g @united-workforce/agent-hermes@latest
 \`\`\`
 
 ### Step 2 — Regenerate skills
-- 
2.43.0


From 0ad10b9b6d446087d4f14fc156075a48adb51181 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= <xiaoju@shazhou.work>
Date: Fri, 5 Jun 2026 14:11:47 +0000
Subject: [PATCH 2/2] chore: add changeset for #112

---
 .changeset/bootstrap-preflight.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 .changeset/bootstrap-preflight.md

diff --git a/.changeset/bootstrap-preflight.md b/.changeset/bootstrap-preflight.md
new file mode 100644
index 0000000..ad72cdf
--- /dev/null
+++ b/.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)
-- 
2.43.0