update: resolve doc inconsistencies (#45)

encrypted-soul · web-flow · commit 3ef6a3f4b4b3 · 2026-03-19T13:08:07.000+05:30
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -42,7 +42,7 @@ export default defineConfig({
           { text: "Dashboard", link: "/guide/dashboard" },
           { text: "Reviewing Changes", link: "/guide/reviewing" },
           { text: "Resuming Work", link: "/guide/resuming" },
-          { text: "Agents", link: "/guide/agents" },
+          { text: "Agent Configuration", link: "/guide/agents" },
           { text: "Merging", link: "/guide/merging" },
         ],
       },
diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md
@@ -29,7 +29,7 @@ The `agent` block configures which AI coding agent to use.
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `command` | `string` | — | **Required.** Binary name or full path (`claude`, `codex`, `aider`, or a custom command). |
+| `command` | `string` | — | **Required.** Agent binary name or full path (currently `claude`). |
 | `args` | `string[]` | `[]` | Extra arguments passed before the prompt. |
 | `env` | `object` | `{}` | Extra environment variables for the agent process. |
 | `timeout` | `number` | — | Timeout in seconds. Agent is killed if it exceeds this. |
@@ -42,9 +42,6 @@ When `acceptAll` is `true` (the default), `ws` automatically adds flags based on
 | Agent | Flags |
 |---|---|
 | `claude` | `--dangerously-skip-permissions --output-format stream-json --verbose --include-partial-messages` |
-| `codex` | `--full-auto` |
-| `aider` | `--yes` |
-| Other | No flags injected |
 
 Set `acceptAll: false` to disable this behavior and control flags manually via `args`.
 
@@ -111,8 +108,6 @@ your-repo/
       dark-mode.log
     comments/              # Review comments
       add-tests.json
-    pending-prompts/       # Continuation prompts
-      add-tests.txt
 ```
 
 The `.workstreams/` directory is automatically added to `.gitignore`.
@@ -128,4 +123,4 @@ The `.workstreams/` directory is automatically added to `.gitignore`.
 ## Next Steps
 
 - [Concepts](/guide/concepts): how worktrees, agents, and parallel execution work
-- [Agents](/guide/agents): agent configuration for Claude, Codex, and Aider
+- [Agents](/guide/agents): agent configuration and custom models
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -4,10 +4,7 @@
 
 - **[Bun](https://bun.sh)** v1.0 or later
 - **Git** 2.20 or later (for worktree support)
-- At least one AI coding agent installed:
-  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (recommended)
-  - [Codex](https://github.com/openai/codex)
-  - [Aider](https://aider.chat)
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** installed
 
 ## Install
 
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -101,7 +101,15 @@ ws run add-tests -p "Resolve the merge conflicts with main"
 
 ## 7. Merge into Main
 
-When a workstream looks good, switch back to `main` and merge:
+When a workstream looks good, first make sure all changes on the workstream branch are committed:
+
+```bash
+cd $(ws checkout add-tests)
+git add .
+git commit -m "finalize changes"
+```
+
+Then switch back to `main` and merge:
 
 ```bash
 cd /path/to/your-repo          # return to the main working directory
diff --git a/docs/guide/agents.md b/docs/guide/agents.md
@@ -1,8 +1,8 @@
 # Agents
 
-`ws` supports multiple AI coding agents. Configure your preferred agent in the `agent` section of `workstream.yaml`.
+`ws` currently supports **Claude Code** as the AI coding agent. Additional agent support is coming soon.
 
-## Claude (Default)
+## Claude Code
 
 ```yaml
 agent:
@@ -15,9 +15,9 @@ agent:
 - `--verbose` — detailed logging
 - `--include-partial-messages` — stream partial messages
 
-**Features with Claude:**
+**Features:**
 - Session capture: `ws` extracts the session ID from Claude's stream-json output
-- Resume: `ws run <name> -p` continues the exact same conversation with full context
+- Resume: `ws run <name> -p "..."` continues the exact same conversation with full context
 - Auto-commit: successful changes are committed automatically
 
 ### Custom Model
@@ -31,41 +31,6 @@ agent:
     ANTHROPIC_MODEL: claude-sonnet-4-20250514
 ```
 
-## Codex
-
-```yaml
-agent:
-  command: codex
-```
-
-**Auto-injected flags:** `--full-auto`
-
-Codex does not support session resume. When resumed, a fresh session runs in the existing worktree with previous changes intact.
-
-## Aider
-
-```yaml
-agent:
-  command: aider
-```
-
-**Auto-injected flags:** `--yes`
-
-Like Codex, Aider does not support session resume. Fresh sessions pick up where the previous one left off via the existing worktree state.
-
-## Custom Agents
-
-Use any command-line tool as an agent:
-
-```yaml
-agent:
-  command: /path/to/my-agent
-  args: ["--some-flag"]
-  acceptAll: false    # No auto-injected flags for custom agents
-```
-
-The agent receives the prompt as the last argument. It runs with the worktree directory as the working directory.
-
 ## Disabling Auto-Accept Flags
 
 Set `acceptAll: false` to prevent `ws` from injecting any flags:
diff --git a/docs/guide/concepts.md b/docs/guide/concepts.md
@@ -52,7 +52,7 @@ ws run
 Each workstream goes through a lifecycle:
 
 ```
-ready → queued → running → success / failed
+ready → queued → running → success / failed / interrupted
 ```
 
 | Status | Meaning |
@@ -62,6 +62,7 @@ ready → queued → running → success / failed
 | `running` | Agent is actively working |
 | `success` | Agent completed without errors |
 | `failed` | Agent exited with an error |
+| `interrupted` | Agent was interrupted (e.g. Ctrl+C) |
 | `workspace` | No prompt, manual workspace only |
 
 ## Session Capture
@@ -78,7 +79,7 @@ The core workflow is iterative:
 4. Repeat until you're happy
 5. Merge
 
-Comments and pending prompts are stored in `.workstreams/comments/` and `.workstreams/pending-prompts/`. They're automatically included when resuming and cleared on success.
+Comments are stored in `.workstreams/comments/` and automatically included when resuming. They're cleared on success.
 
 ## Branches
 
diff --git a/docs/guide/dashboard.md b/docs/guide/dashboard.md
@@ -1,46 +1,24 @@
 # Dashboard
 
-The interactive dashboard is the central hub for managing workstreams.
+The dashboard is the recommended way to interact with your workstreams. It shows all workstreams at a glance and lets you view diffs, review changes, resume agents, and open editors — all from a single screen.
 
 ```bash
 ws dashboard
 ```
 
 ![Dashboard](/dashboard.png)
 
-## Layout
-
-The dashboard displays workstreams as compact cards:
-
-```
-  ✓ add-tests
-    Add unit tests for all API routes
-    +142 −3  ·  3 files  ·  2 min ago: test: add route coverage
-
-  ⠋ dark-mode
-    Implement dark mode toggle
-    running...
-
-  ○ fix-types
-    Fix all TypeScript type errors
-    ready
-```
-
-Each card shows:
-- **Line 1:** Status icon + workstream name
-- **Line 2:** Prompt (dimmed)
-- **Line 3:** Diff stats, commit info, comments count, resume status
-
 ## Status Icons
 
 | Icon | Status | Meaning |
 |---|---|---|
 | `✓` | success | Agent completed |
 | `✗` | failed | Agent errored |
-| `⠋` | running | Agent working (animated) |
-| `○` | queued | Scheduled to run |
+| `■` | interrupted | Agent was interrupted (e.g. Ctrl+C) |
+| `●` | running | Agent working (animated) |
+| `◉` | queued | Scheduled to run |
 | `○` | ready | Has prompt, not run yet |
-| `⊙` | workspace | Manual workspace, no prompt |
+| `◇` | workspace | Manual workspace, no prompt |
 
 ## Navigation
 
@@ -51,8 +29,6 @@ Each card shows:
 | `g` | Jump to first |
 | `G` | Jump to last |
 | `Enter` | Open action picker |
-| `/` | Search workstreams |
-| `?` | Toggle help overlay |
 | `q` / `Esc` | Quit |
 
 ## Action Picker
@@ -61,27 +37,16 @@ Press `Enter` on a workstream to see context-sensitive actions:
 
 **Before first run:**
 - Open in editor
-- Set/Edit prompt
 - Run agent
 
 **After successful run:**
 - Open in editor
 - Open session (interactive terminal)
-- Set continuation prompt
 - View diff & review
 - View logs
 
 **If changes exist:**
-- View diff & review: opens the [diff viewer](/guide/reviewing)
-
-## Search
-
-Press `/` to enter search mode. Type to filter workstreams. Matching uses multi-term AND logic:
-
-- `auth pass` finds workstreams matching both "auth" and "pass"
-- Search checks names, prompts, and status
-
-Press `Enter` to confirm the filter, `Esc` to clear.
+- View diff & review — opens the [diff viewer](/guide/reviewing)
 
 ## Opening in Your Editor
 
diff --git a/docs/guide/merging.md b/docs/guide/merging.md
@@ -2,6 +2,20 @@
 
 Each workstream lives on a `ws/<name>` branch. When you're done iterating, merge it like any other branch.
 
+## Commit changes on the workstream branch
+
+Before merging, make sure all changes on the workstream branch are committed:
+
+```bash
+cd $(ws checkout add-tests)
+git add .
+git commit -m "finalize changes"
+```
+
+::: tip
+If the agent completed successfully, changes are auto-committed. This step is only needed if you made manual edits in the worktree.
+:::
+
 ## Merge into main
 
 ```bash
diff --git a/docs/guide/resuming.md b/docs/guide/resuming.md
@@ -1,6 +1,6 @@
 # Resuming Work
 
-Resume a workstream to send new instructions or review comments to the agent. Resuming is done via `ws run` with the `-p` flag.
+Resume a workstream to send new instructions or review feedback to the agent. Use `ws run` with the `-p` flag.
 
 ## Resume with New Instructions
 
@@ -12,40 +12,19 @@ The agent continues from where it left off, with full context of its previous wo
 
 ## Resume with Review Comments
 
-After adding inline comments in the [diff viewer](/guide/reviewing), resume the workstream. Pending comments are included automatically:
+After adding inline comments in the [diff viewer](/guide/reviewing), resume the workstream. Comments are included automatically:
 
 ```bash
 ws run auth -p "Address the review comments"
 ```
 
 Comments are cleared after a successful resume.
 
-## Combined Resume
-
-When resuming, all pending context is combined in order:
-
-1. Stored review comments (from diff viewer)
-2. Pending prompt (set from dashboard)
-3. `-p` flag text
-
-```bash
-ws run auth -p "And fix the edge case on line 42"
-```
-
-## Setting a Pending Prompt
-
-From the dashboard (`ws dashboard`), select a workstream and choose "Set continuation prompt". This stores a prompt that will be included on the next resume.
-
 ## How Resume Works
 
-When resuming a Claude session:
-
-1. The stored `sessionId` is retrieved from state
+1. The stored `session_id` is retrieved from state
 2. `--resume <sessionId>` is passed to Claude
-3. Your new instructions are passed via `-p`
-4. The agent picks up with full conversation context
-5. Any new changes are auto-committed on success
-
-::: info
-Session resume is currently supported for **Claude** only. For Codex and Aider, resume starts a fresh session in the existing worktree (changes from the previous run are still present).
-:::
+3. Any stored review comments are included in the prompt
+4. Your `-p` text is appended
+5. The agent picks up with full conversation context
+6. New changes are auto-committed on success
diff --git a/docs/guide/reviewing.md b/docs/guide/reviewing.md
@@ -2,19 +2,17 @@
 
 ## View Diffs
 
-View changes from a specific workstream:
+From the dashboard, select a workstream, press `Enter`, and choose "View diff & review". Or from the command line:
 
 ```bash
-ws diff auth-feature
+ws diff auth-feature             # interactive diff viewer
 ```
 
-This opens an interactive diff viewer. For raw output (useful for piping):
-
 ![Diff viewer](/diff-viewer.png)
 
 ```bash
-ws diff auth --raw
-ws diff                  # raw diffs for all workstreams
+ws diff auth --raw               # raw output (for piping)
+ws diff                          # raw diffs for all workstreams
 ```
 
 ## Interactive Diff Viewer
@@ -51,14 +49,10 @@ Comments are shown as inline markers in the diff viewer and are automatically in
 
 ## Review Workflow
 
-The typical review loop:
-
-1. Run `ws diff auth` to browse changes
-2. Press `c` to comment on lines that need work
-3. Press `q` to exit the diff viewer
-4. Run `ws run auth -p "Address review comments"` to resume. Pending comments are included automatically.
-5. The agent addresses your feedback
+1. Open the dashboard with `ws dashboard` (or run `ws diff auth` directly)
+2. Select a workstream and choose "View diff & review"
+3. Press `c` to comment on lines that need work
+4. Press `q` to exit the diff viewer
+5. Resume with `ws run auth -p "Address review comments"` — comments are included automatically
 6. Repeat until satisfied
 7. Merge via GitHub PR or `git merge`
-
-You can also start the review from the dashboard: select a workstream, press `Enter`, and choose "View diff & review".
diff --git a/docs/guide/running.md b/docs/guide/running.md
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/reference/config.md b/docs/reference/config.md
diff --git a/docs/reference/keyboard-shortcuts.md b/docs/reference/keyboard-shortcuts.md
