docs: add CLI reference and How it works to Readme

README.md

@@ -118,6 +118,79 @@ opencode-multi-model open my-session -m openai/gpt-5.2 -b kilo
 
 Priority: CLI flag > Environment variable > Default ("opencode")
 
+## CLI Reference
+
+### `open` - Create a new multi-model tmux session
+
+```bash
+opencode-multi-model open <session-name> [options]
+```
+
+**Arguments:**
+- `<session-name>` - Name for the tmux session (required)
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-m, --models <models...>` | Model IDs to launch (space-separated) |
+| `-b, --binary <binary>` | Binary to use (opencode or kilo). Defaults to env var `OPENCODE_MULTI_MODEL_BINARY` or 'opencode' |
+
+### `close` - Close a multi-model tmux session
+
+```bash
+opencode-multi-model close <session-name> [options]
+```
+
+**Arguments:**
+- `<session-name>` - Name of the tmux session to close (required)
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--keep-worktrees` | Do not remove worktrees and delete branches |
+| `--no-tags` | Do not create archive tags before deleting branches |
+| `-f, --force` | Skip confirmation prompts |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-h, --help` | Display help information |
+| `-V, --version` | Display version number |
+
+## How it works
+
+### `open` command
+
+The `open` command performs the following steps:
+
+1. **Validation**: Checks that session name andmodels are provided, no duplicate models exist, and verifies git repo, tmux, and binary are available
+
+2. **Model verification**: Validates models against `opencode models` output to ensure only valid model IDs are used
+
+3. **Git worktree creation**: For each model, creates:
+   - A git worktree at `~/.local/share/opencode/multi-model/<session>/<model>/`
+   - A branch named `opencode/<session>/<model>`
+
+4. **Tmux session**: Creates a tmux session with one window per model, each window's working directory set to its corresponding worktree
+
+5. **Launch**: Sends the launch command to each window to start the binary with the specified model
+
+### `close` command
+
+The `close` command performs the following steps:
+
+1. **Kill tmux session**: Terminates the tmux session if it exists
+
+2. **Worktree discovery**: Finds all worktrees under `~/.local/share/opencode/multi-model/<session>/`
+
+3. **Worktree cleanup** (unless `--keep-worktrees`):
+   - Removes each gitworktree
+   - Creates an archive tag (unless `--no-tags`): `archive/<branch>-<timestamp>` for recovery
+   - Deletes the associated branches
+
+4. **Directory cleanup**: Removes the base session directory
+
 ## Requirements
 
 - tmux