From fdae5aca30568b96fcb117e244b279e4462273f0 Mon Sep 17 00:00:00 2001
From: Lasse Larsen <iamlasse@gmail.com>
Date: Sun, 7 Jun 2026 09:55:05 +0200
Subject: [PATCH] docs: add package-level godoc via doc.go to all 11 Go
 packages

Add canonical doc.go files with comprehensive package-level godoc to:
- cmd/nightshift/commands (CLI subcommands)
- cmd/provider-calibration (budget calibration tool)
- internal/agents (AI agent interfaces and implementations)
- internal/analysis (code ownership and bus-factor analysis)
- internal/db (SQLite storage layer)
- internal/integrations (external config and task sources)
- internal/orchestrator (agent coordination and plan-implement-review loop)
- internal/providers (usage tracking and cost estimation)
- internal/reporting (run reports and morning summaries)
- internal/tasks (task definitions and priority selection)
- internal/tmux (tmux session scraping for usage data)

Remove duplicate package comments from source files so that doc.go
is the single canonical location for package documentation.

All exported symbols already had inline godoc; no changes needed there.

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift
---
 cmd/nightshift/commands/doc.go        | 32 +++++++++++++++++++++++++++
 cmd/nightshift/commands/root.go       |  1 -
 cmd/provider-calibration/doc.go       | 15 +++++++++++++
 internal/agents/agent.go              |  2 --
 internal/agents/claude.go             |  1 -
 internal/agents/codex.go              |  1 -
 internal/agents/copilot.go            |  1 -
 internal/agents/doc.go                | 24 ++++++++++++++++++++
 internal/analysis/analyzer.go         |  1 -
 internal/analysis/doc.go              | 18 +++++++++++++++
 internal/db/db.go                     |  1 -
 internal/db/doc.go                    | 21 ++++++++++++++++++
 internal/integrations/doc.go          | 18 +++++++++++++++
 internal/integrations/integrations.go |  2 --
 internal/orchestrator/doc.go          | 25 +++++++++++++++++++++
 internal/orchestrator/orchestrator.go |  2 --
 internal/providers/claude.go          |  1 -
 internal/providers/codex.go           |  1 -
 internal/providers/copilot.go         |  1 -
 internal/providers/doc.go             | 26 ++++++++++++++++++++++
 internal/providers/provider.go        |  2 --
 internal/reporting/doc.go             | 19 ++++++++++++++++
 internal/reporting/summary.go         |  2 --
 internal/tasks/doc.go                 | 22 ++++++++++++++++++
 internal/tasks/selector.go            |  1 -
 internal/tasks/tasks.go               |  2 --
 internal/tmux/doc.go                  | 22 ++++++++++++++++++
 internal/tmux/tmux.go                 |  1 -
 28 files changed, 242 insertions(+), 23 deletions(-)
 create mode 100644 cmd/nightshift/commands/doc.go
 create mode 100644 cmd/provider-calibration/doc.go
 create mode 100644 internal/agents/doc.go
 create mode 100644 internal/analysis/doc.go
 create mode 100644 internal/db/doc.go
 create mode 100644 internal/integrations/doc.go
 create mode 100644 internal/orchestrator/doc.go
 create mode 100644 internal/providers/doc.go
 create mode 100644 internal/reporting/doc.go
 create mode 100644 internal/tasks/doc.go
 create mode 100644 internal/tmux/doc.go

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 (