docs: update documentation for v0.3.1–v0.5.2 release changes

MiniCodeMonkey · MiniCodeMonkey · commit f8a9dc3fb37f · 2026-02-20T12:09:50.000+01:00
- Add `chief update` command and automatic version check on startup
- Add diff view (`d` key) and `l` key for PRD picker selection mode
- Add `e` key (edit PRD from any view), `PgUp`/`PgDn`, `+`/`-` keybindings
- Replace removed `--no-sound` flag with `--no-retry` flag
- Fix `--max-iterations` default from hardcoded values to "Dynamic"
- Add `name` and `context` arguments to `chief new`
- Fix build-from-source commands to include `./cmd/chief`
- Remove obsolete sound/audio references (feature removed in v0.5.0)
diff --git a/docs/concepts/how-it-works.md b/docs/concepts/how-it-works.md
@@ -116,7 +116,9 @@ The TUI shows branch and directory information throughout:
 Autonomous doesn't mean unattended. The TUI lets you:
 
 - **Start / Pause / Stop**: Press `s` to start, `p` to pause after the current story, `x` to stop immediately
-- **Switch projects**: Press `n` to cycle through projects, or `1-9` to jump directly
+- **Review diffs**: Press `d` to see the commit diff for the selected story
+- **Edit the PRD**: Press `e` to open the current PRD in Claude Code for refinement
+- **Switch projects**: Press `l` to list PRDs, `n` to create a new one, or `1-9` to jump directly
 - **Resume anytime**: Walk away, come back, press `s`. Chief picks up where you left off
 - **Merge branches**: Press `m` in the picker to merge a completed branch
 - **Clean worktrees**: Press `c` in the picker to remove a worktree and optionally delete the branch
diff --git a/docs/concepts/ralph-loop.md b/docs/concepts/ralph-loop.md
@@ -193,7 +193,7 @@ The next iteration starts fresh. Claude reads the updated PRD, sees the complete
 
 ## Iteration Limits
 
-Chief has a safety limit on iterations (default: 100). This prevents runaway loops if something goes wrong.
+Chief has a safety limit on iterations to prevent runaway loops. When `--max-iterations` is not specified, the limit is calculated dynamically based on the number of remaining stories plus a buffer. You can also adjust the limit at runtime with `+`/`-` in the TUI.
 
 | Scenario | What Happens |
 |----------|--------------|
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
@@ -61,12 +61,22 @@ This method:
 - Installs to `/opt/homebrew/bin/chief` (Apple Silicon) or `/usr/local/bin/chief` (Intel/Linux)
 - Works on macOS (Apple Silicon and Intel) and Linux (x64 and ARM64)
 
-### Updating with Homebrew
+### Updating
+
+The easiest way to update is Chief's built-in update command, which works regardless of how you installed:
+
+```bash
+chief update
+```
+
+If you installed via Homebrew, you can also use:
 
 ```bash
 brew update && brew upgrade chief
 ```
 
+Chief automatically checks for updates on startup and notifies you when a new version is available.
+
 ## Install Script
 
 Download and install with a single command:
@@ -197,18 +207,18 @@ git clone https://github.com/minicodemonkey/chief.git
 cd chief
 
 # Build the binary
-go build -o chief
+go build -o chief ./cmd/chief
 
 # Optionally install to your GOPATH/bin
-go install
+go install ./cmd/chief
 ```
 
 ### Build with Version Info
 
 For a release-quality build with version information embedded:
 
 ```bash
-go build -ldflags "-X main.version=$(git describe --tags --always)" -o chief
+go build -ldflags "-X main.version=$(git describe --tags --always)" -o chief ./cmd/chief
 ```
 
 ### Verify the Build
@@ -236,10 +246,10 @@ Expected output:
 
 ```
 $ chief --version
-chief version v0.1.0
+chief version vX.Y.Z
 
 $ claude --version
-Claude Code CLI v1.0.0
+Claude Code vX.Y.Z
 ```
 
 ::: warning Troubleshooting
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
@@ -91,31 +91,38 @@ Press `s` to start the Ralph Loop. Chief will offer to create a worktree for iso
 
 The TUI shows:
 
-- **Tab Bar** - All your PRDs with status indicators
-- **Stories List** - User stories with completion status
-- **Story Details** - Current story's description and acceptance criteria
-- **Live Activity** - Real-time status updates from Claude
+- **Tab Bar** — All your PRDs with status indicators
+- **Stories List** — User stories with completion status
+- **Story Details** — Current story's description and acceptance criteria
+- **Live Activity** — Real-time status updates from Claude
+- **Diff View** — Press `d` to see the commit diff for the selected story
 
 ### Keyboard Controls
 
 | Key | Action |
 |-----|--------|
-| `s` | **Start** the loop (when Ready, Paused, or Stopped) |
+| `s` | **Start** the loop (when Ready, Paused, Stopped, or Error) |
 | `p` | **Pause** the loop (finishes current iteration) |
 | `x` | **Stop** the loop immediately |
 | `t` | **Toggle** between Dashboard and Log views |
-| `n` | Open **PRD picker** to switch or create PRDs |
+| `d` | **Diff view** — show the selected story's commit diff |
+| `n` | Open **PRD picker** to create or switch PRDs |
+| `l` | Open **PRD picker** in selection mode |
+| `e` | **Edit** current PRD via Claude Code |
 | `1-9` | **Quick switch** to PRD tabs 1-9 |
-| `j/↓` | Navigate down (stories or scroll log) |
-| `k/↑` | Navigate up (stories or scroll log) |
+| `j/↓` | Navigate down (stories or scroll log/diff) |
+| `k/↑` | Navigate up (stories or scroll log/diff) |
+| `PgDn` / `Ctrl+D` | Page down (log/diff) |
+| `PgUp` / `Ctrl+U` | Page up (log/diff) |
+| `+`/`-` | Adjust max iterations |
 | `m` | **Merge** completed branch (in picker) |
 | `c` | **Clean** worktree (in picker) |
 | `,` | Open **Settings** |
 | `?` | Show **help** overlay |
 | `q` | **Quit** Chief |
 
 ::: info Hands-off operation
-Once started with `s`, Chief runs autonomously. You can watch the progress or walk away—it will complete your PRD and play a sound when done.
+Once started with `s`, Chief runs autonomously. You can watch the progress or walk away—it will complete your PRD while you're gone.
 :::
 
 ## What's Next?
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -21,6 +21,7 @@ chief [command] [flags]
 | `edit` | Open the PRD for editing |
 | `status` | Show current PRD progress |
 | `list` | List all PRDs in the project |
+| `update` | Update Chief to the latest version |
 
 ## Commands
 
@@ -42,8 +43,8 @@ chief [name]
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--max-iterations <n>`, `-n` | Maximum loop iterations | `10` |
-| `--no-sound` | Disable completion sound | `false` |
+| `--max-iterations <n>`, `-n` | Maximum loop iterations | Dynamic |
+| `--no-retry` | Disable auto-retry on Claude crashes | `false` |
 | `--verbose` | Show raw Claude output in log | `false` |
 
 **Examples:**
@@ -59,9 +60,13 @@ chief auth-system
 chief --max-iterations 200
 
 # Combine flags
-chief auth-system -n 50 --no-sound
+chief auth-system -n 50 --verbose
 ```
 
+::: info Dynamic iteration limit
+When `--max-iterations` is not specified, Chief calculates a dynamic limit based on the number of remaining stories plus a buffer. You can adjust the limit at runtime with `+`/`-` in the TUI.
+:::
+
 ::: tip
 If your project has only one PRD, Chief auto-detects it. Pass a name when you have multiple PRDs.
 :::
@@ -73,9 +78,16 @@ If your project has only one PRD, Chief auto-detects it. Pass a name when you ha
 Create a new PRD in the current project. This command launches Claude Code with a preloaded prompt to help you define your project requirements interactively.
 
 ```bash
-chief new
+chief new [name] [context]
 ```
 
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `name` | PRD name (optional, defaults to `main`). Must contain only letters, numbers, hyphens, and underscores. |
+| `context` | Additional context to pass to Claude (optional). Included in the PRD creation prompt. |
+
 **How it works:**
 
 1. Chief launches Claude Code with a specialized PRD-creation prompt
@@ -97,9 +109,15 @@ chief new
 **Examples:**
 
 ```bash
-# Create a new PRD
+# Create a new PRD (defaults to name "main")
 chief new
 
+# Create a named PRD
+chief new auth-system
+
+# Create a PRD with additional context
+chief new auth-system "We use Express.js with JWT tokens"
+
 # Claude Code opens - describe what you want to build
 # Type /exit when done - Chief generates the PRD files
 ```
@@ -204,6 +222,37 @@ chief list
 
 ---
 
+### chief update
+
+Update Chief to the latest version. Downloads and installs the newest release from GitHub.
+
+```bash
+chief update
+```
+
+Chief checks the GitHub releases API, compares your current version to the latest, and downloads the appropriate binary for your platform if an update is available.
+
+**Examples:**
+
+```bash
+# Update to latest version
+chief update
+
+# Example output:
+#   Checking for updates...
+#   Downloading v0.5.2 (you have v0.4.0)...
+#   Updated to v0.5.2.
+```
+
+::: tip Automatic update check
+Chief performs a non-blocking version check every time you launch the TUI. If a newer version is available, you'll see a message like:
+```
+Chief v0.5.2 available (you have v0.5.1). Run 'chief update' to upgrade.
+```
+:::
+
+---
+
 ## Keyboard Shortcuts (TUI)
 
 When Chief is running, the TUI provides real-time feedback and interactive controls:
@@ -221,14 +270,16 @@ When Chief is running, the TUI provides real-time feedback and interactive contr
 | Key | Action |
 |-----|--------|
 | `t` | **Toggle** between Dashboard and Log views |
+| `d` | **Toggle** Diff view (shows the selected story's commit diff) |
 
 ### PRD Management
 
 | Key | Action |
 |-----|--------|
-| `n` | Open **PRD picker** (switch PRDs or create new) |
+| `n` | Open **PRD picker** in create mode (switch PRDs or create new) |
+| `l` | Open **PRD picker** in selection mode (switch between existing PRDs) |
 | `1-9` | **Quick switch** to PRD tabs 1-9 |
-| `e` | **Edit** selected PRD (in picker) |
+| `e` | **Edit** current PRD via Claude Code (from any main view) |
 | `m` | **Merge** completed PRD's branch into main (in picker or completion screen) |
 | `c` | **Clean** worktree and optionally delete branch (in picker or completion screen) |
 
@@ -242,12 +293,14 @@ When Chief is running, the TUI provides real-time feedback and interactive contr
 
 | Key | Action |
 |-----|--------|
-| `j` / `↓` | Move down (stories in Dashboard, scroll in Log) |
-| `k` / `↑` | Move up (stories in Dashboard, scroll in Log) |
-| `Ctrl+D` | Page down (Log view) |
-| `Ctrl+U` | Page up (Log view) |
-| `g` | Jump to top (Log view) |
-| `G` | Jump to bottom (Log view) |
+| `j` / `↓` | Move down (stories in Dashboard, scroll in Log/Diff) |
+| `k` / `↑` | Move up (stories in Dashboard, scroll in Log/Diff) |
+| `Ctrl+D` / `PgDn` | Page down (Log/Diff view) |
+| `Ctrl+U` / `PgUp` | Page up (Log/Diff view) |
+| `g` | Jump to top (Log/Diff view) |
+| `G` | Jump to bottom (Log/Diff view) |
+| `+` / `=` | Increase max iterations by 5 |
+| `-` / `_` | Decrease max iterations by 5 |
 
 ### General
 
@@ -259,7 +312,7 @@ When Chief is running, the TUI provides real-time feedback and interactive contr
 | `Ctrl+C` | Force quit |
 
 ::: tip
-The TUI has two main views: **Dashboard** showing stories and progress, and **Log** view streaming Claude's output in real time. Press `t` to toggle between them.
+The TUI has three views: **Dashboard** showing stories and progress, **Log** streaming Claude's output in real time, and **Diff** showing the commit diff for the selected story. Press `t` to toggle Dashboard/Log, or `d` to open the Diff view.
 :::
 
 ## Exit Codes
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
@@ -83,12 +83,14 @@ These settings are saved to `.chief/config.yaml` and can be changed at any time
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--max-iterations <n>`, `-n` | Loop iteration limit | `10` |
-| `--no-sound` | Disable completion sound | `false` |
+| `--max-iterations <n>`, `-n` | Loop iteration limit | Dynamic |
+| `--no-retry` | Disable auto-retry on Claude crashes | `false` |
 | `--verbose` | Show raw Claude output in log | `false` |
 | `--merge` | Auto-merge progress on conversion conflicts | `false` |
 | `--force` | Auto-overwrite on conversion conflicts | `false` |
 
+When `--max-iterations` is not specified, Chief calculates a dynamic limit based on the number of remaining stories plus a buffer. You can also adjust the limit at runtime with `+`/`-` in the TUI.
+
 ## Claude Code Configuration
 
 Chief invokes Claude Code under the hood. Claude Code has its own configuration:
diff --git a/docs/reference/prd-schema.md b/docs/reference/prd-schema.md
@@ -105,7 +105,7 @@ Array of strings, each describing a requirement. Claude uses these to know when
 
 ### priority
 
-Lower numbers = higher priority. Chief always picks the lowest-priority incomplete story.
+Lower numbers = higher priority. Chief always picks the incomplete story with the lowest priority number first.
 
 **Range:** Positive integers, typically 1-100
 
diff --git a/docs/troubleshooting/common-issues.md b/docs/troubleshooting/common-issues.md
@@ -1,5 +1,5 @@
 ---
-description: Troubleshoot common Chief issues including Claude not found, permission errors, audio problems, and loop failures.
+description: Troubleshoot common Chief issues including Claude not found, permission errors, worktree problems, and loop failures.
 ---
 
 # Common Issues
@@ -34,22 +34,6 @@ claude --version
 
 Chief automatically runs Claude with permission prompts disabled for autonomous operation. If you're still seeing permission issues, ensure you're running Chief (not Claude directly) and that your Claude Code installation is up to date.
 
-## No Sound on Completion
-
-**Symptom:** Chief completes but no sound plays.
-
-**Cause:** Audio system configuration or muted output.
-
-**Solution:**
-
-1. Check system volume isn't muted
-2. Verify audio device is selected correctly
-3. Run with `--no-sound` if audio isn't needed:
-
-```bash
-chief --no-sound
-```
-
 ## PRD Not Updating
 
 **Symptom:** Stories stay incomplete even though Claude seems to finish.
@@ -102,7 +86,7 @@ chief --no-sound
 
 **Symptom:** Chief stops with "max iterations reached" message.
 
-**Cause:** Claude hasn't completed after the iteration limit (default 10).
+**Cause:** Claude hasn't completed after the iteration limit.
 
 **Solution:**
 
