feat(cli): add WORKFLOW_STORAGE_ROOT env var support

Add user-facing WORKFLOW_STORAGE_ROOT environment variable to override
the default storage directory (~/.uncaged/workflow). The existing
UNCAGED_WORKFLOW_STORAGE_ROOT (internal/test) takes priority.

- Update storage-env.ts with priority chain: internal > user > default
- Add env var documentation to CLI help text
- Add 5 tests covering all priority/fallback scenarios

Fixes #63

packages/cli-workflow/__tests__/help.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import { runCli } from "../src/cli-dispatch.js";
+import { formatSkillDoc } from "../src/cmd-help.js";
+
+const STORAGE_ROOT = "/tmp/help-test-storage";
+
+describe("help command", () => {
+  test("help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["help"]);
+    expect(code).toBe(0);
+  });
+
+  test("help --skill returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["help", "--skill"]);
+    expect(code).toBe(0);
+  });
+});
+
+describe("formatSkillDoc", () => {
+  const doc = formatSkillDoc();
+
+  test("contains title", () => {
+    expect(doc).toContain("# uncaged-workflow CLI Reference");
+  });
+
+  test("contains all command group headers", () => {
+    expect(doc).toContain("### workflow");
+    expect(doc).toContain("### thread");
+    expect(doc).toContain("### cas");
+    expect(doc).toContain("### init");
+    expect(doc).toContain("### Top-level shortcuts");
+  });
+
+  test("contains core concepts", () => {
+    expect(doc).toContain("## Core Concepts");
+    expect(doc).toContain("Workflow");
+    expect(doc).toContain("Bundle");
+    expect(doc).toContain("Thread");
+    expect(doc).toContain("CAS");
+    expect(doc).toContain("Registry");
+  });
+
+  test("mentions all workflow subcommands", () => {
+    for (const sub of ["add", "list", "show", "rm", "history", "rollback"]) {
+      expect(doc).toContain(`workflow ${sub}`);
+    }
+  });
+
+  test("mentions all thread subcommands", () => {
+    for (const sub of [
+      "run",
+      "list",
+      "show",
+      "rm",
+      "fork",
+      "ps",
+      "kill",
+      "live",
+      "pause",
+      "resume",
+    ]) {
+      expect(doc).toContain(`thread ${sub}`);
+    }
+  });
+
+  test("mentions all cas subcommands", () => {
+    for (const sub of ["get", "put", "list", "rm", "gc"]) {
+      expect(doc).toContain(`cas ${sub}`);
+    }
+  });
+
+  test("contains exit codes section", () => {
+    expect(doc).toContain("## Exit Codes");
+  });
+
+  test("contains environment variables section", () => {
+    expect(doc).toContain("## Environment Variables");
+    expect(doc).toContain("UNCAGED_WORKFLOW_STORAGE_ROOT");
+  });
+
+  test("contains typical workflow section", () => {
+    expect(doc).toContain("## Typical Workflow");
+  });
+});

packages/cli-workflow/__tests__/storage-env.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow";
+import { resolveWorkflowStorageRoot } from "../src/storage-env.js";
+
+describe("resolveWorkflowStorageRoot", () => {
+  let savedInternal: string | undefined;
+  let savedUser: string | undefined;
+
+  beforeEach(() => {
+    savedInternal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    savedUser = process.env.WORKFLOW_STORAGE_ROOT;
+    delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    delete process.env.WORKFLOW_STORAGE_ROOT;
+  });
+
+  afterEach(() => {
+    if (savedInternal === undefined) {
+      delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    } else {
+      process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = savedInternal;
+    }
+    if (savedUser === undefined) {
+      delete process.env.WORKFLOW_STORAGE_ROOT;
+    } else {
+      process.env.WORKFLOW_STORAGE_ROOT = savedUser;
+    }
+  });
+
+  test("returns default when no env vars are set", () => {
+    expect(resolveWorkflowStorageRoot()).toBe(getDefaultWorkflowStorageRoot());
+  });
+
+  test("WORKFLOW_STORAGE_ROOT overrides default", () => {
+    process.env.WORKFLOW_STORAGE_ROOT = "/tmp/custom-storage";
+    expect(resolveWorkflowStorageRoot()).toBe("/tmp/custom-storage");
+  });
+
+  test("UNCAGED_WORKFLOW_STORAGE_ROOT takes priority over WORKFLOW_STORAGE_ROOT", () => {
+    process.env.WORKFLOW_STORAGE_ROOT = "/tmp/user-path";
+    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = "/tmp/internal-path";
+    expect(resolveWorkflowStorageRoot()).toBe("/tmp/internal-path");
+  });
+
+  test("ignores empty WORKFLOW_STORAGE_ROOT", () => {
+    process.env.WORKFLOW_STORAGE_ROOT = "";
+    expect(resolveWorkflowStorageRoot()).toBe(getDefaultWorkflowStorageRoot());
+  });
+
+  test("ignores empty UNCAGED_WORKFLOW_STORAGE_ROOT and falls through to WORKFLOW_STORAGE_ROOT", () => {
+    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = "";
+    process.env.WORKFLOW_STORAGE_ROOT = "/tmp/user-fallback";
+    expect(resolveWorkflowStorageRoot()).toBe("/tmp/user-fallback");
+  });
+});

packages/cli-workflow/src/cli-dispatch.ts

@@ -3,6 +3,7 @@ import { cmdAdd, formatAddSuccess, parseAddArgv } from "./cmd-add.js";
 import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "./cmd-cas.js";
 import { cmdFork, parseForkArgv } from "./cmd-fork.js";
 import { cmdGc } from "./cmd-gc.js";
+import { formatSkillDoc } from "./cmd-help.js";
 import { cmdHistory } from "./cmd-history.js";
 import { cmdInitTemplate, cmdInitWorkspace } from "./cmd-init.js";
 import { cmdKill } from "./cmd-kill.js";
@@ -53,6 +54,10 @@ export function formatCliUsage(): string {
     "",
     "  uncaged-workflow run <name> [...]          (shortcut for thread run)",
     "  uncaged-workflow live <thread-id> [...]    (shortcut for thread live)",
+    "",
+    "Environment variables:",
+    "  WORKFLOW_STORAGE_ROOT              Override storage directory (default: ~/.uncaged/workflow)",
+    "  UNCAGED_WORKFLOW_STORAGE_ROOT      Internal override (takes priority over WORKFLOW_STORAGE_ROOT)",
   ].join("\n");
 }
 
@@ -501,6 +506,17 @@ async function dispatchThread(storageRoot: string, argv: string[]): Promise<numb
   return handler(storageRoot, argv.slice(1));
 }
 
+// ── Help ────────────────────────────────────────────────────────────────
+
+async function dispatchHelp(_storageRoot: string, argv: string[]): Promise<number> {
+  if (argv.includes("--skill")) {
+    printCliLine(formatSkillDoc());
+  } else {
+    printCliLine(formatCliUsage());
+  }
+  return 0;
+}
+
 // ── Top-level command table (Phase 3) ──────────────────────────────────
 
 const COMMAND_TABLE: Record<string, DispatchFn> = {
@@ -509,6 +525,7 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
   thread: dispatchThread,
   cas: dispatchCas,
   init: dispatchInit,
+  help: dispatchHelp,
 
   // Top-level shortcuts (no deprecation)
   run: dispatchRun,

packages/cli-workflow/src/cmd-help.ts

@@ -0,0 +1,86 @@
+export function formatSkillDoc(): string {
+  return `# uncaged-workflow CLI Reference
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Workflow** | A single-file ESM bundle (\`.esm.js\`) that exports \`run\` and \`descriptor\`. Identified by name and XXH64 hash. |
+| **Bundle** | The physical \`.esm.js\` file stored in the bundles directory. Immutable once written. |
+| **Thread** | A single execution of a workflow, identified by a ULID. Persists state as JSONL files. |
+| **CAS** | Content-Addressable Storage. Per-thread key-value store keyed by content hash. |
+| **Registry** | \`workflow.yaml\` — maps workflow names to their current and historical bundle hashes. |
+
+## Commands
+
+### workflow
+
+| Command | Args | Description |
+|---------|------|-------------|
+| \`workflow add\` | \`<name> <file.esm.js> [--types <path>]\` | Register a workflow bundle in the registry |
+| \`workflow list\` | (none) | List all registered workflows |
+| \`workflow show\` | \`<name>\` | Show details of a registered workflow |
+| \`workflow rm\` | \`<name>\` | Remove a workflow from the registry |
+| \`workflow history\` | \`<name>\` | Show version history of a workflow |
+| \`workflow rollback\` | \`<name> [hash]\` | Rollback a workflow to a previous version |
+
+### thread
+
+| Command | Args | Description |
+|---------|------|-------------|
+| \`thread run\` | \`<name> [--prompt <text>] [--max-rounds N]\` | Start a new thread executing a workflow |
+| \`thread list\` | \`[name]\` | List threads, optionally filtered by workflow name |
+| \`thread show\` | \`<id>\` | Show thread details and state |
+| \`thread rm\` | \`<id>\` | Remove a thread |
+| \`thread fork\` | \`<thread-id> [--from-role <role>]\` | Fork a thread, optionally from a specific role |
+| \`thread ps\` | (none) | List running threads |
+| \`thread kill\` | \`<thread-id>\` | Kill a running thread |
+| \`thread live\` | \`<thread-id> [--debug] [--role <name>]\` or \`--latest [--debug] [--role <name>]\` | Attach to a thread and stream output live |
+| \`thread pause\` | \`<thread-id>\` | Pause a running thread |
+| \`thread resume\` | \`<thread-id>\` | Resume a paused thread |
+
+### cas
+
+| Command | Args | Description |
+|---------|------|-------------|
+| \`cas get\` | \`<thread-id> <hash>\` | Retrieve content by hash from a thread's CAS |
+| \`cas put\` | \`<thread-id> <content>\` | Store content in a thread's CAS, returns hash |
+| \`cas list\` | \`<thread-id>\` | List all CAS entries for a thread |
+| \`cas rm\` | \`<thread-id> <hash>\` | Remove a CAS entry |
+| \`cas gc\` | (none) | Garbage-collect unreferenced CAS entries |
+
+### init
+
+| Command | Args | Description |
+|---------|------|-------------|
+| \`init workspace\` | \`<name>\` | Initialize a new workflow workspace |
+| \`init template\` | \`<name>\` | Initialize a new workflow template |
+
+### Top-level shortcuts
+
+| Command | Equivalent | Description |
+|---------|------------|-------------|
+| \`run\` | \`thread run\` | Shortcut to start a thread |
+| \`live\` | \`thread live\` | Shortcut to attach to a thread |
+
+## Typical Workflow
+
+1. \`uncaged-workflow workflow add my-wf ./my-wf.esm.js\` — register a workflow
+2. \`uncaged-workflow run my-wf --prompt "do the thing"\` — start a thread
+3. \`uncaged-workflow live --latest\` — attach and watch output
+4. \`uncaged-workflow thread show <thread-id>\` — inspect completed thread
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| \`UNCAGED_WORKFLOW_STORAGE_ROOT\` | Override the default storage directory for all workflow data |
+`;
+}

packages/cli-workflow/src/storage-env.ts

@@ -1,10 +1,21 @@
 import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow";
 
-/** Resolve storage root, honoring `UNCAGED_WORKFLOW_STORAGE_ROOT` for tests/tools. */
+/**
+ * Resolve storage root with env var override support.
+ *
+ * Priority (highest first):
+ *  1. `UNCAGED_WORKFLOW_STORAGE_ROOT` — internal/test override
+ *  2. `WORKFLOW_STORAGE_ROOT` — user-facing override
+ *  3. Default (`~/.uncaged/workflow`)
+ */
 export function resolveWorkflowStorageRoot(): string {
-  const override = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-  if (override !== undefined && override !== "") {
-    return override;
+  const internal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+  if (internal !== undefined && internal !== "") {
+    return internal;
+  }
+  const userOverride = process.env.WORKFLOW_STORAGE_ROOT;
+  if (userOverride !== undefined && userOverride !== "") {
+    return userOverride;
   }
   return getDefaultWorkflowStorageRoot();
 }

packages/workflow-role-planner/src/planner.ts

@@ -36,6 +36,16 @@ Replace \`<THREAD_ID>\` with the actual thread ID you found above. The command p
 
 **Do NOT store phase details in any other way** (no temp files, no invented paths). The CLI command is the only supported storage mechanism.
 
+## Phase granularity
+
+Match the number of phases to task complexity:
+- Trivial (add a config option, fix a typo, rename): 1 phase
+- Small (a new feature touching 2-3 files): 1-2 phases
+- Medium (cross-module refactor): 2-3 phases
+- Large (new subsystem, architectural change): 3-5 phases
+
+Fewer phases is always better. Each phase must justify its existence — if two phases would be tested together anyway, merge them.
+
 ## Output format
 
 After storing all phases via the CLI, output compact JSON only:

packages/workflow/workflow

@@ -0,0 +1 @@
+/home/azureuser/repos/uncaged-workflow/packages/workflow