[task] Create explanation documentation for conceptual understanding #1454

Objective

Develop conceptual explanation documentation that clarifies and illuminates how GitHub Agentic Workflows work, complementing the task-oriented and reference documentation.

Context

The Diátaxis framework's fourth quadrant (Explanation) is currently missing from the documentation. These understanding-oriented pages help users build mental models of how the system works, which is essential for effective use of advanced features.

Approach

Create new explanation pages in docs/src/content/docs/explanation/ that focus on concepts rather than tasks:

Core explanations needed:

1. How Agentic Workflows Work - Architecture and execution model
2. Security Model - Permission separation, safe outputs, XPIA protection
3. Compilation Process - Markdown to YAML transformation
4. Engine Comparison - When to use Copilot vs Claude vs Codex
5. MCP Server Architecture - How tools integrate with workflows
6. Safe Outputs Design - Why and how safe outputs provide security

Content approach:

• Focus on "why" and "how" rather than "what" and "how to"
• Use diagrams and visual aids
• Explain design decisions and tradeoffs
• Link to relevant tutorials and how-tos

Files to Create

• docs/src/content/docs/explanation/architecture.md - How agentic workflows work
• docs/src/content/docs/explanation/security-model.md - Security and permission design
• docs/src/content/docs/explanation/compilation.md - Compilation process explained
• docs/src/content/docs/explanation/engine-comparison.md - Choosing the right engine
• docs/src/content/docs/explanation/mcp-architecture.md - MCP server integration
• docs/src/content/docs/explanation/safe-outputs-design.md - Safe outputs philosophy

Files to Update

• Move: Conceptual content from docs/src/content/docs/start-here/concepts.md to explanation section
• Update: Cross-references from tutorials and how-tos to explanation pages

Acceptance Criteria

• Each explanation page focuses on understanding, not tasks
• Content explains "why" and "how" system works
• Visual diagrams included where helpful
• Design decisions and tradeoffs are discussed
• Pages link to related tutorials and how-tos
• No step-by-step instructions (those belong in how-tos)

Related to

Issue #1433
Related to #1433

AI generated by Plan Command