github · pelikhan · Apr 17, 2026 · Apr 16, 2026 · Apr 17, 2026 · Copilot
diff --git a/pkg/actionpins/README.md b/pkg/actionpins/README.md
@@ -37,6 +37,19 @@ Resolution supports two modes:
 | `ResolveActionPin` | `func(actionRepo, version string, ctx *PinContext) (string, error)` | Resolves a pinned reference with optional dynamic SHA lookup and fallback behavior |
 | `GetCachedActionPin` | `func(repo string, ctx *PinContext) string` | Returns a pinned reference preferring cache/dynamic resolution when available |
 
+## Usage Example
+
+```go
+ctx := &actionpins.PinContext{StrictMode: true}
+
+reference, err := actionpins.ResolveActionPin("actions/checkout", "v5", ctx)
+if err != nil {
+	panic(err)
+}
+
+fmt.Println(reference) // actions/checkout@<sha> # v5
-reference, err := actionpins.ResolveActionPin("actions/checkout", "v5", ctx)
-if err != nil {
-	panic(err)
-}
-
-fmt.Println(reference) // actions/checkout@<sha> # v5
+reference, err := actionpins.ResolveActionPin("actions/checkout", "v6.0.2", ctx)
+if err != nil {
+	panic(err)
+}
+if reference == "" {
+	panic("no embedded pin found for actions/checkout@v6.0.2")
+}
+
+fmt.Println(reference) // actions/checkout@<sha> # v6.0.2
-reference, err := actionpins.ResolveActionPin("actions/checkout", "v5", ctx)
-if err != nil {
-	panic(err)
-}
-
-fmt.Println(reference) // actions/checkout@<sha> # v5
+reference, err := actionpins.ResolveActionPin("actions/checkout", "v6.0.2", ctx)
+if err != nil {
+	panic(err)
+}
+if reference == "" {
+	panic("no embedded pin found for actions/checkout@v6.0.2")
+}
+
+fmt.Println(reference) // actions/checkout@<sha> # v6.0.2
+```
+
 ## Dependencies
 
 **Internal**:

diff --git a/pkg/console/README.md b/pkg/console/README.md
@@ -1,4 +1,4 @@
-# Console Package
+# console Package
 
 The `console` package provides utilities for formatting and rendering terminal output in GitHub Agentic Workflows. It covers message formatting, table and section rendering, interactive prompts, progress bars, spinners, struct rendering, and accessibility support.
 
@@ -783,3 +783,7 @@ if console.IsAccessibleMode() {
     // Use simpler, non-animated output
 }
 ```
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/envutil/README.md b/pkg/envutil/README.md
@@ -44,3 +44,7 @@ concurrency := envutil.GetIntFromEnv("GH_AW_MAX_CONCURRENT_DOWNLOADS", 5, 1, 20,
 - Warning messages use `console.FormatWarningMessage` so they render consistently in terminals.
 - All warnings go to `os.Stderr` to avoid polluting structured stdout output.
 - The function only handles integers; floating-point or string env vars should be read directly via `os.Getenv`.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/logger/README.md b/pkg/logger/README.md
@@ -1,4 +1,4 @@
-# Logger Package
+# logger Package
 
 A simple, debug-style logging framework for Go that follows the pattern matching syntax of the [debug npm package](https://www.npmjs.com/package/debug).
 
@@ -212,3 +212,7 @@ slogLogger.Warn("something unusual happened", "count", 42)
 - Colors assigned using FNV-1a hash for consistent namespace-to-color mapping
 - Color palette chosen for readability on both light and dark terminals
 - Uses ANSI 256-color codes for better compatibility
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/repoutil/README.md b/pkg/repoutil/README.md
@@ -40,3 +40,7 @@ repoutil.SplitRepoSlug("github/gh-aw/x") // error: invalid repo format: github/g
 
 - All debug output uses `logger.New("repoutil:repoutil")` and is only emitted when `DEBUG=repoutil:*`.
 - For paths that include sub-folders (e.g. GitHub Actions `uses:` fields such as `github/codeql-action/upload-sarif`), use `gitutil.ExtractBaseRepo` first to strip the sub-path before calling `SplitRepoSlug`.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/semverutil/README.md b/pkg/semverutil/README.md
@@ -101,3 +101,7 @@ semverutil.IsCompatible("v6.0.0", "v5")     // false
 - All debug output uses `logger.New("semverutil:semverutil")` and is only emitted when `DEBUG=semverutil:*`.
 - The package intentionally delegates to `golang.org/x/mod/semver` for canonical semver logic rather than implementing its own parsing.
 - `ParseVersion` uses `semver.Canonical` before splitting into components, ensuring correct handling of short forms like `v1` (canonicalized to `v1.0.0`).
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/sliceutil/README.md b/pkg/sliceutil/README.md
@@ -77,3 +77,7 @@ unique := sliceutil.Deduplicate(items)
 - `Any` is implemented via `slices.ContainsFunc` from the standard library.
 - `Deduplicate` uses a `map[T]bool` for O(n) time complexity.
 - None of these functions sort their output; callers that require sorted results should call `slices.Sort` on the returned slice.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/stats/README.md b/pkg/stats/README.md
@@ -30,6 +30,21 @@ The `stats` package provides `StatVar`, a compact accumulator for numeric metric
 | `SampleStdDev` | `func() float64` | Returns sample standard deviation |
 | `Median` | `func() float64` | Returns the exact median (middle value or midpoint of two middle values) |
 
+## Usage Example
+
+```go
+var s stats.StatVar
+
+s.Add(10)
+s.Add(20)
+s.Add(30)
+
+fmt.Println(s.Count())  // 3
+fmt.Println(s.Mean())   // 20
+fmt.Println(s.StdDev()) // 8.164965...
+fmt.Println(s.Median()) // 20
+```
+
 ## Dependencies
 
 **Standard library only**:

diff --git a/pkg/stringutil/README.md b/pkg/stringutil/README.md
@@ -177,3 +177,7 @@ Returns a human-readable description of the token type (e.g. `"fine-grained pers
 - All debug output uses namespace-prefixed loggers (`stringutil:identifiers`, `stringutil:sanitize`, `stringutil:urls`, `stringutil:pat_validation`) and is only emitted when `DEBUG=stringutil:*`.
 - `SanitizeErrorMessage` is intentionally conservative: it excludes common GitHub Actions keywords to avoid over-redacting legitimate error messages.
 - `StripANSI` handles both CSI sequences (`ESC[`) and other ESC-prefixed sequences to cover the full range of ANSI escape codes found in terminal output.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/styles/README.md b/pkg/styles/README.md
@@ -99,3 +99,7 @@ form := huh.NewForm(...).WithTheme(styles.HuhTheme)
 - The package uses `charm.land/lipgloss/v2` and `charm.land/lipgloss/v2/compat` for adaptive color support.
 - For visual examples and detailed usage guidelines, see `scratchpad/styles-guide.md`.
 - All `*` styles export pre-configured `lipgloss.Style` values (not functions), so they can be used with method chaining: `styles.Error.Copy().Underline(true)`.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/testutil/README.md b/pkg/testutil/README.md
@@ -60,3 +60,7 @@ assert.Contains(t, yaml, "runs-on: ubuntu-latest")
 - `GetTestRunDir` uses `sync.Once` so the directory is created exactly once per process even when multiple test packages run concurrently.
 - `TempDir` delegates to `os.MkdirTemp` to generate unique subdirectory names.
 - Test artifacts placed in the test run directory are outside any git repository, which prevents `git` commands executed by tests from picking them up as untracked files.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/timeutil/README.md b/pkg/timeutil/README.md
@@ -60,3 +60,7 @@ timeutil.FormatDurationNs(90_000_000_000) // "1m30s"
 - `FormatDuration` is used by the `logger` package to display time-diff between consecutive log calls (the `+500ms` suffix in debug output).
 - `FormatDurationMs` is used for workflow run duration display, where GitHub Actions reports durations in milliseconds.
 - `FormatDurationNs` is used for job duration display, where GitHub Actions reports billing durations in nanoseconds.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/types/README.md b/pkg/types/README.md
@@ -107,3 +107,7 @@ Per-token-class weights for effective token computation. Each field corresponds
 - This package has no dependencies on other `gh-aw` packages, making it safe to import from anywhere.
 - All struct fields use both `json` and `yaml` struct tags so they can be round-tripped through both serialization formats.
 - `BaseMCPServerConfig` is designed to be embedded — packages add domain-specific fields and validation on top of the shared base.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/typeutil/README.md b/pkg/typeutil/README.md
@@ -75,3 +75,7 @@ ratio := typeutil.ConvertToFloat(jsonData["ratio"])
 - All debug output uses `logger.New("typeutil:convert")` and is only emitted when `DEBUG=typeutil:*`.
 - `float64 → int` truncation is logged at debug level when the fractional part is lost.
 - `uint64 → int` overflow returns `0` rather than panicking, following the defensive convention used elsewhere in the codebase.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*
diff --git a/pkg/workflow/README.md b/pkg/workflow/README.md
@@ -194,6 +194,7 @@ The package is intentionally large (~320 source files) because it encodes all Gi
 | `GetCopilotAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Copilot-specific allowed domains |
 | `GetCodexAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Codex-specific allowed domains |
 | `GetClaudeAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Claude-specific allowed domains |
+| `GetGeminiAllowedDomainsWithToolsAndRuntimes` | `func(*NetworkPermissions, ...) string` | Gemini-specific allowed domains |
 | `GetThreatDetectionAllowedDomains` | `func(*NetworkPermissions) string` | Allowed domains for threat detection jobs |
 
 ### Error Types
@@ -240,6 +241,9 @@ The package is intentionally large (~320 source files) because it encodes all Gi
 | `GetActionPin` | `func(actionRepo string) string` | Returns the pinned SHA for an action |
 | `GetActionPinByRepo` | `func(string) (ActionPin, bool)` | Looks up a pin by repo |
 | `DetectActionMode` | `func(version string) ActionMode` | Detects the action reference mode |
+| `ParseTagRefTSV` | `func(line string) (sha, objType string, err error)` | Parses tab-separated tag ref output into SHA and object type |
+| `ExtractActionsFromLockFile` | `func(lockFilePath string) ([]ActionUsage, error)` | Extracts action usages from a lock file |
+| `CheckActionSHAUpdates` | `func(actions []ActionUsage, resolver *ActionResolver) []ActionUpdateCheck` | Checks whether action SHAs need updates |
 | `ApplyActionPinsToTypedSteps` | `func([]*WorkflowStep, *WorkflowData) []*WorkflowStep` | Applies pins to all steps |
 | `ValidateActionSHAsInLockFile` | `func(string, *ActionCache, bool) error` | Validates action SHAs in a lock file |
 
@@ -305,6 +309,8 @@ The package is intentionally large (~320 source files) because it encodes all Gi
 | `GetAWFCommandPrefix` | `func(*WorkflowData) string` | Returns the `gh aw` command prefix |
 | `WrapCommandInShell` | `func(string) string` | Wraps a command in a shell `run:` block |
 | `GetCopilotAPITarget` | `func(*WorkflowData) string` | Returns the Copilot API target URL |
+| `GetGeminiAPITarget` | `func(*WorkflowData, string) string` | Returns the Gemini API target hostname |
+| `ComputeAWFExcludeEnvVarNames` | `func(*WorkflowData, []string) []string` | Computes secret-backed env var names to exclude from AWF |
 
 ### Versioning
 
@@ -442,6 +448,10 @@ pkg/workflow ── FrontmatterConfig (typed structs)
 - `pkg/constants` — engine names, feature flags, job/step IDs
 - `pkg/console` — terminal formatting
 - `pkg/logger` — debug logging
+- `pkg/actionpins` — action pin data and pin lookup helpers
+- `pkg/semverutil` — semantic version helpers
+- `pkg/typeutil` — safe type conversions
+- `pkg/tty` — terminal capability detection
 - `pkg/stringutil`, `pkg/fileutil`, `pkg/gitutil`, `pkg/sliceutil` — utilities
 - `pkg/types` — shared MCP types