[task] Create comprehensive documentation page for YAML type handling

[github-actions]

Objective

Create a documentation page that explains how gh-aw handles YAML numeric types, type coercion, and the differences between schema validation and runtime behavior.

Context

Related to discussion #4307. The runtime is more permissive than the schema, accepting various type representations for user convenience. This needs clear documentation to help users understand what's supported and why external validators might show false errors.

Approach

1. Create new documentation page in docs/ directory
2. Explain YAML type handling philosophy
3. Document all type coercion behaviors
4. Show examples of accepted formats
5. Explain why IDE validators might show false errors
6. Link from relevant reference documentation

Content Structure

Sections to Include

1. Overview

   • YAML type flexibility philosophy
   • Runtime vs schema validation differences
   • Why gh-aw is permissive

2. Numeric Type Handling

   • String-to-number coercion (e.g., "300" → 300)
   • Float-to-int truncation (e.g., 60.5 → 60)
   • Supported numeric formats

3. Polymorphic Fields

   • Fields accepting multiple types (category, version)
   • How conversions work
   • Examples for each field

4. Type Coercion Matrix

   • Table showing field types and accepted formats
   • Examples for each combination

5. IDE Validation vs Runtime

   • Why IDE might show errors for valid workflows
   • How to validate workflows correctly using gh aw compile
   • Future plans for external validation tools

6. Best Practices

   • Recommended formats for clarity
   • When to use quoted vs unquoted numbers
   • Common pitfalls to avoid

Files to Create/Modify

• Create: docs/src/content/docs/reference/type-handling.mdx (or similar path based on docs structure)
• Update: docs/src/content/docs/reference/frontmatter.mdx (add link to type handling page)
• Update: Navigation/sidebar configuration if needed

Acceptance Criteria

• New documentation page created with Astro Starlight format
• All type coercion behaviors documented with examples
• Type acceptance matrix included (similar to table in discussion)
• Explanation of schema vs runtime differences
• Examples showing valid formats that might fail external validators
• Guidance on using gh aw compile for validation
• Proper internal linking from other reference pages
• Follows Diátaxis framework (Explanation type documentation)

Reference Material

Use the tables and examples from discussion #4307:

• Type acceptance comparison matrix
• Code examples from metrics.go, map_helpers.go
• Real-world impact scenarios
• Positive findings section (well-implemented patterns)

Style Guidelines

• Use Astro Starlight aside components for notes and warnings
• Include code examples in both YAML and Go where relevant
• Use neutral, technical tone (not promotional)
• Focus on understanding (Explanation documentation type)

AI generated by Plan Command for discussion #4307