From d30cf972b5f2c38bfee77330eff8e7ffafe01e10 Mon Sep 17 00:00:00 2001
From: Marcus Vorwaller <marcus@vorwaller.net>
Date: Fri, 10 Apr 2026 04:48:41 -0700
Subject: [PATCH] docs: backfill CLI reference

Nightshift-Task: docs-backfill

Nightshift-Ref: https://github.com/marcus/nightshift
---
 README.md                     |  17 ++++-
 website/docs/budget.md        |   2 +-
 website/docs/cli-reference.md | 140 ++++++++++++++++++++++++++++++----
 website/docs/installation.md  |  62 +++++++++++++++
 4 files changed, 204 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 84f92cd..6e20707 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,8 @@ Manual install:
 go install github.com/marcus/nightshift/cmd/nightshift@latest
 ```
 
+Nightshift can also generate shell completions for bash, zsh, fish, and PowerShell with `nightshift completion <shell>`. The [installation guide](https://nightshift.haplab.com/docs/installation) shows the persistent setup path for each shell.
+
 ## Getting Started
 
 Full guide: [Quick Start docs](https://nightshift.haplab.com/docs/quick-start)
@@ -77,7 +79,7 @@ nightshift doctor
 
 # Budget status and calibration
 nightshift budget --provider claude
-nightshift budget snapshot --local-only
+nightshift budget snapshot
 nightshift budget history -n 10
 nightshift budget calibrate
 
@@ -140,6 +142,19 @@ nightshift run --ignore-budget
 nightshift run -p ./my-project -t lint-fix
 ```
 
+## Morning After
+
+When the overnight run finishes, these are the fastest commands to check what happened:
+
+```bash
+nightshift status --today        # Quick activity summary
+nightshift report                # Polished recap of the last night
+nightshift report --report tasks # Task-focused follow-up
+nightshift logs --summary        # Fast log overview
+```
+
+Use `nightshift logs --follow` when you want to watch a fresh run in real time, and see the [CLI Reference docs](https://nightshift.haplab.com/docs/cli-reference) for the full reporting and diagnostics flag set.
+
 Other useful flags:
 - `nightshift status --today` to see today's activity summary
 - `nightshift daemon start --foreground` for debug
diff --git a/website/docs/budget.md b/website/docs/budget.md
index e965cea..c81f56c 100644
--- a/website/docs/budget.md
+++ b/website/docs/budget.md
@@ -85,7 +85,7 @@ View past budget snapshots:
 
 ```bash
 nightshift budget history -n 10
-nightshift budget snapshot --local-only
+nightshift budget snapshot
 ```
 
 ## Morning Summary
diff --git a/website/docs/cli-reference.md b/website/docs/cli-reference.md
index d5a2cd4..ec8036d 100644
--- a/website/docs/cli-reference.md
+++ b/website/docs/cli-reference.md
@@ -5,20 +5,29 @@ title: CLI Reference
 
 # CLI Reference
 
-## Core Commands
+Run `nightshift --help` or `nightshift <command> --help` for the current command surface and flag details. The sections below focus on the commands most people use regularly, with extra detail for reporting and diagnostics.
+
+## Top-Level Commands
 
 | Command | Description |
 |---------|-------------|
-| `nightshift setup` | Guided global configuration |
-| `nightshift run` | Execute scheduled tasks |
-| `nightshift preview` | Show upcoming runs |
-| `nightshift budget` | Check token budget status |
-| `nightshift task` | Browse and run tasks |
-| `nightshift doctor` | Check environment health |
-| `nightshift status` | View run history |
-| `nightshift logs` | Stream or export logs |
-| `nightshift stats` | Token usage statistics |
-| `nightshift daemon` | Background scheduler |
+| `nightshift budget` | Show budget status |
+| `nightshift busfactor` | Analyze code ownership concentration (bus factor) |
+| `nightshift completion` | Generate shell completions |
+| `nightshift config` | Manage configuration |
+| `nightshift daemon` | Manage background daemon |
+| `nightshift doctor` | Check Nightshift configuration and environment |
+| `nightshift init` | Create configuration file |
+| `nightshift install` | Install system service |
+| `nightshift logs` | View logs |
+| `nightshift preview` | Preview the next scheduled runs |
+| `nightshift report` | Show what nightshift did |
+| `nightshift run` | Execute tasks |
+| `nightshift setup` | Interactive onboarding wizard |
+| `nightshift stats` | Show aggregate statistics |
+| `nightshift status` | Show run history |
+| `nightshift task` | Manage and run tasks |
+| `nightshift uninstall` | Remove system service |
 
 ## Run Options
 
@@ -32,20 +41,25 @@ nightshift run --max-projects 3         # Process up to 3 projects
 nightshift run --max-tasks 2            # Run up to 2 tasks per project
 nightshift run --random-task            # Pick a random eligible task
 nightshift run --ignore-budget          # Bypass budget limits (use with caution)
+nightshift run --branch develop         # Use a specific base branch for feature work
+nightshift run --timeout 45m            # Override per-agent timeout
 nightshift run --project ~/code/myapp   # Target specific project (ignores --max-projects)
 nightshift run --task lint-fix          # Run specific task (ignores --max-tasks)
 ```
 
 | Flag | Default | Description |
 |------|---------|-------------|
+| `--branch`, `-b` | current branch | Base branch for new feature branches |
 | `--dry-run` | `false` | Show preflight summary and exit without executing |
 | `--yes`, `-y` | `false` | Skip confirmation prompt |
 | `--max-projects` | `1` | Max projects to process (ignored when `--project` is set) |
 | `--max-tasks` | `1` | Max tasks per project (ignored when `--task` is set) |
 | `--random-task` | `false` | Pick a random task from eligible tasks instead of the highest-scored one |
 | `--ignore-budget` | `false` | Bypass budget checks with a warning |
+| `--no-color` | `false` | Disable colored output |
 | `--project`, `-p` | | Target a specific project directory |
 | `--task`, `-t` | | Run a specific task by name |
+| `--timeout` | `30m` | Per-agent execution timeout |
 
 Non-interactive contexts (daemon, cron, piped output) skip the confirmation prompt automatically.
 
@@ -75,18 +89,114 @@ nightshift task run lint-fix --provider codex --dry-run
 
 ## Budget Commands
 
+`nightshift budget snapshot` captures a calibration snapshot from local usage data and, when enabled, tmux-scraped provider percentages.
+
 ```bash
 nightshift budget                 # Current status
 nightshift budget --provider claude
-nightshift budget snapshot --local-only
+nightshift budget snapshot
 nightshift budget history -n 10
 nightshift budget calibrate
 ```
 
-## Global Flags
+## Shell Completion
+
+Use `nightshift completion <shell>` to print a completion script for your shell. The [Installation](./installation.md) guide covers persistent setup paths for each shell.
+
+```bash
+source <(nightshift completion bash)
+source <(nightshift completion zsh)
+nightshift completion fish | source
+```
+
+```powershell
+nightshift completion powershell | Out-String | Invoke-Expression
+```
+
+## Status
+
+`nightshift status` is the fastest way to check recent run history without opening a full report or scanning raw logs.
+
+```bash
+nightshift status
+nightshift status --today
+nightshift status --last 10
+```
+
+| Flag | Description |
+|------|-------------|
+| `--today` | Show today's activity summary |
+| `--last`, `-n` | Show the last N runs |
+
+## Logs
+
+Use `nightshift logs` for real-time debugging, targeted filtering, and exporting raw log output.
+
+```bash
+nightshift logs
+nightshift logs --summary
+nightshift logs --follow
+nightshift logs --component scheduler --tail 100
+nightshift logs --match budget --since "2026-04-09 22:00"
+nightshift logs --export ./nightshift.log
+```
+
+| Flag | Description |
+|------|-------------|
+| `--component` | Filter by component substring |
+| `--match` | Filter by message substring |
+| `--level` | Minimum log level: `debug`, `info`, `warn`, or `error` |
+| `--since`, `--until` | Bound the time window |
+| `--tail`, `-n` | Limit how many lines to show |
+| `--summary` | Show summary counts instead of full lines |
+| `--follow`, `-f` | Stream new log lines in real time |
+| `--export`, `-e` | Write matching logs to a file |
+| `--raw` | Skip formatting and show raw log lines |
+| `--path` | Override the log directory |
+
+## Stats
+
+`nightshift stats` aggregates runs, task outcomes, token usage, budget projections, and per-project activity.
+
+```bash
+nightshift stats
+nightshift stats --period last-night
+nightshift stats --period last-7d
+nightshift stats --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--period`, `-p` | Time period: `all`, `last-7d`, `last-30d`, or `last-night` |
+| `--json` | Emit machine-readable JSON |
+
+## Report
+
+`nightshift report` gives you a polished morning-after summary, with alternate report types and output formats when you need to share or automate follow-up.
+
+```bash
+nightshift report
+nightshift report --report tasks
+nightshift report --period today --format markdown
+nightshift report --report budget --format json
+nightshift report --runs 1 --paths
+```
+
+| Flag | Description |
+|------|-------------|
+| `--report`, `-r` | Report type: `overview`, `tasks`, `projects`, `budget`, or `raw` |
+| `--period`, `-p` | Time period: `last-night`, `last-run`, `last-24h`, `last-7d`, `today`, `yesterday`, or `all` |
+| `--format` | Output format: `fancy`, `plain`, `markdown`, or `json` |
+| `--runs`, `-n` | Limit how many runs to include |
+| `--max-items` | Limit highlights per run |
+| `--paths` | Include report and log file paths |
+| `--since`, `--until` | Bound the time window explicitly |
+
+## Top-Level Flags
 
 | Flag | Description |
 |------|-------------|
 | `--verbose` | Verbose output |
-| `--provider` | Select provider (claude, codex) |
-| `--timeout` | Execution timeout (default 30m) |
+| `--version`, `-v` | Show the current version |
+
+Most commands add their own flags on top of these, so use `nightshift <command> --help` when you need the exact options for a specific workflow.
diff --git a/website/docs/installation.md b/website/docs/installation.md
index e2b37d2..a785564 100644
--- a/website/docs/installation.md
+++ b/website/docs/installation.md
@@ -39,6 +39,68 @@ nightshift --version
 nightshift --help
 ```
 
+## Shell Completion
+
+Nightshift can generate completion scripts for bash, zsh, fish, and PowerShell:
+
+```bash
+nightshift completion bash
+nightshift completion zsh
+nightshift completion fish
+nightshift completion powershell
+```
+
+Start a new shell after writing a completion file so the new completions are loaded.
+
+### Bash
+
+The generated bash script depends on the `bash-completion` package.
+
+```bash
+# Current shell
+source <(nightshift completion bash)
+
+# Persistent install on Linux
+nightshift completion bash > /etc/bash_completion.d/nightshift
+
+# Persistent install on macOS
+nightshift completion bash > $(brew --prefix)/etc/bash_completion.d/nightshift
+```
+
+### Zsh
+
+If completion is not already enabled, add `autoload -U compinit; compinit` to your `~/.zshrc` once.
+
+```bash
+# Current shell
+source <(nightshift completion zsh)
+
+# Persistent install on Linux
+nightshift completion zsh > "${fpath[1]}/_nightshift"
+
+# Persistent install on macOS
+nightshift completion zsh > $(brew --prefix)/share/zsh/site-functions/_nightshift
+```
+
+### Fish
+
+```bash
+# Current shell
+nightshift completion fish | source
+
+# Persistent install
+nightshift completion fish > ~/.config/fish/completions/nightshift.fish
+```
+
+### PowerShell
+
+```powershell
+# Current shell
+nightshift completion powershell | Out-String | Invoke-Expression
+```
+
+To make the PowerShell completion persistent, add the output of that command to your PowerShell profile.
+
 ## Prerequisites
 
 - **Claude Code CLI** (`claude`) and/or **Codex CLI** (`codex`) installed