Document role requirements for audit/logs tools in agentic-workflows

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

@@ -172,7 +172,7 @@ Custom jobs and safe outputs jobs can have their own permission requirements bas
 
 Some tools require specific permissions to function:
 
-- **`agentic-workflows`**: Requires `actions: read` to access workflow logs and run data
+- **`agentic-workflows`**: Requires `actions: read` to access workflow logs and run data. Additionally, the `logs` and `audit` tools require the workflow actor to have **write, maintain, or admin** repository role.
 - **GitHub Model Context Protocol (MCP) toolsets**: See [Tools](/gh-aw/reference/tools/) for GitHub API permission requirements
 
 The compiler validates these requirements and provides clear error messages when permissions are missing.

docs/src/content/docs/reference/tools.md

@@ -196,6 +196,9 @@ tools:
   agentic-workflows:
 ```
 
+> [!NOTE]
+> The `logs` and `audit` tools require the workflow actor to have **write, maintain, or admin** repository role. Other tools (status, compile, mcp-inspect, add, update, fix) are available to all users.
+
 See [MCP Server](/gh-aw/setup/mcp-server/#using-as-agentic-workflows-tool) for available operations.
 
 ### Cache Memory (`cache-memory:`)

docs/src/content/docs/setup/mcp-server.md

@@ -178,6 +178,10 @@ Compile Markdown workflows to GitHub Actions YAML with optional static analysis.
 
 Download and analyze workflow logs with timeout handling and size guardrails.
 
+> [!WARNING]
+> Role Requirement
+> This tool requires the workflow actor to have **write, maintain, or admin** repository role. Actors with read or triage access will receive a permission denied error.
+
 **Parameters:**
 - `workflow_name` (optional): Workflow name to download logs for (empty for all)
 - `count` (optional): Number of workflow runs to download (default: 100)
@@ -204,6 +208,10 @@ Download and analyze workflow logs with timeout handling and size guardrails.
 
 Investigate a workflow run, job, or specific step and generate a detailed report.
 
+> [!WARNING]
+> Role Requirement
+> This tool requires the workflow actor to have **write, maintain, or admin** repository role. Actors with read or triage access will receive a permission denied error.
+
 **Parameters:**
 - `run_id_or_url` (required): One of:
   - Numeric run ID: `1234567890`
@@ -328,6 +336,31 @@ Check workflow status, download logs, and audit failures.
 ```
 
 > [!CAUTION]
-> Required Permission
+> Required Permissions and Roles
+> 
+> **GitHub Actions Permission:**
 > The `agentic-workflows` tool requires `actions: read` permission to access GitHub Actions workflow logs and run data.
+> 
+> **Repository Role Requirements:**
+> The `logs` and `audit` tools require the workflow actor to have **write, maintain, or admin** role in the repository. These tools check the actor's repository permissions using the GitHub API before allowing access.
+> 
+> - **Minimum role:** write, maintain, or admin
+> - **Environment variable:** `GITHUB_ACTOR` must be set (automatically provided in GitHub Actions)
+> - **Permission check:** Runtime validation via GitHub API `/repos/{owner}/{repo}/collaborators/{username}/permission`
+> 
+> **Permission Denied Errors:**
+> 
+> If the actor has insufficient permissions (e.g., read or triage access), the tools will return:
+> ```json
+> {
+>   "error": "insufficient repository permissions",
+>   "actor": "username",
+>   "repository": "owner/repo",
+>   "role": "read",
+>   "required": "write, maintain, or admin",
+>   "reason": "Actor username has read access to owner/repo. This tool requires at least write access."
+> }
+> ```
+> 
+> **Other tools** (status, compile, mcp-inspect, add, update, fix) are available to all users regardless of repository role.