docs: add supported runners table to frontmatter reference

[Mossaka]

Summary

Add a runner compatibility table to the runs-on: section of the frontmatter reference, so users know which runners work with agentic workflows.

Changes

• docs/src/content/docs/reference/frontmatter.md — add table below runs-on: showing supported/unsupported runners
• Links to FAQ for macOS explanation

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a runner compatibility table to the runs-on: section of the frontmatter reference to clarify which GitHub Actions runners are supported for agentic workflows.

Changes:

• Add a “Supported runners for runs-on:” table under the runs-on: documentation
• Include a link to the FAQ for macOS runner rationale

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The FAQ link target appears to be broken: there is no #why-dont-agentic-workflows-support-macos-runners section in docs/src/content/docs/reference/faq.md, so this anchor will 404. Either add that FAQ heading (so the slug exists) or change this link to an existing section/page that explains macOS runner limitations.

Suggested change

	| `macos-*` | ❌ Not supported. Docker is unavailable on macOS runners (no nested virtualization). See [FAQ](/gh-aw/reference/faq/#why-dont-agentic-workflows-support-macos-runners). |
	| `macos-*` | ❌ Not supported. Docker is unavailable on macOS runners (no nested virtualization). See [FAQ](/gh-aw/reference/faq/). |

[Copilot]

This row says macos-* is not supported because Docker is unavailable on macOS runners, but this repo includes an agentic workflow that runs on macos-latest and explicitly validates Docker (.github/workflows/smoke-macos-arm64.md). Please reconcile the docs with actual supported behavior (e.g., clarify that macOS is supported/experimental, or that only certain macOS runners are supported) and avoid stating Docker is unavailable if it's expected to work here.

Suggested change

	| `macos-*` | ❌ Not supported. Docker is unavailable on macOS runners (no nested virtualization). See [FAQ](/gh-aw/reference/faq/#why-dont-agentic-workflows-support-macos-runners). |
	| `windows-*` | ❌ Not supported. AWF requires Linux. |
	| `macos-latest` (ARM64) | 🧪 Supported on GitHub-hosted macOS ARM runners with Docker available. See [FAQ](/gh-aw/reference/faq/#why-dont-agentic-workflows-support-macos-runners). |
	| Other `macos-*` | ❌ Not supported. Older macOS runners do not provide the required Docker/nested virtualization capabilities. |
	| `windows-*` | ❌ Not supported. Agentic Workflows do not currently support Windows runners. |

[github-actions]

Smoke test 22247376918 results (@pelikhan):

Test	Status
GitHub MCP	✅
Safe Inputs GH CLI	✅
Serena MCP	❌
Playwright	✅
File Writing	✅
Bash Tool	✅
Discussion Interaction	✅
Build gh-aw	✅
Discussion Creation	✅
Workflow Dispatch	✅
PR Review	✅

Overall: ⚠️ PARTIAL PASS (10/11) — Serena MCP tools unavailable.

📰 BREAKING: Report filed by Smoke Copilot

[github-actions]

Hey @Mossaka 👋 — thanks for working on the runner documentation! The content itself looks great and helpful for users. However, there are a couple of important process issues:

Process Violation: This PR was created directly by you rather than through the agentic workflow process. According to CONTRIBUTING.md, this repository does not accept traditional pull requests. Instead, you should:

1. Close this PR
2. Open an issue describing what documentation needs to be added (with your agentic plan)
3. Wait for a maintainer to review and assign the issue to GitHub Copilot Agent
4. The agent will create a PR implementing your plan

Broken Link: The FAQ link in your table uses the anchor #why-dont-agentic-workflows-support-macos-runners, but the actual FAQ heading is "Why are macOS runners not supported?", which would generate the anchor #why-are-macos-runners-not-supported. This link will be broken.

Here's an agentic plan you could use in an issue instead:

## Add Runner Compatibility Table to Frontmatter Reference

### Summary
Add a table documenting which GitHub Actions runners are supported for agentic workflows to help users choose the right runner.

### Implementation Plan

1. **Update `docs/src/content/docs/reference/frontmatter.md`**:
   - Add a new section "Supported runners for `runs-on:`" after the basic runs-on examples (around line 452)
   - Create a markdown table with two columns: "Runner" and "Status"
   - Include these rows:
     - `ubuntu-latest` — ✅ Default. Recommended for most workflows.
     - `ubuntu-24.04` / `ubuntu-22.04` — ✅ Supported.
     - `ubuntu-24.04-arm` — ✅ Supported. Linux ARM64 runner.
     - `macos-*` — ❌ Not supported. Link to FAQ with correct anchor.
     - `windows-*` — ❌ Not supported. AWF requires Linux.

2. **Fix FAQ Link**:
   - Verify the correct anchor for the macOS FAQ section
   - The FAQ heading is "Why are macOS runners not supported?"
   - Use the proper anchor format (likely `#why-are-macos-runners-not-supported`)
   - Test the link to ensure it resolves correctly

3. **Placement**:
   - Insert the table immediately after the `runs-on:` code example
   - Before the "Workflow Concurrency Control" section

### Why This Helps
Users frequently ask which runners are supported. Having this information directly in the frontmatter reference prevents confusion and failed workflow runs.

The project uses agentic development exclusively to dogfood its own tools — I know it's different from typical GitHub workflows, but it helps demonstrate the power of the approach! 🤖

Generated by Contribution Check

[github-actions]

Hey @Mossaka 👋 — thanks for taking the time to improve the documentation around runner support! The content here looks helpful — adding a clear table showing which runners are supported is exactly the kind of clarification users need.

However, this PR doesn't follow the project's contribution process. This project requires all contributions to go through agentic workflows — you can't create pull requests directly:

• What should have happened: You should open an issue with a detailed agentic plan describing what documentation needs to be added
• Maintainer review: A maintainer reviews and approves the plan
• Agent creates PR: The GitHub Copilot Agent is assigned to the issue and creates the PR automatically

From CONTRIBUTING.md:

🚫 Traditional Pull Requests Are Not Enabled: You cannot create pull requests directly. Instead, you create detailed agentic plans in issues, and GitHub Copilot Agent will create and implement the PR for you after maintainer approval.

This isn't just a formality — the project is dogfooding its own technology. Every contribution goes through the agentic workflow to demonstrate how these systems work in practice.

Next Steps

1. Close this PR (maintainers will likely do this)
2. Open an issue with an agentic plan describing the runner compatibility table you want to add
3. Wait for maintainer approval and agent assignment
4. The agent will create the PR and implement your plan

Thanks for contributing, and sorry for the inconvenience! This process ensures consistency and lets the project practice what it preaches. 🤖

Generated by Contribution Check

[github-actions]

Hey @Mossaka 👋 — thanks for contributing documentation to help users understand runner compatibility! The content you've added is clear and helpful.

However, this PR violates the contribution process outlined in CONTRIBUTING.md. This repository does not accept traditional pull requests — all contributions must go through the agentic workflow:

• Process violation: You created this PR directly instead of opening an issue with an agentic plan
• Required workflow: Create issue → Maintainer reviews → Assign to GitHub Copilot Agent → Agent creates PR

This isn't just a formality — the project dogfoods its own technology. Every contribution demonstrates how agentic workflows work in practice.

What You Should Do

1. Close this PR (or a maintainer will)
2. Open an issue with a detailed agentic plan describing the runner compatibility table
3. Wait for maintainer approval
4. The agent will create the PR and implement your plan

The content quality is good — it just needs to follow the correct process.

Thanks for your patience with this unique workflow! 🤖

Generated by Contribution Check

[github-actions]

Hey @Mossaka 👋 — thanks for working on the runner documentation! The content itself looks helpful and well-organized. The table is clear and provides exactly the kind of information users need when choosing runners.

However, this PR violates the contribution process. According to CONTRIBUTING.md, this repository does not accept traditional pull requests:

🚫 Traditional Pull Requests Are Not Enabled: You cannot create pull requests directly. Instead, you create detailed agentic plans in issues, and GitHub Copilot Agent will create and implement the PR for you after maintainer approval.

This isn't arbitrary bureaucracy — the project dogfoods its own technology. Every contribution demonstrates how agentic workflows work in practice.

Additionally, there's a technical issue with the FAQ link: The anchor #why-dont-agentic-workflows-support-macos-runners doesn't match the actual FAQ heading "Why are macOS runners not supported?", which would generate the anchor #why-are-macos-runners-not-supported. This link will be broken.

What You Should Do

1. Close this PR (or wait for a maintainer to close it)
2. Open an issue with a detailed agentic plan like the one below
3. Wait for maintainer approval
4. The agent will create a PR implementing your plan with the correct FAQ link

If you'd like to proceed with the correct process, here's an agentic plan you can use:

## Add Runner Compatibility Table to Frontmatter Reference

### Summary
Add a table documenting which GitHub Actions runners are supported for agentic workflows to help users choose the right runner.

### Implementation Plan

1. **Update `docs/src/content/docs/reference/frontmatter.md`**:
   - Add a new section titled "Supported runners for `runs-on:`" after the basic runs-on examples
   - Create a markdown table with two columns: "Runner" and "Status"
   - Include these rows:
     - `ubuntu-latest` — ✅ Default. Recommended for most workflows.
     - `ubuntu-24.04` / `ubuntu-22.04` — ✅ Supported.
     - `ubuntu-24.04-arm` — ✅ Supported. Linux ARM64 runner.
     - `macos-*` — ❌ Not supported. Docker is unavailable on macOS runners. Link to FAQ.
     - `windows-*` — ❌ Not supported. AWF requires Linux.

2. **Fix FAQ Link**:
   - Verify the correct anchor for the macOS FAQ section in `docs/src/content/docs/reference/faq.md`
   - The FAQ heading is "Why are macOS runners not supported?"
   - Use the correct auto-generated anchor: `#why-are-macos-runners-not-supported`

### Why This Helps
Users frequently ask which runners are supported. Having this information directly in the frontmatter reference prevents confusion and failed workflow runs.

Thanks for your patience with this unique workflow! 🤖

Generated by Contribution Check