fix: suppress ExperimentalWarning, PEP 668 guidance, setup help

- 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

.changeset/setup-ux-2.md

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

packages/agent-builtin/src/cli.ts

@@ -1,4 +1,4 @@
-#!/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" } });

packages/agent-claude-code/src/cli.ts

@@ -1,4 +1,4 @@
-#!/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" } });

packages/agent-hermes/__tests__/issue-551.test.ts

@@ -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", () => {

packages/agent-hermes/src/cli.ts

@@ -1,4 +1,4 @@
-#!/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" } });

packages/agent-mock/src/cli.ts

@@ -1,4 +1,4 @@
-#!/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" } });

packages/cli/src/cli.ts

@@ -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";
@@ -542,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")

packages/cli/src/commands/prompt.ts

@@ -103,9 +103,16 @@ Install an agent adapter (at least one is required):
 | 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:
+**uwf-hermes** also requires the Hermes ACP plugin:
 \`\`\`bash
-pip install hermes-agent[acp]   # or: pip install -e .[acp] if installed from source
+# 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]'
 \`\`\`
 
 Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose).

packages/cli/src/commands/thread.ts

@@ -1001,12 +1001,6 @@ 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 };
@@ -1254,12 +1248,6 @@ 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();