diff --git a/pkg/tty/README.md b/pkg/tty/README.md
index 4ec49c4f805..4b3304220c2 100644
--- a/pkg/tty/README.md
+++ b/pkg/tty/README.md
@@ -1,6 +1,6 @@
 # tty Package
 
-The `tty` package provides TTY (terminal) detection utilities.
+> TTY (terminal) detection utilities for stdout and stderr streams.
 
 ## Overview
 
diff --git a/pkg/types/README.md b/pkg/types/README.md
index d4ec74e13d8..2fed7402156 100644
--- a/pkg/types/README.md
+++ b/pkg/types/README.md
@@ -1,10 +1,14 @@
 # types Package
 
-The `types` package provides shared type definitions used across multiple `gh-aw` packages to avoid circular dependencies.
+> Shared type definitions for MCP server configuration, token weights, and workflow input parameters — used across multiple `gh-aw` packages to avoid circular imports.
 
 ## Overview
 
-This package defines common data structures that are shared between the `parser` and `workflow` packages. Centralizing these types here allows both packages to reference the same definitions without creating import cycles.
+This package defines common data structures shared between the `parser` and `workflow` packages. Centralizing these types in a dedicated package allows both to reference the same definitions without creating import cycles.
+
+The primary types are `BaseMCPServerConfig` (the foundation for all MCP server configurations), `MCPAuthConfig` (OIDC authentication for HTTP MCP servers), `TokenWeights` with `TokenClassWeights` (AI Credits cost ratio configuration), and `InputDefinition` (workflow dispatch input parameters following the GitHub Actions schema).
+
+All struct fields carry both `json` and `yaml` struct tags, ensuring types can be round-tripped through both serialization formats. `BaseMCPServerConfig` is designed to be embedded rather than used directly — consumer packages (`parser`, `workflow`) add domain-specific fields and validation on top of the shared base.
 
 ## Public API
 
diff --git a/pkg/typeutil/README.md b/pkg/typeutil/README.md
index e214aa7a411..5b6768a059b 100644
--- a/pkg/typeutil/README.md
+++ b/pkg/typeutil/README.md
@@ -1,11 +1,15 @@
 # typeutil Package
 
-The `typeutil` package provides general-purpose type conversion utilities for working with heterogeneous `any` values, particularly those arising from JSON and YAML parsing.
+> General-purpose type conversion utilities for heterogeneous `any` values, particularly those arising from JSON and YAML parsing.
 
 ## Overview
 
 JSON and YAML parsers produce `any` values whose concrete type varies at runtime (`int`, `float64`, `string`, etc.). This package provides safe, well-documented conversion functions that handle the common cases without requiring callers to write their own type switches.
 
+Functions are grouped into three categories: **strict conversions** (return a `(value, ok)` pair to distinguish zero from missing/invalid), **safe overflow conversions** (clamp to zero on overflow instead of panicking), and **lenient conversions** (also handle string inputs, returning zero on failure). A separate group handles token-limit strings with optional `K`/`M` multiplier suffixes.
+
+Choose the right category based on the source: use strict conversions for YAML config fields where the YAML library has already typed the value; use lenient conversions for heterogeneous sources such as JSON metrics or log-parsed data where a zero default on failure is acceptable.
+
 ## Public API
 
 ### Exported Functions
diff --git a/pkg/workflow/README.md b/pkg/workflow/README.md
index b6e157fce7b..84f5771d396 100644
--- a/pkg/workflow/README.md
+++ b/pkg/workflow/README.md
@@ -289,6 +289,14 @@ Each safe-output tool type has its own configuration struct parsed from the `saf
 | `UpdateProjectConfig` | struct | Configuration for updating GitHub Projects v2 boards |
 | `UpdatePullRequestsConfig` | struct | Configuration for updating GitHub pull requests |
 | `UpdateReleaseConfig` | struct | Configuration for updating GitHub releases |
+| `UploadArtifactConfig` | struct | Configuration for uploading GitHub Actions artifacts from agent output |
+| `ArtifactFiltersConfig` | struct | Include/exclude glob patterns for artifact file selection |
+| `ArtifactDefaultsConfig` | struct | Default request settings applied when the model omits a field (e.g. `if-no-files`) |
+| `UploadAssetsConfig` | struct | Configuration for publishing assets to an orphaned git branch |
+| `CreateCodeScanningAlertsConfig` | struct | Configuration for creating repository code scanning alerts (SARIF format) |
+| `ReplaceLabelConfig` | struct | Configuration for replacing one label with another on issues/PRs |
+| `LabelTransition` | struct | An allowed label state transition (`from` → `to` pair) |
+| `SafeScriptConfig` | struct | A custom safe-output handler script that runs inside the consolidated safe-outputs job |
 
 ### Sandbox Configuration