[task] Add progressive disclosure to frontmatter reference documentation #1473

Objective

Refactor docs/src/content/docs/reference/frontmatter.md to use progressive disclosure, showing only essential fields first and hiding advanced configuration behind expandable sections.

Context

The scout report recommends minimizing initial cognitive load. The current frontmatter documentation shows all options at once, which is overwhelming for beginners. Part of issue #1433.

Approach

Restructure the frontmatter reference page with two main sections:

1. Essential Fields (always visible):

   • on: - Workflow triggers
   • permissions: - Token permissions
   • engine: - AI processor (simple string format only)
   • Brief, one-line descriptions

2. Advanced Fields (in <details> tag):

   • tools: - Tool configuration
   • network: - Network access control
   • cache: - Dependency caching
   • safe-outputs: - Output processing
   • timeout_minutes: - Workflow timeout
   • All other optional fields

Files to Modify

• docs/src/content/docs/reference/frontmatter.md

Pattern to Apply

## Essential Frontmatter Fields

These are the minimum fields you need to get started:

### `on:`
Workflow triggers. Example: `on: issues`

### `permissions:`
...

<details>
<summary>Show Advanced Frontmatter Fields</summary>

## Advanced Configuration

### `tools:`
Configure which tools the AI can use...

### `network:`
Control network access...

</details>

Acceptance Criteria

• Essential fields section contains only on, permissions, engine
• Advanced fields are in <details> expandable section
• Each field has a brief description (1-2 sentences max)
• Link to complete field documentation in examples
• Page builds without errors
• No broken internal links
  Related to Simplify docs scaffolding #1433

AI generated by Plan Command