Add security rationale to permissions documentation

[Copilot]

Permissions documentation explains the read-only model's mechanics but not its security rationale. Users need to understand why safe outputs exist, not just how to use them.

Changes

Added "Why This Model?" section to docs/src/content/docs/reference/permissions.md explaining security benefits applicable to all users:

• Audit Trail: Read/write separation provides accountability
• Blast Radius Containment: Limits agent damage scope
• Compliance: Safe outputs serve as approval gates
• Defense in Depth: Blocks destructive actions even under prompt injection

Section positioned between "Security-First Design" and "Permission Scopes" to establish context before technical details.

### Why This Model?

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 security. Safe outputs add one extra job but provide critical safety guarantees.

Addresses UX feedback that users struggle communicating value to security teams and may perceive read-only restrictions as limitations rather than intentional design.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Add "Why This Model?" section to permissions documentation</issue_title>
<issue_description>### Description

The permissions documentation (docs/src/content/docs/reference/permissions.md) provides comprehensive technical details but lacks a critical "Why This Matters" section explaining the security rationale in enterprise context. Users need to understand why the read-only model exists, not just how to use it.

Problem

Current State:

• Documentation jumps directly into technical details (lines 1-175)
• Missing explanation of security rationale for enterprise environments
• No context for why safe outputs are the intended design, not a workaround

User Impact:
Without understanding the "why," users may:

• Perceive read-only restriction as unnecessary limitation
• Attempt to work around the security model
• Struggle to communicate value to security/compliance teams
• Miss the enterprise-grade security benefits

Suggested Changes

Add a new "Why This Model?" section after line 29 (after the introductory explanation) that explains the enterprise security rationale:

Before:

### Permission Scopes

Key permissions include `contents` (code access), `issues` (issue management)...

After:

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

### Permission Scopes

Key permissions include `contents` (code access), `issues` (issue management)...

Files Affected

• docs/src/content/docs/reference/permissions.md - Add new section between lines 29-32

Success Criteria

• New "Why This Model?" section added with 4-6 bullet points
• Content maintains professional tone appropriate for enterprise audience
• Section placed before "Permission Scopes" section
• Links or references maintained (no broken navigation)
• Documentation builds successfully without errors
• Quality assessment improves (per UX analysis)

Source

Extracted from User Experience Analysis Report discussion github/gh-aw#13799

Task 1: "Add 'Why This Model?' Section to Permissions Documentation"

• Addresses clarity and precision + trust and reliability design principles
• High-impact: helps users communicate security value to compliance teams

Priority

Medium - Improves documentation quality and helps users understand security model. Not blocking but valuable for enterprise adoption.

Notes

• Single-file change: docs/src/content/docs/reference/permissions.md only
• Can be completed in 30-45 minutes
• No code changes required
• Follows Diátaxis framework: adds explanation to existing reference documentation

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 6, 2026, 1:25 PM UTC

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

• Fixes [Code Quality] Add "Why This Model?" section to permissions documentation #13912

---

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

[pelikhan]

@copilot remove "in enterprise environments..."

[Copilot]

Removed "In enterprise environments" to make it applicable to all users. Updated in 99b5542

[pelikhan]

@copilot not enterprise specific

[Copilot]

Removed "enterprise-grade" to make it broadly applicable. Updated in 99b5542

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

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.13.0/x64/bin/node node /home/REDACTED/.npm/_npx/aa98e6899c6baff3/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.13.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)

[Copilot]

Pull request overview

This PR adds a security rationale section to the permissions documentation to help users understand why the read-only model exists, not just how to use it. This addresses UX feedback that users struggle to communicate the security value to compliance teams.

Changes:

• Added "Why This Model?" section explaining the security benefits of the read-only permission model (audit trail, blast radius containment, compliance support, and defense in depth)

---

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