Backfill missing documentation

Makefile

@@ -75,10 +75,12 @@ help:
 	@echo "  check         - Run tests and lint"
 	@echo "  install       - Build and install to Go bin directory"
 	@echo "  calibrate-providers - Compare local Claude/Codex session usage for calibration"
-	@echo "  install-hooks  - Install git pre-commit hook"
+	@echo "  install-hooks  - Install git hooks"
 	@echo "  help          - Show this help"
 
-# Install git pre-commit hook
+# Install git hooks
 install-hooks:
 	@ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit
+	@ln -sf ../../scripts/commit-msg.sh .git/hooks/commit-msg
 	@echo "✓ pre-commit hook installed (.git/hooks/pre-commit → scripts/pre-commit.sh)"
+	@echo "✓ commit-msg hook installed (.git/hooks/commit-msg → scripts/commit-msg.sh)"

README.md

@@ -146,7 +146,7 @@ Other useful flags:
 - `--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
+- `--provider` — required for `task run`, choose claude, codex, or copilot
 - `--dry-run` — preview the prompt without executing
 - `--timeout` — execution timeout (default 30m)
 
@@ -220,6 +220,7 @@ providers:
   preference:
     - claude
     - codex
+    - copilot
   claude:
     enabled: true
     data_path: "~/.claude"
@@ -228,6 +229,10 @@ 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
@@ -258,19 +263,38 @@ Each task has a default cooldown interval to prevent the same task from running
 
 ## Development
 
-### Pre-commit hooks
+### Git hooks
 
-Install the git pre-commit hook to catch formatting and vet issues before pushing:
+Install the git hooks to catch formatting, vet, build, and commit message issues before pushing:
 
 ```bash
 make install-hooks
 ```
 
-This symlinks `scripts/pre-commit.sh` into `.git/hooks/pre-commit`. The hook runs:
+This symlinks `scripts/pre-commit.sh` into `.git/hooks/pre-commit` and `scripts/commit-msg.sh` into `.git/hooks/commit-msg`.
+
+The pre-commit hook runs:
 - **gofmt** — flags any staged `.go` files that need formatting
 - **go vet** — catches common correctness issues
 - **go build** — ensures the project compiles
 
+The commit message hook accepts:
+
+```text
+type: summary
+type(scope): summary
+```
+
+Accepted types are `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `build`, `ci`, `perf`, `style`, and `revert`. The hook normalizes safe cases such as `FIX: thing`, `feat - thing`, and extra whitespace, while preserving the body and trailers. Merge, revert, `fixup!`, and `squash!` commits are allowed.
+
+Valid examples:
+
+```text
+feat: add project setup command
+fix(config): preserve default provider
+docs: document hook installation
+```
+
 To bypass in a pinch: `git commit --no-verify`
 
 ## Uninstalling

docs/COPILOT_INTEGRATION.md

@@ -0,0 +1,144 @@
+# GitHub Copilot Integration
+
+Nightshift can run tasks through GitHub Copilot CLI in the same provider pipeline as Claude Code and Codex. Copilot is selected when it is enabled, appears in `providers.preference`, its CLI is available, and the budget manager reports remaining allowance.
+
+## Installation
+
+Nightshift supports either the standalone Copilot CLI or the GitHub CLI Copilot extension.
+
+Standalone:
+
+```bash
+npm install -g @github/copilot
+```
+
+GitHub CLI extension:
+
+```bash
+gh extension install github/gh-copilot
+```
+
+If both `copilot` and `gh` are on `PATH`, Nightshift prefers the standalone `copilot` binary. Otherwise it falls back to `gh copilot`.
+
+## Authentication
+
+Copilot requires a GitHub account with an active Copilot subscription. Authenticate through GitHub CLI before using Nightshift:
+
+```bash
+gh auth login
+gh auth status
+```
+
+Then confirm Copilot is available:
+
+```bash
+gh copilot -- --version
+# or, for standalone installs:
+copilot --version
+```
+
+## Configuration
+
+Copilot is enabled by default in Nightshift's config defaults, and the default provider preference order is `claude`, `codex`, then `copilot`. Add it explicitly when you want Copilot in your configured order:
+
+```yaml
+providers:
+  preference:
+    - claude
+    - codex
+    - copilot
+  copilot:
+    enabled: true
+    data_path: "~/.copilot"
+    dangerously_skip_permissions: false
+```
+
+`providers.copilot.data_path` stores Nightshift's local request counter at `nightshift-usage.json`. The file is separate from GitHub's own account usage data.
+
+## Execution Model
+
+Nightshift runs Copilot non-interactively with a prompt and disables user questions:
+
+```bash
+copilot -p "<prompt>" --no-ask-user --silent
+```
+
+When using GitHub CLI passthrough, the equivalent command is:
+
+```bash
+gh copilot -- -p "<prompt>" --no-ask-user --silent
+```
+
+If `providers.copilot.dangerously_skip_permissions` is true, Nightshift also passes:
+
+```bash
+--allow-all-tools --allow-all-urls
+```
+
+Leave this false for interactive or exploratory use. Set it only for unattended cron, daemon, or CI runs where Copilot must not stop for tool or URL prompts.
+
+## Running a Task
+
+Run Copilot directly for a single task:
+
+```bash
+nightshift task run docs-backfill --provider copilot
+nightshift task run lint-fix --provider copilot --dry-run
+```
+
+For scheduled or immediate runs, include Copilot in `providers.preference` and run:
+
+```bash
+nightshift run
+nightshift run --yes
+```
+
+Nightshift chooses the first enabled provider in preference order that has a CLI available and enough remaining budget.
+
+## Budget Tracking
+
+GitHub Copilot does not expose authoritative local usage percentages to Nightshift. Nightshift tracks Copilot conservatively by counting successful requests it sends through the Copilot provider:
+
+- Each Nightshift Copilot execution counts as one premium request.
+- The counter resets monthly on the first day of the month at 00:00:00 UTC.
+- The counter only includes Copilot usage made through Nightshift.
+- Token costs are reported as zero because Copilot uses request limits rather than per-token pricing.
+
+Nightshift's budget manager still uses `budget.weekly_tokens` or `budget.per_provider.copilot` as the configured allowance input. Internally it approximates a monthly Copilot request limit as four times the configured weekly provider budget, then applies the same daily or weekly budget mode, max percent, reserve percent, and daytime usage reserve logic as other providers.
+
+Example request-limit-oriented configuration:
+
+```yaml
+budget:
+  mode: weekly
+  max_percent: 75
+  reserve_percent: 5
+  per_provider:
+    copilot: 75
+```
+
+With Copilot, treat this value as a request allowance rather than a token allowance.
+
+## Limitations
+
+- GitHub does not provide Nightshift with a local authoritative remaining-quota API.
+- Usage outside Nightshift is not counted in `~/.copilot/nightshift-usage.json`.
+- Daily and weekly Copilot percentages are estimates derived from monthly request tracking.
+- The low-level provider adapter in `internal/providers/copilot.go` is used for budget tracking; task execution uses `internal/agents/copilot.go`.
+
+## Troubleshooting
+
+`copilot CLI not found in PATH`: Install either `copilot` or `gh`, then make sure the binary is visible to the shell that starts Nightshift.
+
+`copilot CLI not found in PATH (install via 'gh' or standalone)`: For `gh` mode, install the `github/gh-copilot` extension and verify `gh extension list` includes it.
+
+Copilot waits for permission: Set `providers.copilot.dangerously_skip_permissions: true` for unattended runs, or run interactively and approve the prompt.
+
+Budget shows unexpected request counts: Inspect or remove `~/.copilot/nightshift-usage.json`. Nightshift will recreate it for the current UTC month.
+
+Related docs:
+
+- [Technical specification](SPEC.md)
+- [Run lifecycle](guides/run-lifecycle.md)
+- [Codex budget tracking](guides/codex-budget-tracking.md)
+- [Provider calibration](guides/provider-calibration.md)