diff --git a/cmd/nightshift/commands/doc.go b/cmd/nightshift/commands/doc.go
new file mode 100644
index 0000000..5b64260
--- /dev/null
+++ b/cmd/nightshift/commands/doc.go
@@ -0,0 +1,32 @@
+// Package commands implements the nightshift CLI commands using cobra.
+//
+// The commands package is the user-facing interface for nightshift. It provides
+// subcommands for running tasks, managing the daemon, checking budget status,
+// displaying configuration, running diagnostics, and installing system services.
+//
+// # Available Commands
+//
+//   - run       Execute configured tasks on one or more projects
+//   - daemon    Manage the background scheduler daemon (start/stop/status)
+//   - budget    Show budget status and token usage across providers
+//   - config    View and modify nightshift configuration
+//   - doctor    Run diagnostics to detect configuration or environment issues
+//   - init      Create a default nightshift.yaml configuration file
+//   - install   Install a system service (launchd, systemd, or cron)
+//   - uninstall Remove a previously installed system service
+//   - logs      Tail nightshift log output
+//   - preview   Show a dry-run preview of what would execute
+//   - report    Display reports from previous runs
+//   - snapshot  Manually take a usage snapshot
+//   - stats     Show usage statistics
+//   - status    Show current nightshift status
+//   - task      Manage task definitions
+//   - setup     Interactive first-time setup wizard
+//   - busfactor Analyze code ownership and bus factor
+//
+// # Configuration
+//
+// Commands load configuration from ~/.config/nightshift/config.yaml (global)
+// and nightshift.yaml (per-project). Project config overrides global config.
+// Use "nightshift config validate" to check for errors.
+package commands
diff --git a/cmd/nightshift/commands/root.go b/cmd/nightshift/commands/root.go
index 3d84a62..01e8233 100644
--- a/cmd/nightshift/commands/root.go
+++ b/cmd/nightshift/commands/root.go
@@ -1,4 +1,3 @@
-// Package commands implements the nightshift CLI commands using cobra.
 package commands
 
 import (
diff --git a/cmd/provider-calibration/doc.go b/cmd/provider-calibration/doc.go
new file mode 100644
index 0000000..b27de78
--- /dev/null
+++ b/cmd/provider-calibration/doc.go
@@ -0,0 +1,15 @@
+// Command provider-calibration analyzes AI provider token usage from session
+// logs and produces a JSON report for budget calibration.
+//
+// It reads Codex session JSONL files and Claude JSONL session files, extracts
+// per-session token counts, and aggregates them into weekly totals. The output
+// can be used to calibrate nightshift's budget estimates against real-world
+// provider usage.
+//
+// Usage:
+//
+//	provider-calibration [--dir <sessions-dir>] [--provider codex|claude] [--week YYYY-MM-DD]
+//
+// This is a standalone tool intended for manual budget tuning, not part of the
+// nightly automated runs.
+package main
diff --git a/internal/agents/agent.go b/internal/agents/agent.go
index 97894a9..a27f1e5 100644
--- a/internal/agents/agent.go
+++ b/internal/agents/agent.go
@@ -1,5 +1,3 @@
-// Package agents provides interfaces and implementations for spawning AI agents.
-// Unlike providers (which track usage), agents execute tasks autonomously.
 package agents
 
 import (
diff --git a/internal/agents/claude.go b/internal/agents/claude.go
index c34d513..ba6ece0 100644
--- a/internal/agents/claude.go
+++ b/internal/agents/claude.go
@@ -1,4 +1,3 @@
-// claude.go implements the Agent interface for Claude Code CLI.
 package agents
 
 import (
diff --git a/internal/agents/codex.go b/internal/agents/codex.go
index c366400..07b4934 100644
--- a/internal/agents/codex.go
+++ b/internal/agents/codex.go
@@ -1,4 +1,3 @@
-// codex.go implements the Agent interface for OpenAI Codex CLI.
 package agents
 
 import (
diff --git a/internal/agents/copilot.go b/internal/agents/copilot.go
index fd94226..580ba02 100644
--- a/internal/agents/copilot.go
+++ b/internal/agents/copilot.go
@@ -1,4 +1,3 @@
-// copilot.go implements the Agent interface for GitHub Copilot CLI.
 package agents
 
 import (
diff --git a/internal/agents/doc.go b/internal/agents/doc.go
new file mode 100644
index 0000000..2a22567
--- /dev/null
+++ b/internal/agents/doc.go
@@ -0,0 +1,24 @@
+// Package agents provides interfaces and implementations for spawning AI agents.
+//
+// Unlike providers (which track usage and billing), agents are responsible for
+// the actual execution of coding tasks. Each agent wraps a CLI tool and handles
+// prompt construction, process lifecycle, timeout management, and output parsing.
+//
+// # Supported Agents
+//
+//   - ClaudeAgent: Executes tasks via the Claude Code CLI ("claude --print")
+//   - CodexAgent:  Executes tasks via the OpenAI Codex CLI ("codex exec")
+//   - CopilotAgent: Executes tasks via GitHub Copilot CLI ("gh copilot" or standalone "copilot")
+//
+// # Agent Interface
+//
+// All agents implement the Agent interface, which provides Name() and Execute()
+// methods. The Execute method accepts ExecuteOptions (prompt, working directory,
+// files, timeout) and returns an ExecuteResult with the agent's output, exit code,
+// duration, and optional parsed JSON.
+//
+// # Testing
+//
+// Agents accept a CommandRunner option for mocking in tests. Use WithRunner
+// (or the provider-specific variant) to inject a test double.
+package agents
diff --git a/internal/analysis/analyzer.go b/internal/analysis/analyzer.go
index 863ab89..ac53f13 100644
--- a/internal/analysis/analyzer.go
+++ b/internal/analysis/analyzer.go
@@ -1,4 +1,3 @@
-// Package analysis provides code ownership and bus-factor analysis tools.
 package analysis
 
 import (
diff --git a/internal/analysis/doc.go b/internal/analysis/doc.go
new file mode 100644
index 0000000..31a19d8
--- /dev/null
+++ b/internal/analysis/doc.go
@@ -0,0 +1,18 @@
+// Package analysis provides code ownership and bus-factor analysis tools.
+//
+// It extracts commit history from git repositories, computes ownership
+// concentration metrics (Herfindahl index, Gini coefficient, bus factor),
+// and generates markdown reports with actionable recommendations.
+//
+// # Metrics
+//
+//   - Bus Factor: Minimum contributors whose departure would halve project capacity
+//   - Herfindahl Index: Ownership concentration (0=diverse, 1=monopoly)
+//   - Gini Coefficient: Contribution inequality (0=equal, 1=unequal)
+//   - Top N Percent: Cumulative ownership by top contributors
+//
+// # Persistence
+//
+// Analysis results can be stored in and loaded from SQLite via the db.go
+// functions (Store, LoadLatest, LoadAll).
+package analysis
diff --git a/internal/db/db.go b/internal/db/db.go
index 2f846a8..6afd1d7 100644
--- a/internal/db/db.go
+++ b/internal/db/db.go
@@ -1,4 +1,3 @@
-// Package db provides SQLite-backed storage for nightshift state and snapshots.
 package db
 
 import (
diff --git a/internal/db/doc.go b/internal/db/doc.go
new file mode 100644
index 0000000..1adf281
--- /dev/null
+++ b/internal/db/doc.go
@@ -0,0 +1,21 @@
+// Package db provides SQLite-backed storage for nightshift state and snapshots.
+//
+// It manages the database lifecycle (open, migrate, close) and exposes methods
+// for the persistence layer used by other internal packages.
+//
+// # Database Location
+//
+// The default path is ~/.local/share/nightshift/nightshift.db. Override with
+// the config key db.path or the --db flag.
+//
+// # Migrations
+//
+// Schema changes are tracked in the migrations.go file. Each migration is
+// applied once and recorded in a schema_version table. The database is
+// automatically migrated on Open.
+//
+// # Legacy Import
+//
+// On first migration, the package imports state from the legacy state.json
+// file if it exists (from nightshift versions prior to SQLite).
+package db
diff --git a/internal/integrations/doc.go b/internal/integrations/doc.go
new file mode 100644
index 0000000..b4a1810
--- /dev/null
+++ b/internal/integrations/doc.go
@@ -0,0 +1,18 @@
+// Package integrations provides readers for external configuration and task sources.
+//
+// It aggregates context and tasks from multiple sources — claude.md files,
+// agents.md files, the td task management CLI, and GitHub Issues — and merges
+// them into a unified result that can be injected into agent prompts.
+//
+// # Architecture
+//
+// Each integration implements the Reader interface (Name, Enabled, Read). A
+// Manager coordinates all readers and merges their output via ReadAll.
+//
+// # Supported Integrations
+//
+//   - claude.md: Reads CLAUDE.md or claude.md from the project root for context
+//   - agents.md: Reads AGENTS.md for agent behavior configuration
+//   - td:        Reads tasks from the td CLI task manager
+//   - github:    Reads issues labeled "nightshift" via the gh CLI
+package integrations
diff --git a/internal/integrations/integrations.go b/internal/integrations/integrations.go
index 5b7823b..17758d5 100644
--- a/internal/integrations/integrations.go
+++ b/internal/integrations/integrations.go
@@ -1,5 +1,3 @@
-// Package integrations provides readers for external configuration and task sources.
-// Supports claude.md, agents.md, td task management, and GitHub issues.
 package integrations
 
 import (
diff --git a/internal/orchestrator/doc.go b/internal/orchestrator/doc.go
new file mode 100644
index 0000000..52f09e5
--- /dev/null
+++ b/internal/orchestrator/doc.go
@@ -0,0 +1,25 @@
+// Package orchestrator coordinates AI agents working on tasks.
+//
+// It implements the plan-implement-review loop for task execution. Each task
+// goes through phases: planning, execution, and review. The orchestrator
+// manages iterations, timeouts, git branch creation, and PR traceability.
+//
+// # Execution Loop
+//
+// For each task the orchestrator:
+//  1. Creates a feature branch (docs/<task-type>-<slug>)
+//  2. Runs the agent with a structured prompt
+//  3. Reviews the result (optionally re-iterating)
+//  4. Records the outcome (completed, abandoned, or failed)
+//
+// # Events
+//
+// The orchestrator emits lifecycle events (EventTaskStart, EventPhaseStart,
+// etc.) that can be consumed via an EventHandler for live UI rendering.
+//
+// # Configuration
+//
+// Use Config to control max iterations, agent timeout, and other parameters.
+// Options are applied via WithAgent, WithConfig, WithLogger, and
+// WithEventHandler.
+package orchestrator
diff --git a/internal/orchestrator/orchestrator.go b/internal/orchestrator/orchestrator.go
index 6141c95..9c504b9 100644
--- a/internal/orchestrator/orchestrator.go
+++ b/internal/orchestrator/orchestrator.go
@@ -1,5 +1,3 @@
-// Package orchestrator coordinates AI agents working on tasks.
-// Implements the plan-implement-review loop for task execution.
 package orchestrator
 
 import (
diff --git a/internal/providers/claude.go b/internal/providers/claude.go
index 3f78e89..423e27d 100644
--- a/internal/providers/claude.go
+++ b/internal/providers/claude.go
@@ -1,4 +1,3 @@
-// claude.go implements the Provider interface for Claude Code CLI.
 package providers
 
 import (
diff --git a/internal/providers/codex.go b/internal/providers/codex.go
index eb948ed..c0a2c43 100644
--- a/internal/providers/codex.go
+++ b/internal/providers/codex.go
@@ -1,4 +1,3 @@
-// codex.go implements the Provider interface for OpenAI Codex CLI.
 package providers
 
 import (
diff --git a/internal/providers/copilot.go b/internal/providers/copilot.go
index fe69acf..8cc16f5 100644
--- a/internal/providers/copilot.go
+++ b/internal/providers/copilot.go
@@ -1,4 +1,3 @@
-// copilot.go implements the Provider interface for GitHub Copilot CLI.
 package providers
 
 import (
diff --git a/internal/providers/doc.go b/internal/providers/doc.go
new file mode 100644
index 0000000..075094d
--- /dev/null
+++ b/internal/providers/doc.go
@@ -0,0 +1,26 @@
+// Package providers defines interfaces and implementations for tracking AI
+// coding agent usage and costs.
+//
+// Each provider knows how to read usage data from the agent's local data
+// directory (stats-cache.json, JSONL session files, rate-limit endpoints) and
+// report percentage of budget consumed.
+//
+// # Supported Providers
+//
+//   - Claude:  Reads from ~/.claude/stats-cache.json and JSONL session files
+//   - Codex:   Reads from ~/.codex JSONL session files and rate-limit data
+//   - Copilot: Tracks usage via local request counting (GitHub API does not
+//     expose usage)
+//
+// # Usage Tracking
+//
+// Providers implement methods like GetUsedPercent, GetWeeklyUsage, and
+// GetUsageBreakdown that the budget package uses to calculate remaining
+// allowance for nightly runs.
+//
+// # Calibration
+//
+// The GetUsedPercent method accepts a mode ("daily" or "weekly") and a budget
+// ceiling in tokens. Some providers also support tmux-based scraping for
+// authoritative usage data when API data is unavailable.
+package providers
diff --git a/internal/providers/provider.go b/internal/providers/provider.go
index 07f53a7..4719b73 100644
--- a/internal/providers/provider.go
+++ b/internal/providers/provider.go
@@ -1,5 +1,3 @@
-// Package providers defines interfaces and implementations for AI coding agents.
-// Supports multiple backends: Claude Code, Codex CLI, etc.
 package providers
 
 import "context"
diff --git a/internal/reporting/doc.go b/internal/reporting/doc.go
new file mode 100644
index 0000000..e257a4b
--- /dev/null
+++ b/internal/reporting/doc.go
@@ -0,0 +1,19 @@
+// Package reporting generates run reports and morning summaries for nightshift.
+//
+// After a nightshift run completes, this package produces structured JSON
+// results (RunResults) and human-readable markdown reports. Reports are saved
+// to ~/.local/share/nightshift/reports/ and can optionally be sent via email
+// or Slack webhook.
+//
+// # Report Types
+//
+//   - Run report: Markdown summary of a single run (tasks completed, failed, skipped)
+//   - Run results: Structured JSON with per-task metrics and output references
+//   - Morning summary: Aggregated summary of the most recent run, suitable for
+//     notification delivery
+//
+// # File Naming
+//
+// Reports are named with timestamps: run-2006-01-02-150405.md and
+// run-2006-01-02-150405.json.
+package reporting
diff --git a/internal/reporting/summary.go b/internal/reporting/summary.go
index fd78887..50fb95a 100644
--- a/internal/reporting/summary.go
+++ b/internal/reporting/summary.go
@@ -1,5 +1,3 @@
-// Package reporting generates morning summary reports for nightshift runs.
-// Reports are generated as markdown and can be saved to disk or sent via notifications.
 package reporting
 
 import (
diff --git a/internal/tasks/doc.go b/internal/tasks/doc.go
new file mode 100644
index 0000000..ef657d2
--- /dev/null
+++ b/internal/tasks/doc.go
@@ -0,0 +1,22 @@
+// Package tasks defines task structures, registration, and priority-based selection.
+//
+// Tasks are the units of work that nightshift executes on projects. Each task
+// has a type, cost tier, risk level, and estimated token consumption. Tasks can
+// come from built-in definitions, custom user definitions in nightshift.yaml,
+// or external sources (td, GitHub issues).
+//
+// # Task Lifecycle
+//
+//  1. Register: Built-in tasks are registered at init time; custom tasks via
+//     RegisterCustomTasksFromConfig
+//  2. Select: The Selector picks the highest-priority tasks that fit within the
+//     remaining budget, respecting cooldowns and per-project processing limits
+//  3. Execute: Selected tasks are handed to the orchestrator for agent execution
+//
+// # Selection Criteria
+//
+// The Selector scores tasks based on priority, cost tier, cooldown status, and
+// whether the task was mentioned in claude.md/agents.md or appears in external
+// task sources. Use SelectTopN for the best N tasks or SelectRandom for a
+// single random eligible task.
+package tasks
diff --git a/internal/tasks/selector.go b/internal/tasks/selector.go
index 7a5c4d3..65f232f 100644
--- a/internal/tasks/selector.go
+++ b/internal/tasks/selector.go
@@ -1,4 +1,3 @@
-// Package tasks provides task selection and priority scoring.
 package tasks
 
 import (
diff --git a/internal/tasks/tasks.go b/internal/tasks/tasks.go
index 2c7dabb..9a8649a 100644
--- a/internal/tasks/tasks.go
+++ b/internal/tasks/tasks.go
@@ -1,5 +1,3 @@
-// Package tasks defines task structures and loading from various sources.
-// Tasks can come from GitHub issues, local files, or inline definitions.
 package tasks
 
 import (
diff --git a/internal/tmux/doc.go b/internal/tmux/doc.go
new file mode 100644
index 0000000..9873663
--- /dev/null
+++ b/internal/tmux/doc.go
@@ -0,0 +1,22 @@
+// Package tmux scrapes tmux sessions to detect running AI agent processes and
+// extract real-time usage data.
+//
+// When the tmux-based scraper is enabled (the default for calibration), this
+// package launches provider CLIs inside tmux sessions, sends the /usage command,
+// and parses the output to extract usage percentages and reset times. This
+// provides authoritative usage data that supplements or replaces local file-based
+// estimates.
+//
+// # Scraping Flow
+//
+//  1. Start a new tmux session
+//  2. Launch the provider CLI (claude or codex)
+//  3. Send the /usage command
+//  4. Capture and parse the output
+//  5. Kill the tmux session
+//
+// # Usage
+//
+// Call ScrapeClaudeUsage or ScrapeCodexUsage with a context. The returned
+// UsageResult contains the parsed weekly percentage and reset times.
+package tmux
diff --git a/internal/tmux/tmux.go b/internal/tmux/tmux.go
index ac3f263..23e9ab8 100644
--- a/internal/tmux/tmux.go
+++ b/internal/tmux/tmux.go
@@ -1,4 +1,3 @@
-// Package tmux scrapes tmux sessions to detect running AI agent processes and their usage.
 package tmux
 
 import (