From e2b760907c2efee1c1ec248c0896ead9549c8695 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 11:30:04 +0000
Subject: [PATCH] [docs] document safe-output app overrides and pi bare mode

---
 docs/src/content/docs/reference/auth.mdx   | 18 ++++++++++++++++++
 docs/src/content/docs/reference/engines.md |  2 +-
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/docs/src/content/docs/reference/auth.mdx b/docs/src/content/docs/reference/auth.mdx
index dc98c90b419..e5973c8c371 100644
--- a/docs/src/content/docs/reference/auth.mdx
+++ b/docs/src/content/docs/reference/auth.mdx
@@ -478,6 +478,24 @@ safe-outputs:
 
 When you configure `github-app:` for safe outputs, tokens are minted with permissions specific to the safe output operations being performed, rather than the broader job-level permissions. This provides enhanced security by ensuring that tokens have the minimum necessary permissions for their specific use case.
 
+For workflows that need different permission sets for different safe outputs, configure a handler-specific override under the output type itself. A handler-level `github-app` mints a dedicated installation token for that handler only, while outputs without an override continue to inherit the top-level `safe-outputs.github-app` fallback.
+
+```yaml wrap
+safe-outputs:
+  github-app:
+    client-id: ${{ vars.GLOBAL_APP_ID }}
+    private-key: ${{ secrets.GLOBAL_APP_PRIVATE_KEY }}
+  add-comment:
+    github-app:
+      client-id: ${{ vars.ISSUES_APP_ID }}
+      private-key: ${{ secrets.ISSUES_APP_PRIVATE_KEY }}
+    target: ${{ github.event.issue.number }}
+  dispatch-workflow:
+    workflows: [downstream.yml]
+```
+
+Use this pattern when one output needs narrower access than another. For example, `add-comment` can use an App with only `issues: write` while `dispatch-workflow` keeps using the global App with `actions: write`.
+
 For both tool authentication and safe outputs, you can scope the GitHub App token to specific repositories for enhanced security. This limits the token's access to only the repositories it needs to interact with.
 
 - Omit `repositories` field - Current repository only (default)
diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
index 722a06b0f47..09fbfa7652a 100644
--- a/docs/src/content/docs/reference/engines.md
+++ b/docs/src/content/docs/reference/engines.md
@@ -430,7 +430,7 @@ engine:
 
 ### Bare Mode (`bare`)
 
-Set `engine.bare: true` to disable automatic loading of context and custom instructions by the engine. Use this when the workflow prompt is fully self-contained and you want to prevent the engine from reading memory files, AGENTS.md, or built-in system prompts that would otherwise be loaded automatically.
+Set `engine.bare: true` to disable automatic loading of context and custom instructions by the engine. Use this when the workflow prompt is fully self-contained and you want to prevent the engine from reading memory files, AGENTS.md, or built-in system prompts that would otherwise be loaded automatically. Pi also accepts `engine.bare: true`; for Pi the setting is supported but is a no-op because Pi already runs in bare mode by default.
 
 ```yaml wrap
 engine: