diff --git a/cmd/provider-calibration/main.go b/cmd/provider-calibration/main.go
index ee573b2..c0266ac 100644
--- a/cmd/provider-calibration/main.go
+++ b/cmd/provider-calibration/main.go
@@ -1,3 +1,10 @@
+// Command provider-calibration compares Codex CLI token usage across
+// codex_originator variants to calibrate per-provider budget attribution.
+//
+// It reads recorded Codex session metrics, groups them by originator, and
+// reports the token attribution that should be applied for each provider so
+// the nightshift budget accounting stays accurate. Run via `make
+// calibrate-providers`.
 package main
 
 import (
diff --git a/internal/security/security.go b/internal/security/security.go
index 1166e57..78e699f 100644
--- a/internal/security/security.go
+++ b/internal/security/security.go
@@ -237,7 +237,7 @@ func ValidateProjectPath(path string) error {
 	return nil
 }
 
-// Operation types for safety checks.
+// OperationType categorizes an operation performed by an agent for safety checks.
 type OperationType string
 
 const (