.changeset/bootstrap-ux-3.md

@@ -0,0 +1,13 @@
+---
+"@united-workforce/cli": patch
+---
+
+fix: improve bootstrap docs — pnpm/npm parity, adapter install order, preset provider table (#118)
+
+- Step 1: show pnpm and npm side-by-side (not just pnpm with a comment)
+- Step 1: add "adapter must be installed before `uwf setup --agent`" note
+- Step 1: add `uwf --version` and adapter version verification with PATH troubleshooting
+- 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
+- Step 2: non-preset providers must specify `--base-url` manually
+- Upgrade scenario: also show npm alternatives

packages/cli/src/commands/prompt.ts

@@ -90,18 +90,43 @@ which hermes
 
 ### Step 1 — Install CLI and agent adapter
 
+Install the CLI using **either** pnpm or npm:
+
 \`\`\`bash
-pnpm add -g @united-workforce/cli    # or: npm install -g @united-workforce/cli
-uwf --version   # should print ${CLI_VERSION}
+# Using pnpm (recommended)
+pnpm add -g @united-workforce/cli
+
+# Using npm
+npm install -g @united-workforce/cli
 \`\`\`
 
-Install an agent adapter (at least one is required):
+Next, install an agent adapter (**must be installed before running \`uwf setup --agent\`**):
 
-| 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) |
+| Adapter | Install (pnpm / npm) | When to use |
+|---------|----------------------|-------------|
+| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` / \`npm i -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent |
+| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` / \`npm i -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly |
+| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` / \`npm i -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) |
+
+**After installing, verify that \`uwf\` and the adapter command (e.g. \`uwf-hermes\`) are available in PATH.** Run:
+
+\`\`\`bash
+uwf --version          # should print ${CLI_VERSION}
+uwf-hermes --version   # (or uwf-claude-code / uwf-builtin)
+\`\`\`
+
+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:
 \`\`\`bash
@@ -115,18 +140,35 @@ pipx install 'hermes-agent[acp]'
 pip install -e '.[acp]'
 \`\`\`
 
-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>]
+uwf setup --provider <name> --api-key <key> --model <model> --agent <adapter-command>
 \`\`\`
 
-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
+**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
@@ -196,11 +238,25 @@ If the thread reaches \`$END\` with status \`completed\`, the setup is working.
 ### 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}
+# Using pnpm
+pnpm add -g @united-workforce/cli@latest
 
-# Also update your adapter(s)
+# 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