Close specification coverage gaps for actionpins/stats and sync README APIs for workflow/parser/cli

pkg/actionpins/README.md

@@ -0,0 +1,55 @@
+# actionpins Package
+
+> GitHub Action pin resolution utilities backed by embedded pin data and optional dynamic SHA resolution.
+
+## Overview
+
+The `actionpins` package resolves `uses:` references like `actions/checkout@v5` to pinned commit SHAs. It loads embedded pin metadata from `data/action_pins.json`, indexes pins by repository, and exposes helpers for formatting and resolving references.
+
+Resolution supports two modes:
+
+- Embedded-only lookup from bundled pin data
+- Dynamic lookup via a caller-provided `SHAResolver`, with fallback behavior controlled by `PinContext.StrictMode`
+
+## Public API
+
+### Types
+
+| Type | Kind | Description |
+|------|------|-------------|
+| `ActionYAMLInput` | struct | Input metadata parsed from an Action's `action.yml` |
+| `ActionPin` | struct | Pinned action entry (repo, version, SHA, optional inputs) |
+| `ActionPinsData` | struct | JSON container used to load embedded pin entries |
+| `SHAResolver` | interface | Resolves a SHA for `repo@version` dynamically |
+| `PinContext` | struct | Runtime context for resolution (resolver, strict mode, warning dedupe map) |
+
+### Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `GetActionPins` | `func() []ActionPin` | Returns all loaded pins |
+| `GetActionPinsByRepo` | `func(repo string) []ActionPin` | Returns all pins for a repository (version-descending) |
+| `GetActionPinByRepo` | `func(repo string) (ActionPin, bool)` | Returns the latest pin for a repository |
+| `FormatReference` | `func(repo, sha, version string) string` | Formats a pinned reference (`repo@sha # version`) |
+| `FormatCacheKey` | `func(repo, version string) string` | Formats a cache key (`repo@version`) |
+| `ExtractRepo` | `func(uses string) string` | Extracts the repository from a `uses` reference |
+| `ExtractVersion` | `func(uses string) string` | Extracts the version from a `uses` reference |
+| `GetActionPinWithData` | `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 |
+
+## Dependencies
+
+**Internal**:
+- `pkg/console` — warning message formatting
+- `pkg/logger` — debug logging
+- `pkg/semverutil` — semantic version compatibility checks
+
+## Thread Safety
+
+Embedded pin loading and index creation use `sync.Once`, and read access to loaded pin slices/maps is safe after initialization.
+
+`PinContext.Warnings` is mutated in place for warning deduplication; callers should not share one `PinContext` across goroutines without external synchronization.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/cli/README.md

@@ -112,6 +112,10 @@ All diagnostic output MUST go to `stderr` using `console` formatting helpers. St
 | `InspectWorkflowMCP` | `func(string, ...) error` | Inspects MCP server configurations |
 | `ListWorkflowMCP` | `func(string, bool) error` | Lists MCP server info for a workflow |
 | `UpdateActions` | `func(bool, bool, bool) error` | Bulk-updates GitHub Action versions in workflows |
+| `ActionsBuildCommand` | `func() error` | Builds all custom actions in `actions/` |
+| `ActionsValidateCommand` | `func() error` | Validates all `action.yml` files under `actions/` |
+| `ActionsCleanCommand` | `func() error` | Removes generated action build artifacts |
+| `GenerateActionMetadataCommand` | `func() error` | Generates `action.yml` and README metadata for selected action modules |
 | `UpdateWorkflows` | `func([]string, ...) error` | Updates workflows from upstream sources |
 | `RemoveWorkflows` | `func(string, bool, string) error` | Removes workflow files |
 | `ValidateWorkflowName` | `func(string) error` | Validates a workflow name identifier |

pkg/parser/README.md

@@ -147,6 +147,20 @@ The package is designed for use both in the main CLI binary and in WebAssembly c
 | `IsLabelOnlyEvent` | `func(eventValue any) bool` | Detects whether a trigger only activates on label events |
 | `IsNonConflictingCommandEvent` | `func(eventValue any) bool` | Detects whether a trigger is a non-conflicting slash command |
 
+#### Virtual Filesystem and Workflow Update Helpers
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `RegisterBuiltinVirtualFile` | `func(path string, content []byte)` | Registers embedded virtual file content under an `@builtin:` path |
+| `BuiltinVirtualFileExists` | `func(path string) bool` | Returns whether a built-in virtual file path has been registered |
+| `GetBuiltinFrontmatterCache` | `func(path string) (*FrontmatterResult, bool)` | Gets cached frontmatter parse results for built-in virtual files |
+| `SetBuiltinFrontmatterCache` | `func(path string, result *FrontmatterResult) *FrontmatterResult` | Stores a frontmatter parse result in the built-in cache |
+| `ReadFile` | `func(path string) ([]byte, error)` | Reads file content through parser virtual/builtin-aware file resolution |
+| `MergeTools` | `func(base, additional map[string]any) (map[string]any, error)` | Merges two tool configuration maps with MCP-aware conflict handling |
+| `UpdateWorkflowFrontmatter` | `func(workflowPath string, updateFunc func(frontmatter map[string]any) error, verbose bool) error` | Reads, updates, and rewrites workflow frontmatter with a callback |
+| `EnsureToolsSection` | `func(frontmatter map[string]any) map[string]any` | Ensures `tools` exists and is a map in frontmatter |
+| `QuoteCronExpressions` | `func(yamlContent string) string` | Ensures schedule cron values in YAML are quoted |
+
 ### Constants / Variables
 
 | Name | Type | Description |

pkg/stats/README.md

@@ -0,0 +1,45 @@
+# stats Package
+
+> Incremental descriptive statistics for float64 observation streams.
+
+## Overview
+
+The `stats` package provides `StatVar`, a compact accumulator for numeric metrics. It tracks count, sum, min, max, mean, variance, standard deviation, and median. Mean and variance are maintained with Welford's online algorithm, while exact median is computed from stored observations.
+
+## Public API
+
+### Types
+
+| Type | Kind | Description |
+|------|------|-------------|
+| `StatVar` | struct | Accumulates observations and exposes descriptive statistics |
+
+### `StatVar` Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Add` | `func(v float64)` | Adds one observation |
+| `Count` | `func() int` | Returns the number of observations |
+| `Sum` | `func() float64` | Returns the arithmetic sum |
+| `Min` | `func() float64` | Returns the minimum observed value (or `0` if empty) |
+| `Max` | `func() float64` | Returns the maximum observed value (or `0` if empty) |
+| `Mean` | `func() float64` | Returns the arithmetic mean (or `0` if empty) |
+| `Variance` | `func() float64` | Returns population variance (`N` denominator) |
+| `SampleVariance` | `func() float64` | Returns sample variance (`N-1` denominator) |
+| `StdDev` | `func() float64` | Returns population standard deviation |
+| `SampleStdDev` | `func() float64` | Returns sample standard deviation |
+| `Median` | `func() float64` | Returns the exact median (middle value or midpoint of two middle values) |
+
+## Dependencies
+
+**Standard library only**:
+- `math` — square root for standard deviation
+- `sort` — sorting copied values for exact median
+
+## Thread Safety
+
+`StatVar` is not concurrency-safe. Use external synchronization when a single instance is shared across goroutines.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/workflow/README.md

@@ -4,13 +4,13 @@
 
 ## Overview
 
-The `workflow` package is the compilation core of `gh-aw`. It transforms parsed markdown frontmatter (from `pkg/parser`) and markdown body text into complete GitHub Actions `.lock.yml` files. Compilation covers the full lifecycle: frontmatter parsing into strongly-typed configuration structs, multi-pass validation (schema, permissions, security, strict mode), engine-specific step generation (Copilot, Claude, Codex, custom), safe-output job construction, and final YAML serialization.
+The `workflow` package is the compilation core of `gh-aw`. It transforms parsed markdown frontmatter (from `pkg/parser`) and markdown body text into complete GitHub Actions `.lock.yml` files. Compilation covers the full lifecycle: frontmatter parsing into strongly-typed configuration structs, multi-pass validation (schema, permissions, security, strict mode), engine-specific step generation (Copilot, Claude, Codex, Gemini, custom), safe-output job construction, and final YAML serialization.
 
 The package is organized around three major subsystems:
 
 1. **Compiler** (`compiler*.go`, `compiler_types.go`): The `Compiler` struct drives the main compilation pipeline. It accepts a markdown file path (or pre-parsed `WorkflowData`), builds the full GitHub Actions workflow YAML, and writes the `.lock.yml` file only when the content has changed.
 
-2. **Engine registry** (`agentic_engine.go`, `*_engine.go`): A pluggable engine architecture where each AI engine (`copilot`, `claude`, `codex`, `custom`) implements a set of focused interfaces (`Engine`, `CapabilityProvider`, `WorkflowExecutor`, `MCPConfigProvider`, etc.). Engines are registered in a global `EngineRegistry` and looked up by name at compile time.
+2. **Engine registry** (`agentic_engine.go`, `*_engine.go`): A pluggable engine architecture where each AI engine (`copilot`, `claude`, `codex`, `gemini`, `custom`) implements a set of focused interfaces (`Engine`, `CapabilityProvider`, `WorkflowExecutor`, `MCPConfigProvider`, etc.). Engines are registered in a global `EngineRegistry` and looked up by name at compile time.
 
 3. **Validation** (`validation.go`, `strict_mode_*.go`, `*_validation.go`): A layered validation system organized by domain. Each validator is a focused file under 300 lines. Validation runs both at compile time and optionally in strict mode for production deployments.
 
@@ -67,6 +67,7 @@ The package is intentionally large (~320 source files) because it encodes all Gi
 | `CopilotEngine` | struct | Copilot coding agent engine |
 | `ClaudeEngine` | struct | Claude coding agent engine |
 | `CodexEngine` | struct | OpenAI Codex coding agent engine |
+| `GeminiEngine` | struct | Google Gemini CLI coding agent engine |
 
 #### Engine Registry Functions
 
@@ -77,6 +78,7 @@ The package is intentionally large (~320 source files) because it encodes all Gi
 | `NewCopilotEngine` | `func() *CopilotEngine` | Creates the Copilot engine |
 | `NewClaudeEngine` | `func() *ClaudeEngine` | Creates the Claude engine |
 | `NewCodexEngine` | `func() *CodexEngine` | Creates the Codex engine |
+| `NewGeminiEngine` | `func() *GeminiEngine` | Creates the Gemini engine |
 
 ### Frontmatter Configuration Types