diff --git a/actions/setup/js/create_pull_request.cjs b/actions/setup/js/create_pull_request.cjs
index ce35dd07a7..8685d7e01b 100644
--- a/actions/setup/js/create_pull_request.cjs
+++ b/actions/setup/js/create_pull_request.cjs
@@ -82,9 +82,7 @@ async function main(config = {}) {
   }
 
   // Extract triggering issue number from context (for auto-linking PRs to issues)
-  const triggeringIssueNumber = context.payload?.issue?.number && !context.payload?.issue?.pull_request
-    ? context.payload.issue.number
-    : undefined;
+  const triggeringIssueNumber = context.payload?.issue?.number && !context.payload?.issue?.pull_request ? context.payload.issue.number : undefined;
 
   // Check if we're in staged mode
   const isStaged = process.env.GH_AW_SAFE_OUTPUTS_STAGED === "true";
diff --git a/pkg/workflow/mcp_config_builtin.go b/pkg/workflow/mcp_config_builtin.go
index 1031078f5d..06ba45d479 100644
--- a/pkg/workflow/mcp_config_builtin.go
+++ b/pkg/workflow/mcp_config_builtin.go
@@ -1,3 +1,99 @@
+// Package workflow provides built-in MCP server configuration rendering.
+//
+// # Built-in MCP Servers
+//
+// This file implements rendering functions for gh-aw's built-in MCP servers:
+// safe-outputs, agentic-workflows, and their variations. These servers provide
+// core functionality for AI agent workflows including controlled output storage,
+// workflow execution, and memory management.
+//
+// Key responsibilities:
+//   - Rendering safe-outputs MCP server configuration (HTTP transport)
+//   - Rendering agentic-workflows MCP server configuration (stdio transport)
+//   - Engine-specific format handling (JSON vs TOML)
+//   - Managing HTTP server endpoints and authentication
+//   - Configuring Docker containers for stdio servers
+//   - Handling environment variable passthrough
+//
+// Built-in MCP servers:
+//
+// 1. Safe-outputs MCP server:
+//   - Transport: HTTP (runs on host, accessed via HTTP)
+//   - Port: 3001 (configurable via GH_AW_SAFE_OUTPUTS_PORT)
+//   - Authentication: API key in Authorization header
+//   - Purpose: Provides controlled storage for AI agent outputs
+//   - Tools: add_issue_comment, create_issue, update_issue, upload_asset, etc.
+//
+// 2. Agentic-workflows MCP server:
+//   - Transport: stdio (runs in Docker container)
+//   - Container: Alpine Linux with gh-aw binary mounted
+//   - Entrypoint: /opt/gh-aw/gh-aw mcp-server
+//   - Purpose: Enables workflow compilation, validation, and execution
+//   - Tools: compile, validate, list, status, run, etc.
+//
+// HTTP vs stdio transport:
+// - HTTP: Server runs on host, accessible via HTTP URL with authentication
+// - stdio: Server runs in Docker container, communicates via stdin/stdout
+//
+// Engine compatibility:
+// The renderer supports multiple output formats:
+//   - JSON (Copilot, Claude, Custom): JSON-like MCP configuration
+//   - TOML (Codex): TOML-like MCP configuration
+//
+// Copilot-specific features:
+// When IncludeCopilotFields is true, the renderer adds:
+//   - "type" field: Specifies transport type (http or stdio)
+//   - Backslash-escaped variables: \${VAR} for MCP passthrough
+//
+// Safe-outputs configuration:
+// Safe-outputs runs as an HTTP server and requires:
+//   - Port and API key from step outputs
+//   - Config files: config.json, tools.json, validation.json
+//   - Environment variables for feature configuration
+//
+// The HTTP URL uses either:
+//   - host.docker.internal: When agent runs in firewall container
+//   - localhost: When agent firewall is disabled (sandbox.agent.disabled)
+//
+// Agentic-workflows configuration:
+// Agentic-workflows runs in a stdio container and requires:
+//   - Mounted gh-aw binary from /opt/gh-aw
+//   - Mounted workspace for workflow files
+//   - Mounted temp directory for logs
+//   - GITHUB_TOKEN for GitHub API access
+//
+// Related files:
+//   - mcp_renderer.go: Main renderer that calls these functions
+//   - mcp_setup_generator.go: Generates setup steps for these servers
+//   - safe_outputs.go: Safe-outputs configuration and validation
+//   - safe_inputs.go: Safe-inputs configuration (similar pattern)
+//
+// Example safe-outputs config:
+//
+//	{
+//	  "safe_outputs": {
+//	    "type": "http",
+//	    "url": "http://host.docker.internal:$GH_AW_SAFE_OUTPUTS_PORT",
+//	    "headers": {
+//	      "Authorization": "$GH_AW_SAFE_OUTPUTS_API_KEY"
+//	    }
+//	  }
+//	}
+//
+// Example agentic-workflows config:
+//
+//	{
+//	  "agentic_workflows": {
+//	    "type": "stdio",
+//	    "container": "alpine:3.20",
+//	    "entrypoint": "/opt/gh-aw/gh-aw",
+//	    "entrypointArgs": ["mcp-server"],
+//	    "mounts": ["/opt/gh-aw:/opt/gh-aw:ro", ...],
+//	    "env": {
+//	      "GITHUB_TOKEN": "$GITHUB_TOKEN"
+//	    }
+//	  }
+//	}
 package workflow
 
 import (
diff --git a/pkg/workflow/mcp_config_playwright_renderer.go b/pkg/workflow/mcp_config_playwright_renderer.go
index 66b6ecfef1..1b656798a9 100644
--- a/pkg/workflow/mcp_config_playwright_renderer.go
+++ b/pkg/workflow/mcp_config_playwright_renderer.go
@@ -1,3 +1,62 @@
+// Package workflow provides Playwright MCP server configuration and Docker setup.
+//
+// # Playwright MCP Server
+//
+// This file handles the configuration and rendering of the Playwright MCP server,
+// which provides AI agents with browser automation capabilities through the
+// Model Context Protocol (MCP). Playwright enables agents to interact with
+// web pages, take screenshots, extract content, and perform accessibility testing.
+//
+// Key responsibilities:
+//   - Generating Playwright MCP server configuration
+//   - Managing Docker container setup for Playwright
+//   - Handling allowed domains for browser navigation
+//   - Processing custom Playwright arguments
+//   - Extracting and managing domain secrets from expressions
+//   - Rendering configuration for different AI engines
+//
+// Container configuration:
+// Playwright runs in a Docker container using the official Microsoft Playwright
+// MCP image (mcr.microsoft.com/playwright/mcp). The container is configured with:
+//   - --init flag for proper signal handling
+//   - --network host for network access
+//   - Volume mounts for log storage
+//   - Output directory for screenshots and artifacts
+//
+// Domain restrictions:
+// For security, Playwright is restricted to specific allowed domains configured
+// in the workflow frontmatter. These domains are passed via:
+//   - --allowed-hosts: Domains the browser can navigate to
+//   - --allowed-origins: Domains that can be used as origins
+//
+// Expression handling:
+// When allowed_domains contains GitHub Actions expressions like ${{ secrets.DOMAIN }},
+// these are extracted and made available as environment variables. The actual
+// secret values are resolved at runtime and passed to the Playwright container.
+//
+// Engine compatibility:
+// The renderer supports multiple AI engines with engine-specific formatting:
+//   - Copilot: Includes "type" field, inline args
+//   - Claude/Custom: Multi-line args, simplified format
+//   - All engines: Same core configuration structure
+//
+// Related files:
+//   - mcp_playwright_config.go: Playwright configuration types and parsing
+//   - mcp_renderer.go: Main MCP renderer that calls this function
+//   - mcp_setup_generator.go: Includes Playwright in setup sequence
+//
+// Example configuration:
+//
+//	tools:
+//	  playwright:
+//	    version: v1.41.0
+//	    allowed_domains:
+//	      - github.com
+//	      - api.github.com
+//	      - ${{ secrets.CUSTOM_DOMAIN }}
+//	    custom_args:
+//	      - --debug
+//	      - --timeout=30000
 package workflow
 
 import (
diff --git a/pkg/workflow/mcp_config_utils.go b/pkg/workflow/mcp_config_utils.go
index 9681052006..b971474fdf 100644
--- a/pkg/workflow/mcp_config_utils.go
+++ b/pkg/workflow/mcp_config_utils.go
@@ -1,3 +1,45 @@
+// Package workflow provides utility functions for MCP configuration processing.
+//
+// # MCP Configuration Utilities
+//
+// This file contains helper functions for processing and transforming MCP
+// configuration data during workflow compilation. These utilities handle
+// common operations needed across different MCP server types.
+//
+// Key functionality:
+//   - URL rewriting for Docker networking
+//   - Localhost to host.docker.internal translation
+//
+// URL rewriting:
+// When MCP servers run on the host machine (like safe-outputs HTTP server
+// on port 3001) but need to be accessed from within a Docker container
+// (like the firewall container running the AI agent), localhost URLs must
+// be rewritten to use host.docker.internal.
+//
+// This ensures that containerized AI agents can communicate with MCP servers
+// running on the host system while maintaining network isolation.
+//
+// Supported URL patterns:
+//   - http://localhost:port → http://host.docker.internal:port
+//   - https://localhost:port → https://host.docker.internal:port
+//   - http://127.0.0.1:port → http://host.docker.internal:port
+//   - https://127.0.0.1:port → https://host.docker.internal:port
+//
+// Use cases:
+//   - Safe-outputs HTTP server accessed from firewall container
+//   - Safe-inputs HTTP server accessed from firewall container
+//   - Custom HTTP MCP servers on localhost
+//
+// Related files:
+//   - mcp_renderer.go: Uses URL rewriting for HTTP MCP servers
+//   - safe_outputs.go: Safe outputs HTTP server configuration
+//   - safe_inputs.go: Safe inputs HTTP server configuration
+//
+// Example:
+//
+//	// Before: http://localhost:3001
+//	// After:  http://host.docker.internal:3001
+//	url := rewriteLocalhostToDockerHost("http://localhost:3001")
 package workflow
 
 import (
diff --git a/pkg/workflow/mcp_environment.go b/pkg/workflow/mcp_environment.go
index f92c1948a6..7a32811377 100644
--- a/pkg/workflow/mcp_environment.go
+++ b/pkg/workflow/mcp_environment.go
@@ -1,3 +1,48 @@
+// Package workflow provides environment variable management for MCP server execution.
+//
+// # MCP Environment Variables
+//
+// This file is responsible for collecting and managing all environment variables
+// required by MCP servers during workflow execution. Environment variables are
+// used to pass configuration, authentication tokens, and runtime settings to
+// MCP servers running in the gateway.
+//
+// Key responsibilities:
+//   - Collecting MCP-related environment variables from workflow configuration
+//   - Managing GitHub MCP server tokens (custom, default, and GitHub App tokens)
+//   - Handling safe-outputs and safe-inputs environment variables
+//   - Processing Playwright domain secrets
+//   - Extracting secrets from HTTP MCP server headers
+//   - Managing agentic-workflows GITHUB_TOKEN
+//
+// Environment variable categories:
+//   - GitHub MCP: GITHUB_MCP_SERVER_TOKEN, GITHUB_MCP_LOCKDOWN
+//   - Safe Outputs: GH_AW_SAFE_OUTPUTS_*, GH_AW_ASSETS_*
+//   - Safe Inputs: GH_AW_SAFE_INPUTS_PORT, GH_AW_SAFE_INPUTS_API_KEY
+//   - Serena: GH_AW_SERENA_PORT (local mode only)
+//   - Playwright: Domain secrets from allowed_domains expressions
+//   - HTTP MCP: Custom secrets from headers and env sections
+//
+// Token precedence for GitHub MCP:
+//  1. GitHub App token (if app configuration exists)
+//  2. Custom github-token from tool configuration
+//  3. Top-level github-token from frontmatter
+//  4. Default GITHUB_TOKEN secret
+//
+// The environment variables collected here are passed to both the
+// "Start MCP gateway" step and the "MCP Gateway" step to ensure
+// MCP servers have access to necessary configuration and secrets.
+//
+// Related files:
+//   - mcp_setup_generator.go: Uses collected env vars in gateway setup
+//   - mcp_github_config.go: GitHub-specific token and configuration
+//   - safe_outputs.go: Safe outputs configuration
+//   - safe_inputs.go: Safe inputs configuration
+//
+// Example usage:
+//
+//	envVars := collectMCPEnvironmentVariables(tools, mcpTools, workflowData, hasAgenticWorkflows)
+//	// Returns map[string]string with all required environment variables
 package workflow
 
 import (
diff --git a/pkg/workflow/mcp_gateway_config.go b/pkg/workflow/mcp_gateway_config.go
index 5854455678..9f188b3ac0 100644
--- a/pkg/workflow/mcp_gateway_config.go
+++ b/pkg/workflow/mcp_gateway_config.go
@@ -1,3 +1,48 @@
+// Package workflow provides MCP gateway configuration management for agentic workflows.
+//
+// # MCP Gateway Configuration
+//
+// The MCP gateway acts as a proxy between AI engines and MCP servers, providing
+// protocol translation, connection management, and security features. This file
+// handles the configuration and setup of the MCP gateway for workflow execution.
+//
+// Key responsibilities:
+//   - Setting default MCP gateway container and version
+//   - Ensuring gateway configuration exists with sensible defaults
+//   - Building gateway configuration for MCP config files
+//   - Managing gateway port, domain, and API key settings
+//
+// The gateway configuration includes:
+//   - Container image and version (defaults to githubnext/gh-aw-mcpg)
+//   - Network port (default: 80)
+//   - Domain for gateway access (localhost or host.docker.internal)
+//   - API key for authentication
+//   - Volume mounts for workspace and temporary directories
+//
+// Configuration flow:
+//  1. ensureDefaultMCPGatewayConfig: Sets defaults if not provided
+//  2. buildMCPGatewayConfig: Builds gateway config for MCP files
+//  3. isSandboxDisabled: Checks if sandbox features are disabled
+//
+// When sandbox is disabled (sandbox: false), the gateway is skipped entirely
+// and MCP servers communicate directly without the gateway proxy.
+//
+// Related files:
+//   - mcp_gateway_constants.go: Gateway version and container constants
+//   - mcp_setup_generator.go: Setup step generation with gateway startup
+//   - mcp_renderer.go: YAML rendering for MCP configurations
+//
+// Example gateway configuration:
+//
+//	sandbox:
+//	  mcp:
+//	    container: githubnext/gh-aw-mcpg
+//	    version: v0.0.12
+//	    port: 80
+//	    domain: host.docker.internal
+//	    mounts:
+//	      - /opt:/opt:ro
+//	      - /tmp:/tmp:rw
 package workflow
 
 import (
diff --git a/pkg/workflow/mcp_gateway_constants.go b/pkg/workflow/mcp_gateway_constants.go
index 94923e0266..fb93a270fb 100644
--- a/pkg/workflow/mcp_gateway_constants.go
+++ b/pkg/workflow/mcp_gateway_constants.go
@@ -1,3 +1,33 @@
+// Package workflow provides constants for MCP gateway configuration.
+//
+// # MCP Gateway Constants
+//
+// This file defines default values and constants used by the MCP gateway
+// throughout the workflow compilation process. These constants ensure
+// consistent configuration across different components.
+//
+// Gateway default values:
+//   - Port: 80 (HTTP standard port)
+//
+// The MCP gateway port is used when:
+//   - No custom port is specified in sandbox.mcp.port
+//   - Building gateway configuration in mcp_gateway_config.go
+//   - Generating gateway startup commands in mcp_setup_generator.go
+//
+// Historical note:
+// This constant was originally used with the awmg gateway binary.
+// The binary has been removed but the constant is retained for
+// backwards compatibility with existing workflow configurations.
+//
+// Related files:
+//   - mcp_gateway_config.go: Uses DefaultMCPGatewayPort for configuration
+//   - mcp_setup_generator.go: Uses port for gateway startup
+//   - constants/constants.go: Other MCP-related constants (versions, containers)
+//
+// Related constants in pkg/constants:
+//   - DefaultMCPGatewayVersion: Gateway container version
+//   - DefaultMCPGatewayContainer: Gateway container image
+//   - DefaultGitHubMCPServerVersion: GitHub MCP server version
 package workflow
 
 const (
diff --git a/pkg/workflow/mcp_github_config.go b/pkg/workflow/mcp_github_config.go
index 017c927092..20d8bb6441 100644
--- a/pkg/workflow/mcp_github_config.go
+++ b/pkg/workflow/mcp_github_config.go
@@ -1,3 +1,67 @@
+// Package workflow provides GitHub MCP server configuration and toolset management.
+//
+// # GitHub MCP Server Configuration
+//
+// This file manages the configuration of the GitHub MCP server, which provides
+// AI agents with access to GitHub's API through the Model Context Protocol (MCP).
+// It handles both local (Docker-based) and remote (hosted) deployment modes.
+//
+// Key responsibilities:
+//   - Extracting GitHub tool configuration from workflow frontmatter
+//   - Managing GitHub MCP server modes (local Docker vs remote hosted)
+//   - Handling GitHub authentication tokens (custom, default, GitHub App)
+//   - Managing read-only and lockdown security modes
+//   - Expanding and managing GitHub toolsets (repos, issues, pull_requests, etc.)
+//   - Handling allowed tool lists for fine-grained access control
+//   - Determining Docker image versions for local mode
+//   - Generating automatic lockdown detection steps
+//   - Managing GitHub App token minting and invalidation
+//
+// GitHub MCP modes:
+//   - Local (default): Runs GitHub MCP server in Docker container
+//   - Remote: Uses hosted GitHub MCP service
+//
+// Security features:
+//   - Read-only mode: Prevents write operations (default: true)
+//   - Lockdown mode: Restricts access to current repository only
+//   - Automatic lockdown: Enables lockdown for private repositories
+//   - Allowed tools: Restricts available GitHub API operations
+//
+// GitHub toolsets:
+//   - default/action-friendly: Standard toolsets safe for GitHub Actions
+//   - repos, issues, pull_requests, discussions, search, code_scanning
+//   - secret_scanning, labels, releases, milestones, projects, gists
+//   - teams, actions, packages (requires specific permissions)
+//   - users (excluded from action-friendly due to token limitations)
+//
+// Token precedence:
+//  1. GitHub App token (minted from app configuration)
+//  2. Custom github-token from tool configuration
+//  3. Top-level github-token from frontmatter
+//  4. Default GITHUB_TOKEN secret
+//
+// Automatic lockdown detection:
+// When lockdown is not explicitly set, a step is generated to automatically
+// enable lockdown for private repositories while keeping it disabled for
+// public repositories. This provides security by default without hindering
+// open source workflows.
+//
+// Related files:
+//   - mcp_renderer.go: Renders GitHub MCP configuration to YAML
+//   - mcp_environment.go: Manages GitHub MCP environment variables
+//   - mcp_setup_generator.go: Generates GitHub MCP setup steps
+//   - safe_outputs_app.go: GitHub App token minting helpers
+//
+// Example configuration:
+//
+//	tools:
+//	  github:
+//	    mode: remote                    # or "local" for Docker
+//	    github-token: ${{ secrets.PAT }}
+//	    read-only: true
+//	    lockdown: true                  # or omit for automatic detection
+//	    toolsets: [repos, issues, pull_requests]
+//	    allowed: [get_repo, list_issues, get_pull_request]
 package workflow
 
 import (
diff --git a/pkg/workflow/mcp_renderer.go b/pkg/workflow/mcp_renderer.go
index c1722f8e99..4f4f3e0604 100644
--- a/pkg/workflow/mcp_renderer.go
+++ b/pkg/workflow/mcp_renderer.go
@@ -1,3 +1,78 @@
+// Package workflow provides YAML rendering for MCP server configurations.
+//
+// # MCP Configuration Renderer
+//
+// This file implements the unified MCP configuration renderer that generates
+// YAML configuration for various MCP servers across different AI engines
+// (Copilot, Claude, Codex, Custom). It provides a consistent interface for
+// rendering MCP configurations while handling engine-specific format requirements.
+//
+// Key responsibilities:
+//   - Unified rendering interface for all MCP server types
+//   - Engine-specific format handling (JSON-like vs TOML-like)
+//   - GitHub MCP server configuration (local Docker and remote hosted)
+//   - Playwright MCP server configuration
+//   - Safe-outputs and safe-inputs MCP server configuration
+//   - Agentic-workflows MCP server configuration
+//   - Cache-memory MCP server configuration
+//   - Serena MCP server configuration
+//   - Custom HTTP and stdio MCP server configuration
+//
+// Renderer architecture:
+// The renderer uses the MCPConfigRendererUnified struct with MCPRendererOptions
+// to configure engine-specific behaviors:
+//   - IncludeCopilotFields: Add "type" and "tools" fields for Copilot
+//   - InlineArgs: Render args inline (Copilot) vs multi-line (Claude/Custom)
+//   - Format: "json" for JSON-like or "toml" for TOML-like output
+//   - IsLast: Control trailing commas in rendered configuration
+//
+// Supported MCP server types:
+//   - GitHub: Local (Docker) or remote (hosted) GitHub API access
+//   - Playwright: Browser automation with domain restrictions
+//   - Safe-outputs: Controlled output storage for AI agents
+//   - Safe-inputs: Custom tool execution with secret passthrough
+//   - Cache-memory: Memory/knowledge base management
+//   - Agentic-workflows: Workflow execution via gh-aw extension
+//   - Serena: Local search functionality
+//   - Custom HTTP: User-defined HTTP-based MCP servers
+//   - Custom stdio: User-defined stdio-based MCP servers
+//
+// Engine-specific rendering:
+//   - Copilot: JSON format with "type" and "tools" fields, inline args
+//   - Claude: JSON format without Copilot fields, multi-line args
+//   - Codex: TOML format for MCP configuration
+//   - Custom: Same as Claude (JSON, multi-line args)
+//
+// Configuration structure:
+// All MCP servers follow the MCP Gateway Specification v1.0.0:
+//   - HTTP servers: type, url, headers
+//   - Stdio servers: type, container, entrypoint, entrypointArgs, mounts, env
+//
+// Variable resolution:
+// The renderer handles two types of variable syntax:
+//   - Shell variables: $VAR or ${VAR} - resolved by shell before gateway
+//   - Gateway variables: ${VAR} in JSON - resolved by gateway at runtime
+//
+// Copilot-specific features:
+// Copilot uses backslash-escaped variables (\${VAR}) for proper MCP passthrough
+// and includes additional fields required by the Copilot MCP specification.
+//
+// Related files:
+//   - mcp_github_config.go: GitHub MCP server configuration
+//   - mcp_config_playwright_renderer.go: Playwright-specific rendering
+//   - mcp_config_builtin.go: Built-in MCP server rendering
+//   - mcp_config_custom.go: Custom MCP server rendering
+//   - mcp_setup_generator.go: Calls renderer for configuration generation
+//
+// Example usage:
+//
+//	renderer := NewMCPConfigRenderer(MCPRendererOptions{
+//	    IncludeCopilotFields: true,
+//	    InlineArgs: true,
+//	    Format: "json",
+//	    IsLast: false,
+//	})
+//	renderer.RenderGitHubMCP(yaml, githubTool, workflowData)
 package workflow
 
 import (
diff --git a/pkg/workflow/mcp_setup_generator.go b/pkg/workflow/mcp_setup_generator.go
index 9371e06c8e..335037df66 100644
--- a/pkg/workflow/mcp_setup_generator.go
+++ b/pkg/workflow/mcp_setup_generator.go
@@ -1,3 +1,62 @@
+// Package workflow provides GitHub Actions setup step generation for MCP servers.
+//
+// # MCP Setup Generator
+//
+// This file generates the complete setup sequence for MCP servers in GitHub Actions
+// workflows. It orchestrates the initialization of all MCP tools including built-in
+// servers (GitHub, Playwright, safe-outputs, safe-inputs) and custom HTTP/stdio
+// MCP servers.
+//
+// Key responsibilities:
+//   - Identifying and collecting MCP tools from workflow configuration
+//   - Generating Docker image download steps
+//   - Installing gh-aw extension for agentic-workflows tool
+//   - Setting up safe-outputs MCP server (config, API key, HTTP server)
+//   - Setting up safe-inputs MCP server (config, tool files, HTTP server)
+//   - Starting Serena MCP server in local mode
+//   - Starting the MCP gateway with proper environment variables
+//   - Rendering MCP configuration for the selected AI engine
+//
+// Setup sequence:
+//  1. Download required Docker images
+//  2. Install gh-aw extension (if agentic-workflows enabled)
+//  3. Write safe-outputs config files (config.json, tools.json, validation.json)
+//  4. Generate and start safe-outputs HTTP server
+//  5. Setup safe-inputs config and tool files (JavaScript, Python, Shell, Go)
+//  6. Generate and start safe-inputs HTTP server
+//  7. Start Serena local mode server
+//  8. Start MCP gateway with all environment variables
+//  9. Render engine-specific MCP configuration
+//
+// MCP tools supported:
+//   - github: GitHub API access via MCP (local Docker or remote hosted)
+//   - playwright: Browser automation with Playwright
+//   - safe-outputs: Controlled output storage for AI agents
+//   - safe-inputs: Custom tool execution with secret passthrough
+//   - cache-memory: Memory/knowledge base management
+//   - agentic-workflows: Workflow execution via gh-aw
+//   - serena: Local Serena search functionality
+//   - Custom HTTP/stdio MCP servers
+//
+// Gateway modes:
+//   - Enabled (default): MCP servers run through gateway proxy
+//   - Disabled (sandbox: false): Direct MCP server communication
+//
+// Related files:
+//   - mcp_gateway_config.go: Gateway configuration management
+//   - mcp_environment.go: Environment variable collection
+//   - mcp_renderer.go: MCP configuration YAML rendering
+//   - safe_outputs.go: Safe outputs server configuration
+//   - safe_inputs.go: Safe inputs server configuration
+//
+// Example workflow setup:
+//   - Download Docker images
+//   - Write safe-outputs config to /opt/gh-aw/safeoutputs/
+//   - Start safe-outputs HTTP server on port 3001
+//   - Write safe-inputs config to /opt/gh-aw/safe-inputs/
+//   - Start safe-inputs HTTP server on port 3000
+//   - Start MCP gateway on port 80
+//   - Render MCP config based on engine (copilot/claude/codex/custom)
 package workflow
 
 import (