[Code Quality] Add \"Why This Model?\" section to permissions documentation

[github-actions]

Description

The permissions reference documentation (docs/src/content/docs/reference/permissions.md) provides comprehensive technical details about the security-first permission model but lacks critical context explaining why the read-only restriction exists. Enterprise users need to understand the security rationale to communicate value to compliance teams.

User Impact

Without the "why" context:

• Security teams may question the architectural choice
• Developers may view safe outputs as a workaround rather than the intended pattern
• Compliance discussions lack clear articulation of security benefits
• Users may attempt to work around the security model

Suggested Changes

Add a new "Why This Model?" section after line 29 (after "This model prevents AI agents from accidentally or maliciously modifying repository content during execution.") explaining the enterprise security rationale.

Content to add:

### Why This Model?

In enterprise environments, AI agents require careful security controls:

- **Audit Trail**: Separating read (agent) from write (safe outputs) provides clear accountability for all changes
- **Blast Radius Containment**: If an agent misbehaves, it cannot modify code, merge PRs, or delete resources
- **Compliance**: Many organizations require approval workflows for automated changes - safe outputs provide the approval gate
- **Defense in Depth**: Even if prompt injection occurs, the agent cannot perform destructive actions

This model trades convenience for enterprise-grade security. Safe outputs add one extra job but provide critical safety guarantees.

Files Affected

Single file only:

• docs/src/content/docs/reference/permissions.md

Success Criteria

• New "Why This Model?" section added between lines 29-32
• Content includes 4-6 bullet points explaining security rationale
• Professional tone appropriate for enterprise audience
• Documentation renders correctly in docs site
• Quality rating improves from ⚠️ to ✅

Source

Extracted from User Experience Analysis discussion #13799

Priority

Medium - Improves documentation clarity, helps users communicate security value

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 6, 2026, 1:27 AM UTC