diff --git a/scratchpad/architecture.md b/scratchpad/architecture.md
index 02c12ec4ea..976d43766b 100644
--- a/scratchpad/architecture.md
+++ b/scratchpad/architecture.md
@@ -1,71 +1,88 @@
 # Architecture Diagram
 
-> Last updated: 2026-04-30 · Source: [🏗️ Architecture Diagram: Full rebuild — gh-aw package architecture (2026-04-30)](https://github.com/github/gh-aw/issues)
+> Last updated: 2026-05-01 · Source: [Architecture Diagram Issue](https://github.com/github/gh-aw/issues)
 
 ## Overview
 
-This diagram shows the package structure and dependencies of the `gh-aw` codebase.
+This diagram shows the package structure and dependencies of the `gh-aw` codebase, organized in three layers: entry points, core packages, and utility packages.
 
 ```
-┌────────────────────────────────────────────────────────────────────────────────────────────────┐
-│                                        ENTRY POINTS                                            │
-│   ┌─────────────────────────────┐              ┌───────────────────────────────┐              │
-│   │        cmd/gh-aw            │              │       cmd/gh-aw-wasm          │              │
-│   │  Main CLI binary / cobra    │              │   WebAssembly compilation     │              │
-│   └──────────────┬──────────────┘              └───────────────────────────────┘              │
-│                  │ imports: cli, workflow, parser, console, constants                           │
-├──────────────────┼─────────────────────────────────────────────────────────────────────────────┤
-│                  ▼                       CORE PACKAGES                                         │
-│   ┌─────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐              │
-│   │       pkg/cli        │──▶│    pkg/workflow       │──▶│     pkg/parser       │              │
-│   │  Command impls for   │   │  Workflow compilation  │   │  Markdown frontmatter│              │
-│   │  compile/run/logs    │   │  engine (MD→YAML)     │   │  parsing & extraction│              │
-│   └──────┬───────────────┘   └────────┬─────────────┘   └──────────────────────┘              │
-│          │                            │                                                         │
-│          │                   ┌────────▼─────────────┐   ┌──────────────────────┐              │
-│          │                   │    pkg/actionpins     │   │    pkg/agentdrain    │              │
-│          │                   │  Action pin resolution│   │  Agent output drain  │              │
-│          └──────────────────▶│  (SHA pinning for CI) │   │  (stream multiplexer)│              │
-│                              └───────────────────────┘   └──────────────────────┘              │
-│                                                                                                 │
-│   ┌───────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐             │
-│   │     pkg/console       │   │    pkg/constants      │   │     pkg/stats        │             │
-│   │  Terminal UI formatting│   │  Shared typed consts  │   │  Numerical statistics│             │
-│   │  (success/warn/error) │   │  (engines, versions)  │   │  for metric tracking │             │
-│   └───────────────────────┘   └──────────────────────┘   └──────────────────────┘             │
-├─────────────────────────────────────────────────────────────────────────────────────────────────┤
-│                                     UTILITY PACKAGES                                            │
-│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────────┐    │
-│  │ logger │ │  tty   │ │ styles │ │ fileutil │ │ gitutil │ │stringutil│ │ sliceutil  │    │
-│  └────────┘ └────────┘ └────────┘ └──────────┘ └─────────┘ └──────────┘ └────────────┘    │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐             │
-│  │ repoutil │ │ envutil  │ │ timeutil │ │semverutil│ │ typeutil │ │  types   │             │
-│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘             │
-└─────────────────────────────────────────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
+│                                        ENTRY POINTS                                              │
+│                                                                                                  │
+│          ┌─────────────────────────────────┐       ┌──────────────────────────────────┐         │
+│          │           cmd/gh-aw             │       │         cmd/gh-aw-wasm           │         │
+│          │  Main CLI binary (gh extension) │       │  WebAssembly compilation target  │         │
+│          └────────────┬────────────────────┘       └────────────────────┬─────────────┘         │
+│                       │  imports cli, workflow,                         │                        │
+│                       │  parser, console, constants                     │                        │
+├───────────────────────┼─────────────────────────────────────────────────┼────────────────────────┤
+│                       ▼          CORE PACKAGES                          ▼                        │
+│                                                                                                  │
+│  ┌──────────────────────────┐    ┌──────────────────────────┐    ┌──────────────────────────┐   │
+│  │         pkg/cli          │──▶│       pkg/workflow        │──▶│       pkg/parser         │   │
+│  │  Command implementations │    │  Workflow compiler engine │    │  Markdown/YAML frontmatter│  │
+│  └───────────┬──────────────┘    └──────────┬───────────────┘    └──────────┬───────────────┘  │
+│              │                              │                               │                    │
+│              │       ┌──────────────────────┘                               │                    │
+│              │       │         ┌────────────────────────────────────────────┘                    │
+│              ▼       ▼         ▼                                                                  │
+│  ┌──────────────────────────┐    ┌──────────────────────────┐    ┌──────────────────────────┐   │
+│  │       pkg/console        │    │      pkg/agentdrain      │    │      pkg/actionpins      │   │
+│  │  Terminal UI formatting  │    │  Agent output streaming  │    │  Action pin resolution   │   │
+│  └───────────┬──────────────┘    └──────────────────────────┘    └──────────────────────────┘  │
+│              │                                                                                    │
+│  ┌───────────┴──────────────┐    ┌──────────────────────────┐                                   │
+│  │        pkg/stats         │    │       pkg/styles         │                                    │
+│  │   Numerical statistics   │    │   Terminal color/styles  │                                    │
+│  └──────────────────────────┘    └──────────────────────────┘                                   │
+├──────────────────────────────────────────────────────────────────────────────────────────────────┤
+│                                     UTILITY PACKAGES                                             │
+│                                                                                                  │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐  │
+│  │pkg/fileutil│  │pkg/gitutil │  │ pkg/logger │  │pkg/stringut│  │pkg/sliceutil  │ pkg/tty  │  │
+│  │File path & │  │Git repo    │  │Namespace   │  │String      │  │Slice helper│  │TTY detect│  │
+│  │operations  │  │operations  │  │debug logs  │  │utilities   │  │functions   │  │          │  │
+│  └────────────┘  └────────────┘  └────────────┘  └────────────┘  └────────────┘  └──────────┘  │
+│                                                                                                  │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐  │
+│  │pkg/constants  │pkg/repoutil│  │pkg/semverut│  │ pkg/types  │  │pkg/typeutil│  │pkg/envutil  │
+│  │Shared consts  │Repo slug & │  │Semver      │  │Shared type │  │Type convert│  │Env var   │  │
+│  │& type aliases │URL helpers │  │primitives  │  │definitions │  │utilities   │  │utilities │  │
+│  └────────────┘  └────────────┘  └────────────┘  └────────────┘  └────────────┘  └──────────┘  │
+│                                                                                                  │
+│  ┌────────────┐  ┌────────────┐                                                                  │
+│  │pkg/timeutil│  │pkg/testutil│                                                                  │
+│  │Time helpers│  │Test helpers│                                                                  │
+│  └────────────┘  └────────────┘                                                                  │
+└──────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ## Package Reference
 
 | Package | Layer | Description |
 |---------|-------|-------------|
-| cli | Core | Command implementations for compile/run/logs/audit |
-| workflow | Core | Workflow compilation engine (Markdown → GitHub Actions YAML) |
-| parser | Core | Markdown frontmatter parsing and content extraction |
-| actionpins | Core | GitHub Actions pin resolution (SHA pinning for CI) |
-| agentdrain | Core | Agent output drain / stream multiplexer |
-| console | Core | Terminal UI formatting (success/warn/error messages) |
-| constants | Core | Shared typed constants (engines, versions, job names) |
-| stats | Core | Numerical statistics for metric tracking |
-| logger | Utility | Namespace-based debug logging with zero overhead |
-| tty | Utility | TTY (terminal) detection utilities |
-| styles | Utility | Centralized style and color definitions for terminal output |
-| fileutil | Utility | File path and file operation utilities |
-| gitutil | Utility | Git repository utilities |
-| stringutil | Utility | String manipulation utilities |
-| sliceutil | Utility | Slice operation utilities |
-| repoutil | Utility | GitHub repository slug and URL utilities |
-| envutil | Utility | Environment variable reading and validation |
-| timeutil | Utility | Time utilities |
-| semverutil | Utility | Shared semantic versioning primitives |
-| typeutil | Utility | General-purpose type conversion utilities |
-| types | Utility | Shared type definitions used across packages |
+| cmd/gh-aw | Entry Point | Main CLI binary (`gh aw` extension) |
+| cmd/gh-aw-wasm | Entry Point | WebAssembly compilation target |
+| pkg/cli | Core | Command implementations (compile, run, audit, logs, mcp, etc.) |
+| pkg/workflow | Core | Workflow compiler engine — markdown→GitHub Actions YAML |
+| pkg/parser | Core | Markdown frontmatter parsing and content extraction |
+| pkg/console | Core | Terminal UI formatting (success/info/warning/error messages) |
+| pkg/agentdrain | Core | Agent output streaming and draining |
+| pkg/actionpins | Core | GitHub Actions pin resolution (SHA pinning) |
+| pkg/stats | Core | Numerical statistics utilities for metric collection |
+| pkg/styles | Core | Centralized terminal color/style definitions |
+| pkg/constants | Utility | Shared constants and semantic type aliases |
+| pkg/envutil | Utility | Environment variable reading and validation |
+| pkg/fileutil | Utility | File path and file operation utilities |
+| pkg/gitutil | Utility | Git repository operations |
+| pkg/logger | Utility | Namespace-based debug logging (zero overhead) |
+| pkg/repoutil | Utility | GitHub repository slug and URL helpers |
+| pkg/semverutil | Utility | Semantic versioning primitives |
+| pkg/sliceutil | Utility | Generic slice helper functions |
+| pkg/stringutil | Utility | String manipulation utilities |
+| pkg/timeutil | Utility | Time helper utilities |
+| pkg/tty | Utility | TTY (terminal) detection |
+| pkg/types | Utility | Shared type definitions across packages |
+| pkg/typeutil | Utility | General-purpose type conversion utilities |
+| pkg/testutil | Utility | Test helper utilities (test-only use) |