Add screenshot and comprehensive usage docs to README

.changeset/add-readme-usage-docs.md

@@ -0,0 +1,5 @@
+---
+"git-work-grove": patch
+---
+
+Add screenshot and comprehensive usage documentation to README

CLAUDE.md

@@ -36,6 +36,16 @@ Design specs live in `docs/spec/`. These are the **source of truth** for how fea
 
 With favorites, these become 8 item types (4 normal + 4 favorite). Never conflate repository workspace with worktree workspace — they have different available template variables and may display different information.
 
+## Documentation Maintenance
+
+When modifying features or behavior, **always update the corresponding documentation in the same work session**:
+
+- **README.md** — Update the Usage, Settings, Commands, or Features sections if user-facing behavior changes
+- **docs/templates.md** — Update if template variables, syntax, or defaults change
+- **docs/spec/*.md** — Update the relevant spec (per Spec Maintenance Rules above)
+
+All three layers (README, user docs, specs) must stay in sync with the code.
+
 ## Code Conventions
 
 - **ESLint**: Uses `@antfu/eslint-config` with `perfectionist/sort-named-imports` — named imports MUST be alphabetically sorted

README.md

@@ -4,6 +4,8 @@
 
 Git WorkGrove provides first-class `.code-workspace` support for git worktrees. It appears in the Source Control view, letting you browse worktrees and directly open their workspace files.
 
+![Git WorkGrove tree view](https://raw.githubusercontent.com/vp-tw/vscode-extension-git-work-grove/main/docs/images/screenshot.png)
+
 ## Why This Extension Exists
 
 Git worktrees are powerful for parallel development — but VS Code and its extensions don't handle `.code-workspace` files well in worktree workflows.
@@ -37,15 +39,109 @@ If VS Code or GitLens ever ships proper `.code-workspace` support for worktrees,
 - **Prune** — Clean up stale worktree records
 - **Live updates** — FileSystemWatcher detects worktree changes automatically
 
+## Usage
+
+### Tree View
+
+Git WorkGrove adds a **WORKGROVE** panel in the Source Control sidebar. It shows:
+
+1. **Favorites** — Pinned items at the top (if any exist)
+2. **Repository** — The main worktree (collapsible, with workspace files as children)
+3. **Linked worktrees** — All other worktrees (alphabetically sorted, each with workspace files)
+
+Click a workspace file to open it. Click a worktree to expand/collapse its children.
+
+### Context Menu (Right-Click)
+
+Right-click any item in the tree to access:
+
+| Action | Description |
+|--------|-------------|
+| **Open in New Window** | Opens the worktree or workspace file in a new VS Code window |
+| **Open in Current Window** | Opens in the current VS Code window |
+| **Reveal in Finder** | Opens the item's location in your OS file manager |
+
+Favorite-specific actions appear as inline buttons:
+
+| Button | Description |
+|--------|-------------|
+| **Add Favorite** (star outline) | Pin this item to the Favorites section |
+| **Remove Favorite** (filled star) | Unpin from Favorites |
+| **Move Up / Move Down** (chevrons) | Reorder within Favorites |
+
+You can also drag and drop favorites to reorder them.
+
+### View Title Actions
+
+The WORKGROVE panel header provides:
+
+| Action | Location | Description |
+|--------|----------|-------------|
+| **Refresh** | Header icon | Re-scan worktrees and workspace files |
+| **Prune Worktrees** | `...` overflow menu | Run `git worktree prune` to clean up stale records |
+| **Clean Stale Favorites** | `...` overflow menu | Remove favorites that no longer exist on disk |
+| **Show Output** | Command Palette | Open the Git WorkGrove output channel for debugging |
+
+### Open Behavior
+
+When you click a workspace file, the behavior depends on the `openBehavior` setting:
+
+- **`ask`** (default) — Shows a picker with options: _Open in New Window_, _Open in Current Window_, plus "Always" variants that persist your choice
+- **`newWindow`** — Always opens in a new window
+- **`currentWindow`** — Always opens in the current window
+
+### Current Indicator
+
+The currently open workspace or worktree is highlighted with:
+
+- A **green-tinted icon**
+- A **green dot badge** (●)
+
+Clicking the current item does nothing (it's already open).
+
 ## Settings
 
+Open VS Code Settings (`Cmd+,` / `Ctrl+,`) and search for `git-work-grove`:
+
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `git-work-grove.openBehavior` | `ask` \| `newWindow` \| `currentWindow` | `ask` | Default action when opening a workspace |
 | `git-work-grove.workspaceFile.include` | `string[]` | `["*.code-workspace"]` | Glob patterns for workspace file scanning |
 | `git-work-grove.workspaceFile.exclude` | `string[]` | `[]` | Glob patterns to exclude from scanning |
 | `git-work-grove.template.*` | `string` | *(varies)* | Display templates — see [Template Customization](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/templates.md) |
-| `git-work-grove.favorites` | `string[]` | `[]` | Ordered list of favorited item paths |
+| `git-work-grove.favorites` | `string[]` | `[]` | Ordered list of favorited item paths (managed via the UI) |
+
+### Template Customization
+
+All tree item labels and descriptions are customizable. Templates support variables like `{name}`, `{branch}`, `{ref}`, fallback syntax (`{branch|detached}`), and conditional sections (`{?branch}({branch}){/branch}`).
+
+See [Template Customization](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/templates.md) for all 8 item types, available variables, and examples.
+
+## Commands
+
+All commands use the `Git WorkGrove:` prefix. Some are available via the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), while others appear only in the tree view context menu or inline buttons.
+
+### Command Palette
+
+| Command | Description |
+|---------|-------------|
+| Refresh | Re-scan worktrees and workspace files |
+| Prune Worktrees | Run `git worktree prune` to clean up stale records |
+| Show Output | Open the extension's output channel for debugging |
+| Clean Stale Favorites | Remove favorites pointing to deleted items |
+
+### Context Menu Only
+
+These commands appear when right-clicking items in the tree view:
+
+| Command | Description |
+|---------|-------------|
+| Open in New Window | Open worktree or workspace file in a new VS Code window |
+| Open in Current Window | Open in the current VS Code window |
+| Reveal in Finder / Explorer | Open the item's location in your OS file manager |
+| Add Favorite | Pin this item to the Favorites section |
+| Remove Favorite | Unpin from Favorites |
+| Move Favorite Up / Down | Reorder within Favorites |
 
 ## Documentation
 
@@ -62,6 +158,7 @@ Design documents for contributors and AI-assisted development:
 - [Commands](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/commands.md) — All commands, menu placement, behaviors
 - [Workspace Scanning](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/workspace-scanning.md) — File discovery, include/exclude patterns
 - [Open Behavior](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/open-behavior.md) — Open modes, URI resolution, click handling
+- [Empty States](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/empty-states.md) — Git unavailable, no repository, no worktrees messages
 
 ## Requirements