docs: complete observability CLI reference

README.md

@@ -6,15 +6,15 @@
 
 ![Nightshift logo](logo.png)
 
-Your tokens get reset every week, you might as well use them. Nightshift runs overnight to find dead code, doc drift, test gaps, security issues, and 20+ other things silently accumulating while you ship features. Like a Roomba for your codebase — runs overnight, worst case you close the PR.
+Your tokens get reset every week, you might as well use them. Nightshift runs overnight to find dead code, doc drift, test gaps, security issues, and 20+ other things silently accumulating while you ship features. Like a Roomba for your codebase - runs overnight, worst case you close the PR.
 
 Everything lands as a branch or PR. It never writes directly to your primary branch. Don't like something? Close it. That's the whole rollback plan.
 
 ## Features
 
 - **Budget-aware**: Uses remaining daily allotment, never exceeds configurable max (default 75%)
 - **Multi-project**: Point it at your repos, it already knows what to look for
-- **Zero risk**: Everything is a PR — merge what surprises you, close the rest
+- **Zero risk**: Everything is a PR - merge what surprises you, close the rest
 - **Great DX**: Thoughtful CLI defaults with clear output and reports
 
 ## Installation
@@ -43,7 +43,9 @@ After installing, run the guided setup:
 nightshift setup
 ```
 
-This walks you through provider configuration, project selection, budget calibration, and daemon setup. Once complete you can preview what nightshift will do:
+This walks you through provider configuration, project selection, budget calibration, and daemon setup. It covers Claude, Codex, and Copilot, and checks for the provider CLIs on `PATH`. If you want a manual flow instead, use `nightshift init` for a project config, `nightshift init --global` for `~/.config/nightshift/config.yaml`, and `nightshift config validate` to verify the result.
+
+Once complete you can preview what nightshift will do:
 
 ```bash
 nightshift preview
@@ -72,6 +74,14 @@ nightshift preview --write ./nightshift-prompts
 # Guided global setup
 nightshift setup
 
+# Bootstrap or inspect config
+nightshift init
+nightshift init --global
+nightshift config
+nightshift config get budget.max_percent
+nightshift config set budget.max_percent 15
+nightshift config validate
+
 # Check environment and config health
 nightshift doctor
 
@@ -95,6 +105,18 @@ nightshift task show lint-fix --prompt-only
 nightshift task run lint-fix --provider claude
 nightshift task run skill-groom --provider codex --dry-run
 nightshift task run lint-fix --provider codex --dry-run
+
+# Manage the scheduler and service lifecycle
+nightshift daemon start
+nightshift daemon start --foreground
+nightshift daemon start --timeout 45m
+nightshift daemon status
+nightshift daemon stop
+nightshift install
+nightshift install launchd
+nightshift install systemd
+nightshift install cron
+nightshift uninstall
 ```
 
 If `gum` is available, preview output is shown through the gum pager. Use `--plain` to disable.
@@ -115,6 +137,8 @@ daemon, CI) confirmation is auto-skipped.
 | `--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 (use with caution) |
+| `--branch`, `-b` | _(current branch)_ | Base branch for new feature branches |
+| `--timeout` | `30m` | Per-agent execution timeout |
 | `--yes`, `-y` | `false` | Skip the confirmation prompt |
 
 ```bash
@@ -138,24 +162,30 @@ nightshift run --ignore-budget
 
 # Target a specific project and task directly
 nightshift run -p ./my-project -t lint-fix
+
+# Base new branches off develop
+nightshift run --branch develop
+
+# Give agents more time
+nightshift run --timeout 45m
 ```
 
 Other useful flags:
 - `nightshift status --today` to see today's activity summary
 - `nightshift daemon start --foreground` for debug
-- `--category` — filter tasks by category (pr, analysis, options, safe, map, emergency)
-- `--cost` — filter by cost tier (low, medium, high, veryhigh)
-- `--prompt-only` — output just the raw prompt text for piping
-- `--provider` — required for `task run`, choose claude or codex
-- `--dry-run` — preview the prompt without executing
-- `--timeout` — execution timeout (default 30m)
+- `--category` - filter tasks by category (pr, analysis, options, safe, map, emergency)
+- `--cost` - filter by cost tier (low, medium, high, veryhigh)
+- `--prompt-only` - output just the raw prompt text for piping
+- `--provider` - required for `task run`, choose claude, codex, or copilot
+- `--dry-run` - preview the prompt without executing
+- `--timeout` - execution timeout (default 30m)
 
-## Authentication (Subscriptions)
+## Provider Setup
 
 Nightshift supports three AI providers:
 - **Claude Code** - Anthropic's Claude via local CLI
-- **Codex** - OpenAI's GPT via local CLI  
-- **GitHub Copilot** - GitHub's Copilot via GitHub CLI
+- **Codex** - OpenAI's Codex via local CLI
+- **GitHub Copilot** - GitHub's Copilot via the standalone `copilot` binary or `gh copilot`
 
 ### Claude Code
 
@@ -177,13 +207,17 @@ Supports signing in with ChatGPT or an API key.
 ### GitHub Copilot
 
 ```bash
-# Install Copilot CLI
+# Standalone binary
 npm install -g @github/copilot
 # or
 curl -fsSL https://gh.io/copilot-install | bash
+# GitHub CLI extension
+gh extension install github/gh-copilot
 ```
 
-Requires GitHub Copilot subscription. See [docs/COPILOT_INTEGRATION.md](docs/COPILOT_INTEGRATION.md) for details.
+Nightshift prefers the standalone `copilot` binary when it exists, otherwise it falls back to `gh copilot`. `nightshift setup` checks for both and uses whichever is on `PATH`.
+
+If you use `gh copilot`, authenticate with `gh auth login` first.
 
 If you prefer API-based usage, you can authenticate Claude and Codex CLIs with API keys instead.
 
@@ -198,15 +232,17 @@ Nightshift uses YAML config files to define:
 - Task priorities
 - Schedule preferences
 
-Run `nightshift setup` to create/update the global config at `~/.config/nightshift/config.yaml`.
+Use `nightshift setup` for guided onboarding. Use `nightshift init` to create a project config in the current directory, or `nightshift init --global` to create `~/.config/nightshift/config.yaml`. `nightshift config` shows the merged configuration, `nightshift config get KEY` reads a value, `nightshift config set KEY VALUE` writes a value, and `nightshift config validate` checks both the global and project files.
 
-See the [full configuration docs](https://nightshift.haplab.com/docs/configuration) or [SPEC.md](docs/SPEC.md) for detailed options.
+See the [full configuration docs](https://nightshift.haplab.com/docs/configuration) for detailed options.
 
 Minimal example:
 
 ```yaml
 schedule:
   cron: "0 2 * * *"
+  max_projects: 1
+  max_tasks: 1
 
 budget:
   mode: daily
@@ -220,6 +256,7 @@ providers:
   preference:
     - claude
     - codex
+    - copilot
   claude:
     enabled: true
     data_path: "~/.claude"
@@ -228,12 +265,18 @@ providers:
     enabled: true
     data_path: "~/.codex"
     dangerously_bypass_approvals_and_sandbox: true
+  copilot:
+    enabled: true
+    data_path: "~/.copilot"
+    dangerously_skip_permissions: false
 
 projects:
   - path: ~/code/sidecar
   - path: ~/code/td
 ```
 
+Default provider order is `claude -> codex -> copilot`. Nightshift uses whichever provider has budget remaining, unless you override the provider or disable one in config.
+
 Task selection:
 
 ```yaml
@@ -267,9 +310,9 @@ make install-hooks
 ```
 
 This symlinks `scripts/pre-commit.sh` into `.git/hooks/pre-commit`. The hook runs:
-- **gofmt** — flags any staged `.go` files that need formatting
-- **go vet** — catches common correctness issues
-- **go build** — ensures the project compiles
+- **gofmt** - flags any staged `.go` files that need formatting
+- **go vet** - catches common correctness issues
+- **go build** - ensures the project compiles
 
 To bypass in a pinch: `git commit --no-verify`