[plan] Create schema design philosophy documentation page #10221
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:
-
Security Model Overview
- Main workflows: full capabilities, trusted entry points
- Included files: restricted capabilities, reusable components
-
Property Availability Matrix
- Table showing which properties work in main vs included
- 38 properties in main, 15 in included, 13 common
-
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)
-
Usage Guidance
- When to create a main workflow
- When to create an included file
- Migration strategies
-
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