docs: update README for auto-lookback feature and add -a short flag (#8)

README.md

@@ -37,6 +37,53 @@ claude-chill claude
 claude-chill -- claude --verbose   # Use -- for command flags
 ```
 
+### Command Line Help
+
+```
+$ claude-chill --help
+A PTY proxy that tames Claude Code's massive terminal updates
+
+Usage: claude-chill [OPTIONS] <COMMAND> [ARGS]...
+
+Arguments:
+  <COMMAND>  Command to run (e.g., "claude")
+  [ARGS]...  Arguments to pass to the command
+
+Options:
+  -H, --history <HISTORY_LINES>
+          Max lines stored for lookback (default: 100000)
+  -k, --lookback-key <LOOKBACK_KEY>
+          Key to toggle lookback mode, quote to prevent glob expansion (default: "[ctrl][6]")
+  -a, --auto-lookback-timeout <AUTO_LOOKBACK_TIMEOUT>
+          Auto-lookback timeout in ms, 0 to disable (default: 5000)
+  -h, --help
+          Print help
+  -V, --version
+          Print version
+```
+
+### Examples
+
+```bash
+# Basic usage
+claude-chill claude
+
+# Pass arguments to claude
+claude-chill -- claude --verbose
+
+# Custom history size
+claude-chill -H 50000 claude
+
+# Custom lookback key
+claude-chill -k "[f12]" claude
+
+# Disable auto-lookback (see below)
+claude-chill -a 0 claude
+
+# Combine options with claude arguments
+claude-chill -H 50000 -a 0 -- claude --verbose
+```
+
 ## Lookback Mode
 
 Press `Ctrl+6` (or your configured key) to enter lookback mode:
@@ -48,15 +95,21 @@ Press `Ctrl+6` (or your configured key) to enter lookback mode:
 
 When you exit lookback mode, any cached output is processed and the current state is displayed.
 
-**Auto-lookback**: After 5 seconds of idle (no new renders), the full history is automatically displayed so you can scroll back without pressing any keys.
+## Auto-Lookback
+
+After 5 seconds of idle (no new renders), the full history is automatically dumped to your terminal so you can scroll back without pressing any keys. This is useful for reviewing Claude's output after it finishes working.
+
+**Note:** The auto-lookback causes a brief screen flicker during the transition as it clears the screen and writes the history buffer. Disable with `-a 0` or adjust the timeout with `-a 10000` (10 seconds).
 
 ## Configuration
 
 Create `~/.config/claude-chill.toml`:
 
 ```toml
-history_lines = 100000 # Max lines stored for lookback
+history_lines = 100000          # Max lines stored for lookback
-lookback_key = "[ctrl][6]"
+lookback_key = "[ctrl][6]"      # Key to toggle lookback mode
+refresh_rate = 20               # Rendering FPS
+auto_lookback_timeout_ms = 5000 # Auto-lookback after 5s idle (0 to disable)
 ```
 
 Note: History is cleared on full screen redraws, so lookback shows output since Claude's last full render.
@@ -69,6 +122,8 @@ Modifiers: `[ctrl]`, `[shift]`, `[alt]`
 
 Keys: `[a]`-`[z]`, `[f1]`-`[f12]`, `[pageup]`, `[pagedown]`, `[home]`, `[end]`, `[enter]`, `[tab]`, `[space]`, `[esc]`
 
+**Note:** Quote the key value on the command line to prevent shell glob expansion: `-k "[ctrl][7]"`
+
 ### Why Ctrl+6?
 
 `Ctrl+6` sends 0x1E, a control character not frequently used by terminals, signals, or shells. Avoid `Ctrl+letter` hotkeys - terminals can't distinguish `Ctrl+J` from `Ctrl+Shift+J`.

crates/claude-chill/src/cli.rs

@@ -1,19 +1,28 @@
 use clap::Parser;
 
 #[derive(Parser, Debug)]
-#[command(name = "claude-chill", version)]
+#[command(
+    name = "claude-chill",
+    version,
+    about = "A PTY proxy that tames Claude Code's massive terminal updates"
+)]
 pub struct Cli {
+    /// Command to run (e.g., "claude")
     pub command: String,
 
+    /// Arguments to pass to the command
     #[arg(trailing_var_arg = true)]
     pub args: Vec<String>,
 
+    /// Max lines stored for lookback (default: 100000)
     #[arg(short = 'H', long = "history")]
     pub history_lines: Option<usize>,
 
+    /// Key to toggle lookback mode, quote to prevent glob expansion (default: "[ctrl][6]")
     #[arg(short = 'k', long = "lookback-key")]
     pub lookback_key: Option<String>,
 
-    #[arg(long = "auto-lookback-timeout")]
+    /// Auto-lookback timeout in ms, 0 to disable (default: 5000)
+    #[arg(short = 'a', long = "auto-lookback-timeout")]
     pub auto_lookback_timeout: Option<u64>,
 }