Document workspace-first agent automation (#2192)

* docs: explain workspace-first automation

* docs: make automation examples self-contained

public-docs/cli.md

@@ -1,6 +1,6 @@
 ---
 title: CLI
-description: "Paseo CLI reference: manage agents, daemons, permissions, and worktrees from your terminal."
+description: "Paseo CLI reference: manage agents, workspaces, schedules, daemons, and permissions from your terminal."
 nav: CLI
 order: 3
 category: Getting started
@@ -10,7 +10,7 @@ category: Getting started
 
 The Paseo CLI lets you manage agents from your terminal. It's the same interface exposed by the daemon's API, so anything you can do in the app you can do from the command line.
 
-> **Agent orchestration:** You can tell coding agents to use the Paseo CLI to spawn and manage other agents. This enables multi-agent workflows where one agent delegates subtasks to others and waits for results.
+> **Agent orchestration:** You can tell coding agents to use the Paseo CLI to spawn and manage other agents. Paseo recognizes the calling agent, so CLI-created workers get the same workspace and parent defaults as MCP-created workers.
 
 ## Quick reference
 
@@ -30,17 +30,59 @@ Use `paseo run` to start a new agent with a task:
 ```bash
 paseo run "implement user authentication"
 paseo run --provider codex "refactor the API layer"
-paseo run --detach "run the full test suite"  # background
-paseo run --worktree feature-x "implement feature X"
+paseo run --background "run the focused test suite"
+paseo run --isolation worktree --base main "implement feature X"
+paseo run --workspace <workspace-id> "review the current diff"
 paseo run --output-schema schema.json "extract release notes"
 paseo run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "summarize release notes"
 ```
 
-The `--worktree` flag creates the agent in an isolated git worktree, useful for parallel feature development.
+From a human shell, a bare `paseo run` creates a new local workspace for the current directory. Use `--workspace <id>` to add the agent to an existing workspace, or `--isolation worktree` to create a new workspace backed by an isolated git worktree.
 
-Use `--output-schema` to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with `--detach`.
+When an existing Paseo agent runs the same command, Paseo recognizes it through `PASEO_AGENT_ID`. Without explicit placement, the new agent becomes its subagent in the same workspace. `--workspace` can place that subagent elsewhere without changing its parent.
 
-By default, `paseo run` waits for completion. Use `--detach` to run in the background.
+Use `--output-schema` to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with `--background`.
+
+By default, `paseo run` waits for completion. Use `--background` to return immediately while the agent keeps running.
+
+## Workspaces
+
+Create a workspace independently when you want to prepare its files before starting an agent:
+
+```bash
+paseo workspace create --isolation local --path ~/dev/my-app --title main
+
+paseo workspace create \
+  --isolation worktree \
+  --path ~/dev/my-app \
+  --mode branch-off \
+  --new-branch feature/auth \
+  --worktree-slug feature-auth \
+  --base main
+
+paseo workspace create \
+  --isolation worktree \
+  --path ~/dev/my-app \
+  --mode checkout-branch \
+  --branch feature/existing \
+  --worktree-slug existing-copy
+
+paseo workspace create \
+  --isolation worktree \
+  --path ~/dev/my-app \
+  --mode checkout-pr \
+  --pr-number 2186
+```
+
+Then list, use, or archive it:
+
+```bash
+paseo workspace ls
+paseo run --workspace <workspace-id> "implement authentication"
+paseo workspace archive <workspace-id>
+```
+
+Add `--forge <name>` to PR checkout when Paseo cannot infer the forge from the source checkout. See [Git worktrees](/docs/worktrees) for setup hooks and services.
 
 ## Listing agents
 
@@ -93,7 +135,7 @@ Useful in scripts or when one agent needs to wait for another.
 
 ## Schedules
 
-Run an agent on an interval or a cron. See [Schedules from the CLI](/docs/schedules-cli) for the full reference.
+Run an agent on a cron schedule. The CLI also accepts simple cadence presets and compiles them to cron. See [Schedules from the CLI](/docs/schedules-cli) for the full reference.
 
 ```bash
 paseo schedule create --every 30m --cwd ~/dev/my-app "Continue the refactor and leave a note."
@@ -119,8 +161,11 @@ Change an agent's operational mode (provider-specific):
 paseo agent mode <id> --list   # Show available modes
 paseo agent mode <id> bypass   # Set bypass mode
 paseo agent mode <id> plan     # Set plan mode
+paseo agent detach <id>        # Make a subagent top-level
 ```
 
+Detaching is an explicit lifecycle action, not a creation flag. The agent keeps running; only its relationship to its parent changes.
+
 ## Daemon management
 
 ```bash
@@ -157,11 +202,13 @@ The CLI is designed to be used by agents themselves. You can instruct an agent t
 
 ```bash
 # Agent A spawns Agent B and waits for it
-paseo run --detach "implement the API" --name api-agent
-paseo wait api-agent
-paseo logs api-agent --tail 5
+agent_id=$(paseo run --background --quiet --title api-agent "implement the API")
+paseo wait "$agent_id"
+paseo logs "$agent_id" --tail 5
 ```
 
+Because Agent A's ID is present in the environment, Agent B is created as its subagent in the same workspace unless `--workspace` is specified.
+
 Simple implement + verify loop:
 
 ```bash