Fix cache-memory classification in frontmatter documentation

[Copilot]

The documentation incorrectly listed cache-memory as a top-level frontmatter element when the schema defines it under properties.tools.properties.cache-memory.

Changes

• Removed cache-memory from top-level frontmatter elements list
• Added clarifying sentence distinguishing tools configuration from top-level fields
• Grouped all tool configurations (bash, edit, github, web-fetch, web-search, playwright, cache-memory, MCP servers) with explicit reference to tools: key placement

Schema Structure

properties.tools.properties.cache-memory  ✓ (actual schema)
properties.cache-memory                   ✗ (documentation implied)

Correct Usage

---
on: issues
tools:
  cache-memory: true  # Under tools: key
---

Fixes #3589

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Reclassify cache-memory as tools configuration in frontmatter documentation</issue_title>
<issue_description>## Objective
Fix the misleading classification of cache-memory in the frontmatter documentation to accurately reflect that it's a tools configuration, not a top-level frontmatter field.

Context

The schema consistency check (discussion #3589) found that the documentation lists cache-memory as a "frontmatter element" at the same level as top-level fields like engine, network, permissions, etc. However, cache-memory is actually nested under tools: configuration (properties.tools.properties.cache-memory).

Impact:

• Users might incorrectly place cache-memory: at the top level instead of inside tools:
• Documentation structure doesn't match actual YAML structure
• Inconsistent with how other tools configurations are presented

Approach

1. Review the frontmatter elements introduction in frontmatter.md
2. Reorganize the list to distinguish between:
   • Top-level frontmatter fields: on, permissions, engine, network, strict, timeout-minutes, etc.
   • Tools configuration: cache-memory, bash, edit, github, web-fetch, web-search, MCP servers, etc.
3. Update any examples or references that might suggest cache-memory is top-level
4. Ensure the reorganization maintains clarity and doesn't introduce new confusion

Files to Modify

• docs/src/content/docs/reference/frontmatter.md:25 - Update frontmatter elements categorization

Example Structure

## Frontmatter Elements

### Top-Level Configuration
Core workflow settings that appear at the root level:
- `on:` - Workflow triggers
- `permissions:` - GitHub token permissions
- `engine:` - AI processor configuration
- `network:` - Network access control
- `timeout-minutes:` - Workflow timeout
- [etc.]

### Tools Configuration
Tool availability and settings under the `tools:` key:
- `cache-memory:` - Persistent memory storage
- `bash:` - Shell command tools
- `edit:` - File editing tools
- `github:` - GitHub API tools
- `web-fetch:` - Web content fetching
- [etc.]

Acceptance Criteria

• Documentation clearly distinguishes top-level fields from tools configuration
• cache-memory is correctly categorized under tools configuration
• Examples show cache-memory under the tools: key where applicable
• No confusion about configuration hierarchy
• Other tools are similarly and consistently categorized

Related Documentation

• Discussion [Schema Consistency] 🔍 Schema Consistency Check - 2025-11-11: Network & MCP Integration Analysis #3589 - Schema Consistency Check findings
• docs/src/content/docs/reference/frontmatter.md:25 - Current documentation
• pkg/parser/schemas/main_workflow_schema.json - Schema showing cache-memory under tools
  Related to [Schema Consistency] 🔍 Schema Consistency Check - 2025-11-11: Network & MCP Integration Analysis #3589

AI generated by Plan Command for discussion #3589</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [task] Reclassify cache-memory as tools configuration in frontmatter documentation #3595

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull Request Overview

This PR corrects a documentation error where cache-memory was incorrectly listed as a top-level frontmatter element when it's actually a tool configuration that must be specified under the tools: key, matching the schema structure (properties.tools.properties.cache-memory).

Key Changes

• Removed cache-memory from the list of top-level GitHub Agentic Workflows-specific elements
• Added a clarifying sentence explaining that tool configurations are specified under the tools: key
• Included a reference to the Tools documentation for complete configuration details

---

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