Replace API reference with CLI documentation in README

Signed-off-by: Cong Wang <cwang@multikernel.io>

Author: congwang-mk

README.md

@@ -268,124 +268,82 @@ Any agent pattern can also opt into process isolation:
 outcome = Speculate(candidates, isolate_processes=True, timeout=60)(ws)
 ```
 
-## How it works
+## CLI
 
-BranchContext uses copy-on-write filesystems to create instant, zero-cost
-branches of your workspace. Two backends are supported, auto-detected at
-runtime:
+The `branching` command exposes the agent patterns as shell commands.
+Auto-detects the workspace from your current directory, or pass `-w PATH`.
+All commands support `--json` for machine-readable output.
 
-| Backend | How branches work |
-|---|---|
-| **[BranchFS](https://github.com/multikernel/branchfs)** (FUSE) | Single mount; branches are virtual paths within it. First-winner-commit semantics. |
-| **[DaxFS](https://github.com/multikernel/daxfs)** (kernel) | Separate mount per branch. Fastest option for DAX-capable storage. |
+### run
 
-You just create a `Workspace` pointed at a mounted path - the backend is
-detected automatically.
+Run a command in a new branch. Commits on exit 0, aborts on non-zero.
 
-Process isolation (`BranchContext`) uses unprivileged Linux user namespaces
-to give each child its own filesystem view. No root required - works on any
-Linux distribution with `unprivileged_userns_clone=1` (the default).
+```bash
+branching run -- ./build.sh
+branching run --on-error none -- python train.py
+branching run --ask -- make test          # prompt before commit/abort
+```
 
-## API reference
+### speculate
 
-The library has three layers. Imports are lazy - only the layer you use
-gets loaded.
+Race N commands in parallel branches. First success wins.
 
-```python
-from branching import Workspace      # FS layer only
-from branching import BranchContext  # process layer only
-from branching import Speculate      # agent layer (+ FS layer)
+```bash
+branching speculate -c "./fix_a.sh" -c "./fix_b.sh" -c "./fix_c.sh"
+branching speculate --timeout 60 -c "python solve_v1.py" -c "python solve_v2.py"
 ```
 
-### Workspace and Branch
+### best-of-n
 
-**`Workspace(path)`** - open a workspace from an existing mount.
+Run CMD N times in parallel, commit the highest-scoring success.
 
-| Property / Method | Description |
-|---|---|
-| `.path` | Mount root path |
-| `.fstype` | Detected backend (`"branchfs"` or `"daxfs"`) |
-| `.branch(name, on_success="commit", on_error="abort")` | Create a branch (returns `Branch` context manager) |
-
-**`Branch`** - context manager for an isolated workspace view.
+The child process can write a score to fd 3 (`echo 0.95 >&3`).
+If nothing is written, score defaults to 1.0 for success / 0.0 for failure.
+Each child receives `BRANCHING_ATTEMPT` (0-indexed) in its environment.
 
-| Property / Method | Description |
-|---|---|
-| `.name` | Branch name |
-| `.path` | Working directory for this branch |
-| `.branch_path` | Full path (e.g. `"/main/feature"`) |
-| `.branch(name, ...)` | Create a nested child branch |
-| `.commit()` | Merge changes into parent |
-| `.abort()` | Roll back to parent |
+```bash
+branching best-of-n -n 5 -- ./solve.py
+branching best-of-n -n 3 --timeout 120 --json -- python attempt.py
+branching best-of-n -n 3 -- bash -c 'python run.py && echo "$SCORE" >&3'
+```
 
-`on_success` accepts `"commit"` or `None`.
-`on_error` accepts `"abort"` or `None`.
+### reflexion
 
-### BranchContext (process isolation)
+Sequential retry with optional critique feedback loop.
 
-**`BranchContext(target, workspace, *, close_fds=False)`** - run a function
-in a sandboxed child process.
+The child receives `BRANCHING_ATTEMPT` (0-indexed) and `BRANCHING_FEEDBACK`
+(empty on first attempt, critique output on retries) in its environment.
 
-| Property / Method | Description |
-|---|---|
-| `target` | `Callable[[Path], None]` - return normally for success, raise for failure |
-| `workspace` | Directory to bind-mount into the child |
-| `.pid` | Child PID |
-| `.alive` | Whether the child is still running |
-| `.wait(timeout=None)` | Block until exit; raises `ProcessBranchError` on failure, `TimeoutError` on timeout |
-| `.abort(timeout=5.0)` | Abort child and all its descendants |
-
-**`BranchContext.create(targets, workspaces, *, close_fds=False)`** - fork N
-children at once; cleans up all on exit.
+```bash
+branching reflexion --retries 5 -- ./fix.sh
+branching reflexion --retries 3 --critique "./review.sh" -- ./solve.py
+branching reflexion --retries 3 --critique "python critique.py" --json -- python agent.py
+```
 
-### Agent patterns
+### status
 
-All patterns: instantiate with config, call with a `Workspace`, get a
-`SpeculationOutcome`.
+Show workspace info and active branches.
 
-| Pattern | Constructor | What it does |
-|---|---|---|
-| **`Speculate`** | `(candidates, *, first_wins=True, max_parallel=None, isolate_processes=False, timeout=None)` | Run candidates in parallel; first success wins |
-| **`BestOfN`** | `(task, n=3, *, timeout=None)` | Run N copies; commit highest-scoring success |
-| **`Reflexion`** | `(task, max_retries=3, *, critique=None)` | Retry with critique feedback loop |
-| **`TreeOfThoughts`** | `(strategies, *, evaluate=None, expand=None, max_depth=1, timeout=None)` | Parallel strategy tree with optional depth expansion |
-| **`BeamSearch`** | `(strategies, *, expand, evaluate=None, beam_width=3, max_depth=2, timeout=None)` | Multi-level beam search; top-K branches survive each depth |
-| **`Tournament`** | `(task, n=4, *, judge, timeout=None)` | Generate N candidates; pairwise elimination picks winner |
+```bash
+branching status
+branching status --json
+```
 
-### Result types
+## How it works
 
-**`SpeculationOutcome`** - returned by all agent patterns.
+BranchContext uses copy-on-write filesystems to create instant, zero-cost
+branches of your workspace. Two backends are supported, auto-detected at
+runtime:
 
-| Field | Description |
+| Backend | How branches work |
 |---|---|
-| `.committed` | Whether a winner was committed |
-| `.winner` | `SpeculationResult` or `None` |
-| `.all_results` | All candidate results |
-
-**`SpeculationResult`** - one candidate's outcome.
+| **[BranchFS](https://github.com/multikernel/branchfs)** (FUSE) | Single mount; branches are virtual paths within it. First-winner-commit semantics. |
+| **[DaxFS](https://github.com/multikernel/daxfs)** (kernel) | Separate mount per branch. Fastest option for DAX-capable storage. |
 
-| Field | Description |
-|---|---|
-| `.branch_index` | Candidate index |
-| `.success` | Whether the candidate succeeded |
-| `.score` | Quality score (default 0.0) |
-| `.return_value` | Raw return value |
-| `.exception` | Exception if failed, else `None` |
-| `.branch_path` | Working directory used |
+You just create a `Workspace` pointed at a mounted path - the backend is
+detected automatically.
 
-### Exceptions
+Process isolation (`BranchContext`) uses unprivileged Linux user namespaces
+to give each child its own filesystem view. No root required - works on any
+Linux distribution with `unprivileged_userns_clone=1` (the default).
 
-```
-BranchingError                  # base for all errors
-├── MountError                  # filesystem mount/unmount failed
-├── BranchError                 # branch operation failed
-│   ├── BranchStaleError        # a sibling branch was already committed
-│   ├── BranchNotFoundError     # branch does not exist
-│   ├── CommitError             # commit failed
-│   │   └── ConflictError       # another branch already committed
-│   └── AbortError              # abort failed
-├── ProcessBranchError          # sandboxed child process failed
-│   ├── ForkError               # fork() failed
-│   └── NamespaceError          # sandbox setup failed
-└── MemoryBranchError           # memory branching failed
-```