diff --git a/internal/agents/claude.go b/internal/agents/claude.go
index c34d513..4f80849 100644
--- a/internal/agents/claude.go
+++ b/internal/agents/claude.go
@@ -1,3 +1,5 @@
+// Package agents provides interfaces and implementations for spawning AI agents.
+//
 // claude.go implements the Agent interface for Claude Code CLI.
 package agents
 
diff --git a/internal/agents/codex.go b/internal/agents/codex.go
index c366400..4be6886 100644
--- a/internal/agents/codex.go
+++ b/internal/agents/codex.go
@@ -1,3 +1,5 @@
+// Package agents provides interfaces and implementations for spawning AI agents.
+//
 // codex.go implements the Agent interface for OpenAI Codex CLI.
 package agents
 
diff --git a/internal/agents/copilot.go b/internal/agents/copilot.go
index fd94226..f7dce69 100644
--- a/internal/agents/copilot.go
+++ b/internal/agents/copilot.go
@@ -1,3 +1,5 @@
+// Package agents provides interfaces and implementations for spawning AI agents.
+//
 // copilot.go implements the Agent interface for GitHub Copilot CLI.
 package agents
 
diff --git a/internal/analysis/db.go b/internal/analysis/db.go
index 338641d..fb74b22 100644
--- a/internal/analysis/db.go
+++ b/internal/analysis/db.go
@@ -1,3 +1,4 @@
+// Package analysis provides code ownership and bus-factor analysis tools.
 package analysis
 
 import (
diff --git a/internal/analysis/metrics.go b/internal/analysis/metrics.go
index 91f794c..b9f0415 100644
--- a/internal/analysis/metrics.go
+++ b/internal/analysis/metrics.go
@@ -1,3 +1,4 @@
+// Package analysis provides code ownership and bus-factor analysis tools.
 package analysis
 
 import (
diff --git a/internal/analysis/report.go b/internal/analysis/report.go
index 696e77a..3a392f2 100644
--- a/internal/analysis/report.go
+++ b/internal/analysis/report.go
@@ -1,3 +1,4 @@
+// Package analysis provides code ownership and bus-factor analysis tools.
 package analysis
 
 import (
diff --git a/internal/db/import.go b/internal/db/import.go
index 0c1462b..2669c35 100644
--- a/internal/db/import.go
+++ b/internal/db/import.go
@@ -1,3 +1,4 @@
+// Package db provides SQLite-backed storage for nightshift state and snapshots.
 package db
 
 import (
diff --git a/internal/db/migrations.go b/internal/db/migrations.go
index 3b7d11e..ff55a7d 100644
--- a/internal/db/migrations.go
+++ b/internal/db/migrations.go
@@ -1,3 +1,4 @@
+// Package db provides SQLite-backed storage for nightshift state and snapshots.
 package db
 
 import (
diff --git a/internal/integrations/agentsmd.go b/internal/integrations/agentsmd.go
index 5af031b..ab16af7 100644
--- a/internal/integrations/agentsmd.go
+++ b/internal/integrations/agentsmd.go
@@ -1,3 +1,4 @@
+// Package integrations provides readers for external configuration and task sources.
 package integrations
 
 import (
diff --git a/internal/integrations/claudemd.go b/internal/integrations/claudemd.go
index 44b5ec6..8b8525d 100644
--- a/internal/integrations/claudemd.go
+++ b/internal/integrations/claudemd.go
@@ -1,3 +1,4 @@
+// Package integrations provides readers for external configuration and task sources.
 package integrations
 
 import (
diff --git a/internal/integrations/github.go b/internal/integrations/github.go
index 9cfcbe9..1210446 100644
--- a/internal/integrations/github.go
+++ b/internal/integrations/github.go
@@ -1,3 +1,4 @@
+// Package integrations provides readers for external configuration and task sources.
 package integrations
 
 import (
diff --git a/internal/integrations/td.go b/internal/integrations/td.go
index a8ed79d..259fd9e 100644
--- a/internal/integrations/td.go
+++ b/internal/integrations/td.go
@@ -1,3 +1,4 @@
+// Package integrations provides readers for external configuration and task sources.
 package integrations
 
 import (
diff --git a/internal/orchestrator/events.go b/internal/orchestrator/events.go
index 7399672..31cd66c 100644
--- a/internal/orchestrator/events.go
+++ b/internal/orchestrator/events.go
@@ -1,3 +1,4 @@
+// Package orchestrator coordinates AI agents working on tasks.
 package orchestrator
 
 import "time"
diff --git a/internal/providers/claude.go b/internal/providers/claude.go
index 3f78e89..2dab733 100644
--- a/internal/providers/claude.go
+++ b/internal/providers/claude.go
@@ -1,3 +1,5 @@
+// Package providers defines interfaces and implementations for AI coding agents.
+//
 // claude.go implements the Provider interface for Claude Code CLI.
 package providers
 
diff --git a/internal/providers/codex.go b/internal/providers/codex.go
index eb948ed..07d639b 100644
--- a/internal/providers/codex.go
+++ b/internal/providers/codex.go
@@ -1,3 +1,5 @@
+// Package providers defines interfaces and implementations for AI coding agents.
+//
 // codex.go implements the Provider interface for OpenAI Codex CLI.
 package providers
 
diff --git a/internal/providers/copilot.go b/internal/providers/copilot.go
index fe69acf..588dee9 100644
--- a/internal/providers/copilot.go
+++ b/internal/providers/copilot.go
@@ -1,3 +1,5 @@
+// Package providers defines interfaces and implementations for AI coding agents.
+//
 // copilot.go implements the Provider interface for GitHub Copilot CLI.
 package providers
 
diff --git a/internal/reporting/run_report.go b/internal/reporting/run_report.go
index 88f76a8..c942f35 100644
--- a/internal/reporting/run_report.go
+++ b/internal/reporting/run_report.go
@@ -1,3 +1,4 @@
+// Package reporting generates morning summary reports for nightshift runs.
 package reporting
 
 import (
diff --git a/internal/reporting/run_results.go b/internal/reporting/run_results.go
index 6a88a84..0895a84 100644
--- a/internal/reporting/run_results.go
+++ b/internal/reporting/run_results.go
@@ -1,3 +1,4 @@
+// Package reporting generates morning summary reports for nightshift runs.
 package reporting
 
 import (
diff --git a/internal/tasks/register.go b/internal/tasks/register.go
index 72bb586..06a7cb2 100644
--- a/internal/tasks/register.go
+++ b/internal/tasks/register.go
@@ -1,3 +1,4 @@
+// Package tasks defines task structures and loading from various sources.
 package tasks
 
 import (
diff --git a/internal/tmux/scraper.go b/internal/tmux/scraper.go
index 55f4d31..b49fad4 100644
--- a/internal/tmux/scraper.go
+++ b/internal/tmux/scraper.go
@@ -1,3 +1,4 @@
+// Package tmux scrapes tmux sessions to detect running AI agent processes and their usage.
 package tmux
 
 import (