docs: Expand CLAUDE.md with comprehensive architecture guide

[oleksiibarsuk-eng]

Summary

Significantly expanded CLAUDE.md to serve as a complete architectural reference for the Claude GitHub Action. This documentation now covers the full execution flow, directory structure, key concepts, and gotchas that developers need to understand when working on this codebase.

Key Changes

• Execution Flow: Added detailed four-phase breakdown (Prepare → Install → Execute → Cleanup) with explanations of what happens in each phase
• Directory Structure: Added comprehensive ASCII tree showing all source files with inline descriptions of their purpose
• Architecture Sections:
  • Expanded "How It Runs" into "Architecture Overview" with subsections for execution flow, directory structure, and base-action
  • Added "Two Auth Domains" section clarifying GitHub auth vs Claude API auth
  • Added "Mode Detection" section explaining tag vs agent mode lifecycle
  • Added "Prompt Construction" section detailing what Claude sees in both modes
  • Added "MCP Servers" section with table of auto-installed servers and their tools
  • Added "GitHub Context Type System" section explaining the discriminated union pattern
• Things That Will Bite You: Expanded with more specific gotchas:
  • TypeScript strictness flags (noUncheckedIndexedAccess, strict)
  • WorkflowValidationSkipError special case
  • verbatimModuleSyntax requirement
  • Branch name validation security
• Code Conventions: Reorganized and expanded with:
  • Bun-specific guidance (native test runner, not Jest)
  • Retry logic expectations
  • Content sanitization and path validation requirements
  • Actor filtering wildcard support
• CI/CD Section: Added new section documenting all GitHub workflows

Notable Details

• Clarified that base-action/ is published as a standalone npm package and its public API must not break
• Emphasized that SSH signing cleanup and token revocation must stay in action.yml always() steps, not in run.ts, to survive process crashes
• Documented the retry utility specifics (3 attempts, 5s initial, 20s max, 2x backoff)
• Added security considerations for path validation and content sanitization
• Included table of MCP servers with their tools and purposes for quick reference

https://claude.ai/code/session_011sD6dcnksrWF5zdoDmu9ui