diff --git a/README.md b/README.md
index 4ef3dba..566e9f3 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,8 @@ https://raw.githubusercontent.com/DanHenton/opencode-worktree/main/docs/install.
 
 For other install methods (Go, manual download, PATH troubleshooting), see the [full install guide](docs/install.md).
 
+For command-by-command behavior, examples, and edge cases, see the [command reference](docs/commands/README.md).
+
 ## Usage
 
 > **Shortcut:** The installer adds `ocwt` as a shell alias for `opencode-worktree` — use either interchangeably.
diff --git a/docs/commands/README.md b/docs/commands/README.md
new file mode 100644
index 0000000..4bdc18f
--- /dev/null
+++ b/docs/commands/README.md
@@ -0,0 +1,20 @@
+# Command Reference
+
+Command-level reference for `opencode-worktree`. Each page follows the same structure so a human or an agent can understand behavior, inputs, and edge cases without reading the Go code.
+
+## Commands
+
+- [`task`](task.md) — create a new agent worktree and launch OpenCode
+- [`attach`](attach.md) — reopen an existing agent worktree session
+- [`merge`](merge.md) — merge an agent branch back into its parent branch
+- [`sync`](sync.md) — rebase an agent branch onto the latest parent branch
+- [`list`](list.md) — show active agent worktrees
+- [`cleanup`](cleanup.md) — remove orphaned worktrees and stale agent branches
+
+## Shared conventions
+
+- Agent branches are named `agent/<task-name>`.
+- Agent worktrees are created as sibling directories named `<repo>-agent-<task-name>`.
+- Managed worktrees contain `.agent-parent-branch` and `.agent-context` marker files.
+- The installer adds `ocwt` as a shell alias for `opencode-worktree`.
+- Run `opencode-worktree <command> --help` for built-in CLI help.
diff --git a/docs/commands/attach.md b/docs/commands/attach.md
new file mode 100644
index 0000000..4ca8986
--- /dev/null
+++ b/docs/commands/attach.md
@@ -0,0 +1,60 @@
+# `opencode-worktree attach`
+
+## Summary
+
+Reopens an existing agent worktree session by task name, launches OpenCode inside that worktree again, and by default merges the branch when the session exits.
+
+## Usage
+
+```bash
+opencode-worktree attach <name> [--no-merge]
+```
+
+## Arguments
+
+- `<name>` — required task name for an already-existing agent worktree.
+
+## Options
+
+- `--no-merge` — skip the automatic merge step after the OpenCode session ends.
+
+## What it does
+
+1. Confirms you are inside the source git repository.
+2. Finds the active worktree that matches `agent/<name>`.
+3. Launches `opencode` inside that worktree.
+4. Unless `--no-merge` is set, runs the same merge-and-cleanup flow used by `task`.
+
+## When to use it
+
+Use `attach` when a task already has a live worktree and you want to continue that session instead of creating a second worktree.
+
+## Examples
+
+```bash
+# Reopen an existing session
+opencode-worktree attach fix-auth-bug
+
+# Reopen without auto-merging on exit
+opencode-worktree attach fix-auth-bug --no-merge
+```
+
+## Important behavior
+
+- `attach` does not create a branch or worktree. It only reconnects to one that already exists.
+- Task lookup is based on active git worktree metadata, not directory name guessing.
+- If the named task does not exist, the command exits with an error.
+- The same merge rules as `task` apply after OpenCode exits.
+
+## Common failure cases
+
+- Not inside the source git repository.
+- No active worktree exists for the requested task name.
+- Missing `opencode` binary.
+- Merge conflicts during auto-merge.
+
+## Related commands
+
+- [`task`](task.md) to create a new session.
+- [`list`](list.md) to discover active task names.
+- [`merge`](merge.md) to merge manually later.
diff --git a/docs/commands/cleanup.md b/docs/commands/cleanup.md
new file mode 100644
index 0000000..3c6ab6d
--- /dev/null
+++ b/docs/commands/cleanup.md
@@ -0,0 +1,61 @@
+# `opencode-worktree cleanup`
+
+## Summary
+
+Removes orphaned agent worktree directories and stale `agent/*` branches that no longer correspond to an active git worktree.
+
+## Usage
+
+```bash
+opencode-worktree cleanup [--dry-run] [--yes]
+```
+
+## Arguments
+
+This command does not take positional arguments.
+
+## Options
+
+- `--dry-run` — show what would be removed without deleting anything.
+- `--yes` — skip the confirmation prompt.
+
+## What it does
+
+1. Prunes stale git worktree metadata.
+2. Scans sibling directories for names matching the tool's worktree naming pattern.
+3. Compares those directories against active git worktrees and marks unmatched ones as orphaned.
+4. Scans local branches for `agent/*` branches that are no longer attached to an active worktree.
+5. In normal mode, prompts for confirmation when running interactively unless `--yes` is set.
+6. Removes orphaned directories and attempts to delete orphaned branches.
+
+## When to use it
+
+Use `cleanup` when a worktree directory or agent branch is left behind after manual interruption, failed cleanup, or other unexpected session endings.
+
+## Examples
+
+```bash
+# Review what would be removed
+opencode-worktree cleanup --dry-run
+
+# Remove orphaned items without an interactive prompt
+opencode-worktree cleanup --yes
+```
+
+## Important behavior
+
+- Active worktree directories and active `agent/*` branches are preserved.
+- In `--dry-run` mode, nothing is removed.
+- Without `--yes`, interactive terminals get a confirmation prompt.
+- If a stale branch cannot be deleted because it is unmerged, the command leaves it in place and prints the `git branch -D` command to force deletion manually.
+
+## Common failure cases
+
+- Running outside a git repository.
+- File-system permission failures while removing directories.
+- Branch deletion blocked because the branch is not fully merged.
+
+## Related commands
+
+- [`list`](list.md) to inspect active sessions before cleaning.
+- [`merge`](merge.md) if a worktree is still valid and should be merged instead of deleted.
diff --git a/docs/commands/list.md b/docs/commands/list.md
new file mode 100644
index 0000000..98eb366
--- /dev/null
+++ b/docs/commands/list.md
@@ -0,0 +1,51 @@
+# `opencode-worktree list`
+
+## Summary
+
+Shows active managed agent worktrees for the current repository.
+
+## Usage
+
+```bash
+opencode-worktree list
+```
+
+## Arguments
+
+This command does not take positional arguments.
+
+## Options
+
+This command has no flags.
+
+## What it does
+
+1. Confirms you are inside a git repository.
+2. Reads `git worktree list` output for the repository.
+3. Filters the result down to worktrees whose branch name starts with `agent/`.
+4. Marks entries with `(uncommitted changes)` when the worktree contains changes outside the tool's marker/config files.
+
+## When to use it
+
+Use `list` to see which agent sessions are still active and to find task names you can pass to `attach`.
+
+## Examples
+
+```bash
+opencode-worktree list
+```
+
+## Important behavior
+
+- If no managed agent worktrees exist, the command prints `(none)`.
+- The output is informational and does not modify anything.
+- Dirty-state detection ignores `.agent-parent-branch`, `.agent-context`, `opencode.json`, and `.opencode/`.
+
+## Common failure cases
+
+- Running outside a git repository.
+
+## Related commands
+
+- [`attach`](attach.md) to reopen a listed session.
+- [`cleanup`](cleanup.md) to remove stale sessions that are no longer active.
diff --git a/docs/commands/merge.md b/docs/commands/merge.md
new file mode 100644
index 0000000..aebc91c
--- /dev/null
+++ b/docs/commands/merge.md
@@ -0,0 +1,68 @@
+# `opencode-worktree merge`
+
+## Summary
+
+Merges an agent branch back into its recorded parent branch and optionally removes the agent worktree and branch afterward.
+
+## Usage
+
+```bash
+opencode-worktree merge [path] [--no-cleanup]
+```
+
+## Arguments
+
+- `[path]` — optional path to an agent worktree. If omitted, the command tries to detect the current directory as a managed agent worktree.
+
+## Options
+
+- `--no-cleanup` — keep the worktree and branch after a successful merge.
+
+## What it does
+
+1. Resolves the target worktree path, either from the argument or by auto-detecting the current directory.
+2. Reads `.agent-parent-branch` to find the branch the agent work should merge back into.
+3. Confirms the current worktree branch starts with `agent/`.
+4. Counts commits that exist on the agent branch but not the parent branch.
+5. Checks whether the worktree has uncommitted changes, excluding marker and copied config files.
+6. Takes a file lock before switching the main repo to the parent branch and merging, so concurrent merges do not race.
+7. On success, optionally removes the worktree, deletes the agent branch, and prunes stale worktree metadata.
+
+## When to use it
+
+Use `merge` when you skipped auto-merge, when you want to merge from a specific worktree manually, or when you need to retry after resolving issues.
+
+## Examples
+
+```bash
+# Merge from the current agent worktree
+opencode-worktree merge
+
+# Merge a specific worktree from anywhere
+opencode-worktree merge /path/to/worktree
+
+# Merge but keep the worktree and branch around
+opencode-worktree merge --no-cleanup
+```
+
+## Important behavior
+
+- If the worktree has no new commits, the command skips the merge itself.
+- If there are no new commits and no uncommitted changes, cleanup still happens by default.
+- If the worktree has uncommitted changes, the worktree is preserved even when cleanup is enabled.
+- Merge conflicts are detected, the merge is aborted automatically, and conflicting files are listed.
+- The command only works for managed agent worktrees that contain `.agent-parent-branch` and are on an `agent/*` branch.
+
+## Common failure cases
+
+- Running without a path from a directory that is not an agent worktree.
+- Missing `.agent-parent-branch` marker.
+- Worktree is on a non-agent branch.
+- Merge conflicts between the parent branch and the agent branch.
+- Cleanup failing after a successful merge.
+
+## Related commands
+
+- [`task`](task.md) and [`attach`](attach.md) for auto-merge on exit.
+- [`sync`](sync.md) to rebase the agent branch onto the latest parent branch before merging.
+- [`cleanup`](cleanup.md) to remove leftover worktrees or branches later.
diff --git a/docs/commands/sync.md b/docs/commands/sync.md
new file mode 100644
index 0000000..79c277e
--- /dev/null
+++ b/docs/commands/sync.md
@@ -0,0 +1,63 @@
+# `opencode-worktree sync`
+
+## Summary
+
+Rebases an agent branch onto the latest version of its parent branch so the worktree picks up upstream changes before merge time.
+
+## Usage
+
+```bash
+opencode-worktree sync [path]
+```
+
+## Arguments
+
+- `[path]` — optional path to an agent worktree. If omitted, the command tries to detect the current directory as a managed agent worktree.
+
+## Options
+
+This command has no flags.
+
+## What it does
+
+1. Resolves the target worktree path, either from the argument or by auto-detecting the current directory.
+2. Reads `.agent-parent-branch` to determine which parent branch to sync against.
+3. Confirms the worktree is on an `agent/*` branch.
+4. Refuses to continue if the worktree has uncommitted changes.
+5. Checks whether the parent branch has moved ahead of the branch point.
+6. If needed, rebases the agent branch onto the parent branch.
+7. If a conflict occurs, aborts the rebase and reports the conflicting files.
+
+## When to use it
+
+Use `sync` when the parent branch has new commits and you want to integrate them into the agent worktree before finishing or merging.
+
+## Examples
+
+```bash
+# Sync from inside an agent worktree
+opencode-worktree sync
+
+# Sync a specific worktree from anywhere
+opencode-worktree sync /path/to/worktree
+```
+
+## Important behavior
+
+- If the parent branch has no new commits, the command reports that the worktree is already up to date.
+- `sync` is stricter than `merge`: it refuses to run if the worktree has uncommitted changes.
+- Rebase conflicts are aborted automatically so the worktree is not left mid-rebase.
+- The command only works for managed agent worktrees with a valid `.agent-parent-branch` marker.
+
+## Common failure cases
+
+- Running without a path from a directory that is not an agent worktree.
+- Missing or empty `.agent-parent-branch` marker.
+- Worktree is dirty.
+- Worktree is on a non-agent branch.
+- Rebase conflicts while replaying agent commits onto the parent branch.
+
+## Related commands
+
+- [`merge`](merge.md) to finish the session after syncing.
+- [`task`](task.md) to start a new synced-off-current-branch session.
diff --git a/docs/commands/task.md b/docs/commands/task.md
new file mode 100644
index 0000000..78fd0d2
--- /dev/null
+++ b/docs/commands/task.md
@@ -0,0 +1,71 @@
+# `opencode-worktree task`
+
+## Summary
+
+Creates a new agent worktree from your current branch, launches OpenCode inside it, and by default merges the finished work back into the parent branch when OpenCode exits.
+
+## Usage
+
+```bash
+opencode-worktree task <name> [message] [--no-merge]
+```
+
+## Arguments
+
+- `<name>` — required task name used for both the branch and sibling worktree directory. Only letters, numbers, and hyphens are allowed.
+- `[message]` — optional initial prompt passed to `opencode --prompt`.
+
+## Options
+
+- `--no-merge` — skip the automatic merge step after the OpenCode session ends.
+
+## What it does
+
+1. Confirms you are inside a git repository and currently on a named branch.
+2. Validates the task name and rejects duplicates if a matching agent worktree already exists.
+3. Creates a new branch named `agent/<name>`.
+4. Creates a sibling worktree at `<repo-dir>-agent-<name>`.
+5. Writes `.agent-parent-branch` and `.agent-context` marker files into the worktree.
+6. Copies `opencode.json` and `.opencode/` into the worktree if they exist in the source repo.
+7. Launches `opencode` in the new worktree.
+8. Unless `--no-merge` is set, attempts to merge the agent branch back into the parent branch and clean up.
+
+## When to use it
+
+Use `task` when you want to start a brand-new isolated agent session for a piece of work.
+
+## Examples
+
+```bash
+# Start a new isolated session
+opencode-worktree task fix-auth-bug
+
+# Start a session with an initial prompt
+opencode-worktree task fix-auth-bug "Fix the JWT token expiry bug"
+
+# Keep the worktree and merge manually later
+opencode-worktree task add-dark-mode --no-merge
+```
+
+## Important behavior
+
+- If `opencode` is not installed or not on your `PATH`, launch fails.
+- Task names cannot contain spaces, underscores, slashes, or special characters.
+- If a worktree already exists for the same task name, the command stops instead of reusing it.
+- Automatic merge happens only after the OpenCode process exits.
+- If there are no new commits, the merge step skips the merge itself and only cleans up.
+- If the worktree still has uncommitted changes, the merge result is preserved and the worktree is kept.
+
+## Common failure cases
+
+- Not inside a git repository.
+- Running from detached `HEAD` instead of a named branch.
+- Reusing an existing task name.
+- Missing `opencode` binary.
+- Merge conflicts during auto-merge.
+
+## Related commands
+
+- [`attach`](attach.md) to reopen an existing session.
+- [`merge`](merge.md) to merge later when `--no-merge` was used.
+- [`list`](list.md) to see active sessions.
diff --git a/docs/install.md b/docs/install.md
index 8876d51..c3751ff 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -166,7 +166,7 @@ command -v opencode-worktree
 opencode-worktree --help
 ```
 
-This should display the available subcommands: `task`, `merge`, `list`, `cleanup`.
+This should display the available subcommands: `task`, `attach`, `merge`, `sync`, `list`, `cleanup`.
 
 ### Step 5: Confirm with user