[Code Quality] Document null value semantics in frontmatter configuration

[github-actions]

Description

Production workflows use null values in configuration (e.g., workflow_dispatch: null, github: null), but documentation doesn't explain when to use null vs omitting the field entirely.

Current Behavior

Schema explicitly allows "type": "null" in 76 locations, and production workflows use it:

# From .github/workflows/daily-team-status.md
on:
  schedule:
  - cron: 0 9 * * 1-5
  stop-after: +1mo
  workflow_dispatch: null  # What does null mean here?

tools:
  github: null  # Why null instead of omitting?

Questions to Address

1. When should users use null vs omitting the field?
2. Does workflow_dispatch: null behave differently than omitting it?
3. Is there semantic meaning to null that should be documented?

Suggested Changes

1. Update Documentation

Add a new section to docs/src/content/docs/reference/frontmatter.md:

### Null Values vs Omitting Fields

When a field is optional, you can either omit it entirely or set it to `null`. Here's when to use each:

**Omit the field** when:
- You don't need the feature
- You want to inherit default behavior
- Example: Omitting `timeout-minutes` uses the default 360 minutes

**Use `null`** when:
- You want to explicitly disable a feature
- You want to override an inherited configuration
- Example: `workflow_dispatch: null` disables manual workflow dispatch

#### Common Examples

``````yaml
# Disable workflow_dispatch trigger explicitly
workflow_dispatch: null

# Use GitHub tools with default configuration
tools:
  github: null  # Same as `github: {}` or omitting

### 2. Add Schema Descriptions

Update the 76 `"type": "null"` locations in schema with clear descriptions explaining null semantics.

Example for `workflow_dispatch`:
``````json
{
  "workflow_dispatch": {
    "description": "Manual workflow dispatch trigger. Use null to explicitly disable, or omit to use default behavior.",
    "oneOf": [
      { "type": "null" },
      // ... other types
    ]
  }
}

Files Affected

• docs/src/content/docs/reference/frontmatter.md (documentation)
• pkg/parser/schemas/main_workflow_schema.json (schema descriptions)

Success Criteria

• Documentation clearly explains null vs omission semantics
• Schema descriptions updated for key fields using null
• Users understand when to use null vs omit
• No behavioral changes to existing workflows

Impact

• Improves developer experience and reduces confusion
• Provides clear guidance on optional field usage
• Helps users make informed configuration choices

Source

Extracted from Schema Consistency Check discussion #11976 (2026-01-26).

Issue identified as "NEW" discovery in "Moderate Issues" section under "Null Value Handling in Workflows".

Priority

Medium - Documentation improvement affecting workflow authoring experience

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 17, 2026, 5:23 AM UTC