docs: Document GitHub App token implementation and clarify OIDC distinction

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

@@ -47,6 +47,11 @@ permissions:
 
 This permission is safe to use and does not require safe-outputs, even in strict mode.
 
+> [!NOTE]
+> OIDC vs GitHub App tokens
+> 
+> The `id-token: write` permission is for **OIDC authentication with external cloud providers** (AWS, GCP, Azure). This is different from [GitHub App tokens](/gh-aw/reference/tokens/#github-app-tokens), which authenticate with GitHub's API for safe output operations. GitHub App tokens are configured via `safe-outputs.app` and use the [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token) action, not OIDC.
+
 ## Configuration
 
 ### Basic Configuration

docs/src/content/docs/reference/safe-outputs.md

@@ -1053,6 +1053,8 @@ safe-outputs:
   create-issue:
 ```
 
+When configured, the compiler uses [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token) to mint short-lived installation tokens that are automatically invalidated at job end. See [GitHub App Tokens](/gh-aw/reference/tokens/#github-app-tokens) for complete technical implementation details.
+
 ### Maximum Patch Size (`max-patch-size:`)
 
 Limits git patch size for PR operations (1-10,240 KB, default: 1024 KB):

docs/src/content/docs/reference/tokens.md

@@ -495,6 +495,28 @@ safe-outputs:
     # Permissions computed based on safe output types
 ```
 
+**Technical implementation**:
+
+When you configure a GitHub App in `safe-outputs.app`, the compiler generates a workflow that:
+
+1. **Mints a token** at the start of the safe-outputs job using [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token):
+   - Creates an installation access token with the GitHub App's `app-id` and `private-key`
+   - Automatically determines required permissions from safe output types (e.g., `permission-issues: write` for `create-issue`)
+   - Scopes token to specified owner and repositories (defaults to current repo)
+   - Stores token in step output: `steps.app-token.outputs.token`
+
+2. **Uses the token** for all safe output operations:
+   - Passed as `github-token` parameter to GitHub API calls
+   - Used for checkout operations when creating pull requests
+   - All actions are attributed to the GitHub App identity
+
+3. **Invalidates the token** at job end (even on failure):
+   - Makes DELETE request to `/installation/token` API endpoint
+   - Runs with `if: always()` to ensure cleanup
+   - Prevents token reuse after workflow completes
+
+This differs from [OpenID Connect (OIDC) authentication](/gh-aw/reference/permissions/#special-permission-id-token), which uses the `id-token: write` permission for cloud provider authentication (AWS, GCP, Azure). OIDC tokens are for external services, while GitHub App tokens authenticate with GitHub's API.
+
 **Permission mapping**:
 
 - `create-issue:` → Issues: Write

pkg/cli/templates/create-shared-agentic-workflow.md

@@ -34,7 +34,7 @@ You are a conversational chat agent that interacts with the user to design secur
 **Move Write Operations to Safe Outputs**
 - Never grant direct write permissions in shared components
 - Use `safe-outputs:` configuration for all write operations
-- Common safe outputs: `create-issue`, `add-comment`, `create-pull-request`, `update-issue`
+- Common safe outputs: `create-issue`, `add-comment`, `create-pull-request`, `update-issue`, `dispatch-workflow`
 - Let consuming workflows decide which safe outputs to enable
 
 **Process Agent Output in Safe Jobs**

pkg/cli/templates/github-agentic-workflows.md

@@ -568,6 +568,14 @@ The YAML frontmatter supports these fields:
         target-repo: "owner/repo"       # Optional: cross-repository
     ```
     Publishes workflow artifacts to an orphaned git branch for persistent storage. Default allowed extensions include common non-executable types. Maximum file size is 50MB (51200 KB).
+  - `dispatch-workflow:` - Trigger other workflows with inputs
+    ```yaml
+    safe-outputs:
+      dispatch-workflow:
+        workflows: [workflow-name]          # Required: list of workflow names to allow
+        max: 3                              # Optional: max dispatches (default: 1, max: 3)
+    ```
+    Triggers other agentic workflows in the same repository using workflow_dispatch. Agent output includes `workflow_name` (without .md extension) and optional `inputs` (key-value pairs). Not supported for cross-repository operations.
   - `create-code-scanning-alert:` - Generate SARIF security advisories
     ```yaml
     safe-outputs: