docs(cli): add deprecation handlers and update documentation (#463)

Complete the CLI refactoring with deprecation error handlers, updated
help text, and comprehensive migration guide.

## Changes

### Deprecation Handlers
Add error handlers for all removed commands with helpful migration messages:
- `workflow put` → suggests `workflow add`
- `thread step` → suggests `thread exec`
- `thread steps` → suggests `step list`
- `thread step-details` → suggests `step show`
- `thread fork` → suggests `step fork`
- `thread kill` → suggests `thread stop` or `thread cancel`
- `thread running` → suggests `thread list --status running`

Error messages follow the format:
```
Error: Command 'X' has been removed.
Use 'Y' instead.

For more information, see: uwf help Y
```

### Help Documentation
Updated CLI help text to explain four-layer architecture:
- Main help shows architecture diagram with Chinese labels
- Command group descriptions reference layers:
  - `workflow` → "Workflow definitions (layer 1: templates)"
  - `thread` → "Thread execution (layer 2: instances)"
  - `step` → "Step results (layer 3: single cycle)"
- Deprecated commands appear in help with [DEPRECATED] tag

### README Updates
Comprehensive documentation updates:
- Added "Four-Layer Architecture" section with diagram
- Updated all command tables with new command names
- Added complete migration guide with:
  - Renamed commands table
  - Merged commands table
  - Split commands table
  - Moved commands table
  - Example deprecation error output
- Updated "Internal Structure" to show new step.ts module

## Testing
- ✅ All 124 tests pass
- ✅ Build completes successfully
- ✅ Deprecation handlers tested manually
- ✅ Help output verified for main, thread, and step commands

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/cli-workflow/README.md

@@ -6,6 +6,18 @@
 
 Layer 4 entry point for the workflow engine. The `uwf` binary orchestrates one step per invocation: load thread head from `threads.yaml`, run the moderator, spawn the configured agent CLI, run extract, append a CAS step node, and update the head pointer (or archive when `$END`).
 
+### Four-Layer Architecture
+
+```
+workflow → thread → step → turn
+模板定义   执行实例   单步结果   agent内部交互
+```
+
+- **Workflow** (layer 1): YAML template with roles and routing graph
+- **Thread** (layer 2): Single workflow execution instance
+- **Step** (layer 3): One moderator→agent→extract cycle
+- **Turn** (layer 4): Agent-internal interactions (use `step read` or CAS to inspect)
+
 This package has no library `src/index.ts` — it is consumed as a CLI binary only.
 
 **Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-moderator`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `yaml`
@@ -30,34 +42,53 @@ bun link packages/cli-workflow
 -h, --help             Show help
 ```
 
-### Thread
+### Thread (Layer 2: Execution Instances)
 
 | Command | Description |
 |---------|-------------|
 | `uwf thread start <workflow> -p <prompt>` | Create a thread without executing |
-| `uwf thread step <thread-id> [--agent <cmd>] [-c <count>]` | Execute one or more moderator→agent→extract cycles |
+| `uwf thread exec <thread-id> [--agent <cmd>] [-c <count>] [--background]` | Execute one or more moderator→agent→extract cycles |
 | `uwf thread show <thread-id>` | Show thread head pointer |
-| `uwf thread list [--all]` | List active threads (`--all` includes archived) |
+| `uwf thread list [--status <idle\|running\|completed>]` | List threads, optionally filtered by status |
-| `uwf thread steps <thread-id>` | List all steps chronologically |
 | `uwf thread read <thread-id> [--quota N] [--before <hash>] [--start]` | Render thread as readable markdown |
-| `uwf thread fork <step-hash>` | Fork from a specific step |
+| `uwf thread stop <thread-id>` | Stop background execution (keep thread active) |
-| `uwf thread step-details <step-hash>` | Dump full detail node as YAML |
+| `uwf thread cancel <thread-id>` | Cancel thread (stop + archive to history) |
-| `uwf thread kill <thread-id>` | Terminate and archive |
 
 Examples:
 
 ```bash
 uwf thread start solve-issue -p "Fix the login redirect bug"
-uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV
+uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV
-uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
+uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
+uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV --background
+uwf thread list --status running
 uwf thread read 01ARZ3NDEKTSV4RRFFQ69G5FAV --quota 8000
+uwf thread stop 01ARZ3NDEKTSV4RRFFQ69G5FAV
 ```
 
-### Workflow
+### Step (Layer 3: Single Cycle Results)
 
 | Command | Description |
 |---------|-------------|
-| `uwf workflow put <file.yaml>` | Register a workflow from YAML |
+| `uwf step list <thread-id>` | List all steps in a thread chronologically |
+| `uwf step show <step-hash>` | Show step metadata and frontmatter |
+| `uwf step read <step-hash> [--before N]` | Read step output as markdown |
+| `uwf step fork <step-hash>` | Fork a thread from a specific step |
+
+Examples:
+
+```bash
+uwf step list 01ARZ3NDEKTSV4RRFFQ69G5FAV
+uwf step show 32GCDE899RRQ3
+uwf step read 32GCDE899RRQ3 --before 3
+uwf step fork 32GCDE899RRQ3
+```
+
+### Workflow (Layer 1: Templates)
+
+| Command | Description |
+|---------|-------------|
+| `uwf workflow add <file.yaml>` | Register a workflow from YAML |
 | `uwf workflow show <name-or-hash>` | Show workflow definition |
 | `uwf workflow list` | List registered workflows |
 
@@ -99,6 +130,52 @@ Config: `~/.uncaged/workflow/config.yaml`. API keys: `~/.uncaged/workflow/.env`.
 | `uwf log show [--thread <id>] [--process <pid>] [--date YYYY-MM-DD]` | Show filtered log entries |
 | `uwf log clean [--before YYYY-MM-DD]` | Delete old log files |
 
+## Migration Guide
+
+### Breaking Changes (v0.x → v1.x)
+
+The CLI was reorganized to clarify the four-layer architecture. **No backward compatibility** — old commands have been removed.
+
+#### Renamed Commands
+
+| Old Command | New Command | Notes |
+|------------|-------------|-------|
+| `workflow put` | `workflow add` | More intuitive verb |
+| `thread step` | `thread exec` | Eliminates ambiguity with "step" noun |
+| `thread list --all` | `thread list --status completed` | Unified status filtering |
+
+#### Removed Commands (Merged)
+
+| Old Command | New Command | Notes |
+|------------|-------------|-------|
+| `thread running` | `thread list --status running` | Merged into unified list |
+
+#### Removed Commands (Split)
+
+| Old Command | New Commands | Notes |
+|------------|-------------|-------|
+| `thread kill` | `thread stop` or `thread cancel` | `stop` keeps thread active, `cancel` archives it |
+
+#### Moved Commands
+
+| Old Command | New Command | Notes |
+|------------|-------------|-------|
+| `thread steps` | `step list` | Moved to step layer |
+| `thread step-details` | `step show` | Moved to step layer |
+| `thread fork` | `step fork` | Moved to step layer (forks are step-based) |
+
+#### Deprecation Errors
+
+Old commands now show helpful error messages:
+
+```bash
+$ uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV
+Error: Command 'thread step' has been removed.
+Use 'thread exec' instead.
+
+For more information, see: uwf help thread exec
+```
+
 ## Internal Structure
 
 ```
@@ -109,8 +186,9 @@ src/
 ├── validate.ts         Workflow YAML validation
 ├── schemas.ts          CLI-local schema registration
 └── commands/
-    ├── thread.ts       Thread lifecycle and step execution
+    ├── thread.ts       Thread lifecycle and exec
-    ├── workflow.ts     Workflow registry (put/show/list)
+    ├── step.ts         Step operations (list/show/read/fork)
+    ├── workflow.ts     Workflow registry (add/show/list)
     ├── cas.ts          CAS inspection and schema ops
     ├── setup.ts        Interactive/non-interactive setup
     ├── skill.ts        Built-in skill references

packages/cli-workflow/src/cli.ts

@@ -52,11 +52,18 @@ const program = new Command();
 const pkg = await import("../package.json", { with: { type: "json" } });
 program
   .name("uwf")
-  .description("Stateless workflow CLI")
+  .description(
+    "Stateless workflow CLI\n\n" +
+      "Four-layer architecture:\n" +
+      "  workflow → thread → step → turn\n" +
+      "  模板定义   执行实例   单步结果   agent内部交互",
+  )
   .version(pkg.default.version, "-V, --version");
 program.option("--format <fmt>", "Output format: json or yaml", "json");
 
-const workflow = program.command("workflow").description("Workflow registry and CAS");
+const workflow = program
+  .command("workflow")
+  .description("Workflow definitions (layer 1: templates)");
 
 workflow
   .command("add")
@@ -93,7 +100,9 @@ workflow
     });
   });
 
-const thread = program.command("thread").description("Thread lifecycle and execution");
+const thread = program
+  .command("thread")
+  .description("Thread execution (layer 2: instances)");
 
 thread
   .command("start")
@@ -240,7 +249,7 @@ thread
     },
   );
 
-const step = program.command("step").description("Step operations");
+const step = program.command("step").description("Step results (layer 3: single cycle)");
 
 step
   .command("list")
@@ -292,6 +301,103 @@ step
     });
   });
 
+// ── Deprecation Handlers ──────────────────────────────────────────────────────
+// These commands have been removed. Show helpful error messages.
+
+workflow
+  .command("put")
+  .description("[DEPRECATED] Use 'workflow add' instead")
+  .argument("<file>", "Workflow YAML file")
+  .action(() => {
+    process.stderr.write(`Error: Command 'workflow put' has been removed.
+Use 'workflow add' instead.
+
+For more information, see: uwf help workflow add
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("step")
+  .description("[DEPRECATED] Use 'thread exec' instead")
+  .argument("<thread-id>", "Thread ULID")
+  .allowUnknownOption()
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread step' has been removed.
+Use 'thread exec' instead.
+
+For more information, see: uwf help thread exec
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("steps")
+  .description("[DEPRECATED] Use 'step list' instead")
+  .argument("<thread-id>", "Thread ULID")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread steps' has been removed.
+Use 'step list' instead.
+
+For more information, see: uwf help step list
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("step-details")
+  .description("[DEPRECATED] Use 'step show' instead")
+  .argument("<step-hash>", "Step hash")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread step-details' has been removed.
+Use 'step show' instead.
+
+For more information, see: uwf help step show
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("fork")
+  .description("[DEPRECATED] Use 'step fork' instead")
+  .argument("<step-hash>", "Step hash")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread fork' has been removed.
+Use 'step fork' instead.
+
+For more information, see: uwf help step fork
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("kill")
+  .description("[DEPRECATED] Use 'thread stop' or 'thread cancel' instead")
+  .argument("<thread-id>", "Thread ULID")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread kill' has been removed.
+Use 'thread stop' to stop background execution (keep thread active),
+or 'thread cancel' to cancel and archive the thread.
+
+For more information, see:
+  uwf help thread stop
+  uwf help thread cancel
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("running")
+  .description("[DEPRECATED] Use 'thread list --status running' instead")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread running' has been removed.
+Use 'thread list --status running' instead.
+
+For more information, see: uwf help thread list
+`);
+    process.exit(1);
+  });
+
 const skill = program.command("skill").description("Built-in skill references for agents");
 
 skill