Add schema design philosophy documentation

[Copilot]

Documents the security model and design rationale behind the dual-schema architecture for main workflows vs included files.

What's Added

• Security Model Overview: Main workflows as trusted entry points (38 properties), included files as restricted reusable components (15 properties), with 13 shared properties
• Property Availability Matrix: Complete comparison table showing which frontmatter properties work in each schema type
• Design Rationale: Explains why critical restrictions exist:
  • on: triggers - main-only for explicit entry points
  • engine.command - main-only to prevent arbitrary code execution via imports
  • sandbox - main-only to maintain consistent security boundaries
  • mcp-servers - simplified merge behavior in included files
• Usage Guidance: When to create main workflows vs included files, with migration strategies
• Examples: Valid patterns for both types plus common mistakes (adding triggers to included files, using custom commands in imports, expecting permission inheritance)

Location

docs/src/content/docs/reference/schema-design.md

Follows Diátaxis reference style with descriptive mood and technical precision.

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: /opt/hostedtoolcache/node/24.12.0/x64/bin/node 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>[plan] Create schema design philosophy documentation page</issue_title>
<issue_description>## Objective

Create docs/src/content/docs/reference/schema-design.md documenting the security model and design philosophy behind main vs included workflow schemas.

Context

Users need to understand when to use main workflows vs included files, and why certain properties are restricted. This philosophical foundation is currently undocumented.

Approach

Create new documentation page covering:

1. Security Model Overview

   • Main workflows: full capabilities, trusted entry points
   • Included files: restricted capabilities, reusable components

2. Property Availability Matrix

   • Table showing which properties work in main vs included
   • 38 properties in main, 15 in included, 13 common

3. Design Rationale

   • Why engine.command is main-only (security)
   • Why MCP config is simplified in included (sandboxing)
   • Why triggers (on) are main-only (semantic model)

4. Usage Guidance

   • When to create a main workflow
   • When to create an included file
   • Migration strategies

5. Examples

   • Valid main workflow with full capabilities
   • Valid included file with restricted config
   • Common mistakes and how to fix them

Files to Create

• docs/src/content/docs/reference/schema-design.md

Acceptance Criteria

• Documentation clearly explains security model
• Property matrix table is complete and accurate
• Design rationale explains all 3 critical restrictions
• Usage guidance helps users choose correctly
• Examples demonstrate valid patterns
• Page follows Diátaxis framework (reference style)
  Related to [plan] Document schema design philosophy and security model differences #10219

AI generated by Plan Command for discussion #10151

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

• Fixes [plan] Create schema design philosophy documentation page #10221

---

💡 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.