docs: fix spec audit — add Public API, Usage Examples, and Dependencies to 17 packages (#30155)

Author: Copilot

.github/workflows/daily-model-inventory.lock.yml

@@ -10,7 +10,9 @@ In GitHub Agentic Workflows, `agentdrain` processes `AgentEvent` records emitted
 1. Build a model of normal behavior by training on events from successful runs.
 2. Detect anomalies in new runs by comparing events against the learned model.
 
-## Types
+## Public API
+
+### Types
 
 ### `Config`
 
@@ -95,7 +97,7 @@ type AnomalyReport struct {
 }
 ```
 
-## Core Components
+### Core Components
 
 ### `Miner`
 
@@ -210,6 +212,45 @@ type SnapshotCluster struct {
 
 These types are returned and consumed by `SaveSnapshots` / `LoadSnapshots` and are serialized as JSON.
 
+## Usage Examples
+
+```go
+import "github.com/github/gh-aw/pkg/agentdrain"
+
+// Create a coordinator with default config
+cfg := agentdrain.DefaultConfig()
+stages := []string{"plan", "tool_call", "finish"}
+coord, err := agentdrain.NewCoordinator(cfg, stages)
+if err != nil {
+    panic(err)
+}
+
+// Load pre-trained weights
+if err := coord.LoadDefaultWeights(); err != nil {
+    panic(err)
+}
+
+// Analyze an incoming agent event
+evt := agentdrain.AgentEvent{
+    Stage:  "tool_call",
+    Fields: map[string]string{"tool": "read_file", "path": "/workspace/main.go"},
+}
+result, report, err := coord.AnalyzeEvent(evt)
+if err != nil {
+    panic(err)
+}
+if report.IsNewTemplate {
+    fmt.Printf("New behavior pattern detected (score=%.2f): %s\n",
+        report.AnomalyScore, report.Reason)
+}
+```
+
+## Dependencies
+
+**Internal**:
+- `pkg/logger` — debug logging
+- `pkg/sliceutil` — slice utilities for cluster management
+
 ## Default Weights
 
 The package embeds a set of default trained weights (in `data/`) via `//go:embed`. Call `coord.LoadDefaultWeights()` to initialize the coordinator with pre-trained cluster weights rather than starting cold.

pkg/agentdrain/README.md

@@ -446,6 +446,15 @@ err := cli.RunHealth(cli.HealthConfig{
 - `pkg/console` — terminal output formatting
 - `pkg/logger` — structured debug logging
 - `pkg/constants` — engine names, job names, feature flags
+- `pkg/agentdrain` — Drain log anomaly detection for audit analysis
+- `pkg/envutil` — environment variable reading with bounds validation
+- `pkg/semverutil` — semantic version comparison for dependency checks
+- `pkg/sliceutil` — slice utilities
+- `pkg/stats` — incremental statistics for health metrics
+- `pkg/styles` — terminal color styles and lipgloss configuration
+- `pkg/timeutil` — human-readable duration formatting
+- `pkg/tty` — terminal detection
+- `pkg/types` — shared MCP server configuration types
 - `pkg/stringutil`, `pkg/fileutil`, `pkg/gitutil`, `pkg/repoutil` — utilities
 
 **External**:

pkg/cli/README.md

@@ -31,6 +31,33 @@ This package follows Charmbracelet best practices for terminal UI:
 - **Boxes**: 2 character horizontal padding, 0-1 vertical padding
 - **Info sections**: 2 character left padding for consistent indentation
 
+## Public API
+
+The following components and functions are exported by the `console` package:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `NewSpinner` | func | Creates a new animated spinner |
+| `NewProgressBar` | func | Creates a determinate progress bar |
+| `NewIndeterminateProgressBar` | func | Creates an indeterminate progress bar |
+| `RenderStruct` | func | Renders a Go struct to a styled terminal string |
+| `RenderTable` | func | Renders a formatted table string |
+| `RenderTree` | func | Renders a tree-node hierarchy |
+| `RenderTitleBox` / `RenderErrorBox` / `RenderInfoSection` | funcs | Section rendering helpers |
+| `RenderComposedSections` | func | Composes and prints multiple sections |
+| `FormatSuccessMessage` / `FormatInfoMessage` / `FormatWarningMessage` / `FormatErrorMessage` | funcs | Styled status message formatting |
+| `FormatCommandMessage` / `FormatProgressMessage` / `FormatVerboseMessage` | funcs | Additional message styles |
+| `FormatError` | func | Renders a structured `CompilerError` with context |
+| `FormatErrorChain` | func | Renders a wrapped-error chain |
+| `FormatErrorWithSuggestions` | func | Error message with actionable suggestions |
+| `ConfirmAction` | func | Interactive yes/no confirmation |
+| `ShowInteractiveList` | func | Interactive single-selection list |
+| `PromptInput` / `PromptSecretInput` | funcs | Text and secret input prompts |
+| `LogVerbose` | func | Conditional verbose logging |
+| `FormatFileSize` / `FormatNumber` | funcs | Human-readable byte and integer formatting |
+| `IsAccessibleMode` | func | Detects accessibility mode |
+| `CompilerError` / `ErrorPosition` / `TableConfig` / `TreeNode` | types | Supporting data types |
+
 ## Spinner Component
 
 The `Spinner` component provides animated visual feedback during long-running operations with automatic TTY detection and accessibility support.
@@ -794,6 +821,59 @@ if console.IsAccessibleMode() {
 }
 ```
 
+## Usage Examples
+
+```go
+import (
+    "fmt"
+    "os"
+    "github.com/github/gh-aw/pkg/console"
+)
+
+// Display a spinner during a long-running operation
+spinner := console.NewSpinner("Compiling workflows...")
+spinner.Start()
+// ... do work ...
+spinner.StopWithMessage("✓ Done!")
+
+// Format status messages (always write to stderr)
+fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Workflow compiled successfully"))
+fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Processing 3 files..."))
+fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Network access is unrestricted"))
+fmt.Fprintln(os.Stderr, console.FormatErrorMessage("File not found: workflow.md"))
+
+// Render a table
+table := console.RenderTable(console.TableConfig{
+    Headers: []string{"Name", "Status"},
+    Rows: [][]string{
+        {"build", "success"},
+        {"test", "failure"},
+    },
+    Title: "Job Results",
+})
+fmt.Print(table)
+
+// Interactive confirmation
+confirmed, err := console.ConfirmAction("Delete all compiled workflows?", "Yes, delete", "Cancel")
+if err != nil || !confirmed {
+    return
+}
+```
+
+## Dependencies
+
+**Internal**:
+- `pkg/logger` — debug-level console logging
+- `pkg/styles` — adaptive color constants and pre-configured lipgloss styles
+- `pkg/tty` — terminal detection for spinner and progress bar
+
+**External**:
+- `charm.land/lipgloss/v2` — terminal styling and layout
+- `charm.land/bubbles/v2/spinner` — spinner animation
+- `charm.land/bubbles/v2/progress` — progress bar
+- `charm.land/bubbletea/v2` — terminal UI event loop
+- `charm.land/huh/v2` — interactive form components
+
 ---
 
 *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/console/README.md

@@ -16,7 +16,9 @@ The package is organized into focused files:
 | `url_constants.go` | URL semantic types, well-known URLs, documentation URLs |
 | `version_constants.go` | Default version strings and minimum version constraints |
 
-## Semantic Types
+## Public API
+
+### Semantic Types
 
 The package uses typed aliases to prevent mixing unrelated string or integer values:
 
@@ -441,6 +443,39 @@ constants.DefaultGitHubTools              // deprecated: use DefaultGitHubToolsL
 constants.DefaultBashTools
 ```
 
+## Usage Examples
+
+```go
+import "github.com/github/gh-aw/pkg/constants"
+
+// Engine constants
+engine := constants.CopilotEngine // EngineName("copilot")
+fmt.Println(engine.String())      // "copilot"
+fmt.Println(engine.IsValid())     // true
+
+// Resolve an engine option for display and secret info
+opt := constants.GetEngineOption("copilot")
+fmt.Println(opt.Label)      // "GitHub Copilot"
+fmt.Println(opt.SecretName) // "COPILOT_GITHUB_TOKEN"
+
+// Version constants
+fmt.Println(constants.DefaultCopilotVersion)
+
+// Feature flags
+fmt.Println(constants.MCPGatewayFeatureFlag.String()) // "mcp-gateway"
+
+// Job / step IDs
+fmt.Println(constants.AgentJobName.String())          // "agent"
+fmt.Println(constants.CheckMembershipStepID.String()) // "check_membership"
+
+// Runtime paths
+fmt.Println(constants.GhAwRootDir)       // "${{ runner.temp }}/gh-aw"
+fmt.Println(constants.GhAwRootDirShell)  // "${RUNNER_TEMP}/gh-aw"
+
+// Dynamic workflow directory (respects GH_AW_WORKFLOWS_DIR)
+dir := constants.GetWorkflowDir() // ".github/workflows"
+```
+
 ## Design Notes
 
 - All semantic types implement `String()` and `IsValid()` to allow consistent validation across the codebase.

pkg/constants/README.md

@@ -6,9 +6,21 @@ The `envutil` package provides utilities for reading and validating environment
 
 This package centralizes the pattern of reading integer-valued environment variables, validating them against configured minimum and maximum bounds, and falling back to a default value when the variable is absent or out of range. It emits warning messages to stderr when an invalid value is encountered, following the console formatting conventions of the rest of the codebase.
 
-## Usage
+## Public API
 
-### GetIntFromEnv
+### `GetIntFromEnv(envVar string, defaultValue, minValue, maxValue int, log *logger.Logger) int`
+
+Reads an integer-valued environment variable, validates it against `[minValue, maxValue]`, and returns `defaultValue` when the variable is absent, unparseable, or out of range. A warning is emitted to `os.Stderr` when the value is invalid.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `envVar` | `string` | Environment variable name (e.g. `"GH_AW_TIMEOUT"`) |
+| `defaultValue` | `int` | Value returned when env var is absent or invalid |
+| `minValue` | `int` | Minimum allowed value (inclusive) |
+| `maxValue` | `int` | Maximum allowed value (inclusive) |
+| `log` | `*logger.Logger` | Optional logger for debug output; pass `nil` to disable |
+
+## Usage Examples
 
 ```go
 import (
@@ -20,24 +32,22 @@ var log = logger.New("mypackage:config")
 
 // Read GH_AW_MAX_CONCURRENT_DOWNLOADS, constrained to [1, 20], default 5
 concurrency := envutil.GetIntFromEnv("GH_AW_MAX_CONCURRENT_DOWNLOADS", 5, 1, 20, log)
+
+// Suppress debug output by passing nil logger
+timeout := envutil.GetIntFromEnv("GH_AW_TIMEOUT", 60, 1, 3600, nil)
 ```
 
 **Behavior**:
 - Returns `defaultValue` when the environment variable is not set.
 - Returns `defaultValue` and emits a warning when the value cannot be parsed as an integer.
 - Returns `defaultValue` and emits a warning when the value is outside `[minValue, maxValue]`.
 - Logs the accepted value at debug level when `log` is non-nil.
-- Pass `nil` for `log` to suppress debug output.
 
-### Parameters
+## Dependencies
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `envVar` | `string` | Environment variable name (e.g. `"GH_AW_TIMEOUT"`) |
-| `defaultValue` | `int` | Value returned when env var is absent or invalid |
-| `minValue` | `int` | Minimum allowed value (inclusive) |
-| `maxValue` | `int` | Maximum allowed value (inclusive) |
-| `log` | `*logger.Logger` | Optional logger for debug output; pass `nil` to disable |
+**Internal**:
+- `pkg/console` — warning message formatting
+- `pkg/logger` — debug logging
 
 ## Design Notes
 

pkg/envutil/README.md

@@ -6,7 +6,7 @@ The `fileutil` package provides utility functions for safe file path validation
 
 This package focuses on security-conscious file handling: path validation, boundary enforcement, and straightforward file/directory operations. It also provides a cross-platform tar extraction helper.
 
-## Functions
+## Public API
 
 ### Path Validation
 
@@ -83,6 +83,33 @@ if err != nil {
 }
 ```
 
+## Usage Examples
+
+```go
+import "github.com/github/gh-aw/pkg/fileutil"
+
+// Validate and clean a user-supplied path
+cleanPath, err := fileutil.ValidateAbsolutePath(userInput)
+if err != nil {
+    return fmt.Errorf("invalid path: %w", err)
+}
+
+// Ensure output path stays within workspace
+if err := fileutil.MustBeWithin("/workspace", outputPath); err != nil {
+    return fmt.Errorf("output path escapes workspace: %w", err)
+}
+
+// Copy a file
+if err := fileutil.CopyFile("source.txt", "destination.txt"); err != nil {
+    return fmt.Errorf("copy failed: %w", err)
+}
+```
+
+## Dependencies
+
+**Internal**:
+- `pkg/logger` — debug logging
+
 ## Design Notes
 
 - All debug output uses `logger.New("fileutil:fileutil")` and `logger.New("fileutil:tar")` and is only emitted when `DEBUG=fileutil:*`.

pkg/fileutil/README.md

@@ -11,7 +11,7 @@ This package contains helpers for:
 - Finding the root directory of the current Git repository.
 - Reading file contents from the `HEAD` commit.
 
-## Functions
+## Public API
 
 ### Error Classification
 
@@ -88,6 +88,36 @@ root, _ := gitutil.FindGitRoot()
 content, err := gitutil.ReadFileFromHEADWithRoot("pkg/workflow/compiler.go", root)
 ```
 
+## Usage Examples
+
+```go
+import "github.com/github/gh-aw/pkg/gitutil"
+
+// Check for rate-limit errors from GitHub API
+if gitutil.IsRateLimitError(err.Error()) {
+    // Back off and retry
+}
+
+// Validate a commit SHA
+if gitutil.IsValidFullSHA(commitSHA) {
+    fmt.Println("Valid 40-character commit SHA")
+}
+
+// Find the git repository root
+root, err := gitutil.FindGitRoot()
+if err != nil {
+    return fmt.Errorf("not in a git repository: %w", err)
+}
+
+// Read a file from the HEAD commit
+content, err := gitutil.ReadFileFromHEADWithRoot("go.mod", root)
+```
+
+## Dependencies
+
+**Internal**:
+- `pkg/logger` — debug logging
+
 ## Design Notes
 
 - All debug output uses `logger.New("gitutil:gitutil")` and is only emitted when `DEBUG=gitutil:*`.