diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
index 226e503c4b..e5ada122b9 100644
--- a/docs/src/content/docs/reference/safe-outputs.md
+++ b/docs/src/content/docs/reference/safe-outputs.md
@@ -821,8 +821,32 @@ safe-outputs:
     expires: 3                # auto-close after 3 days (or false to disable)
     max: 3                    # max discussions (default: 1)
     target-repo: "owner/repo" # cross-repository
+    fallback-to-issue: true   # fallback to issue creation on permission errors (default: true)
 ```
 
+#### Fallback to Issue Creation
+
+The `fallback-to-issue` field (default: `true`) automatically falls back to creating an issue when discussion creation fails due to permissions errors. This is useful in repositories where discussions are not enabled or where the workflow lacks the necessary permissions to create discussions.
+
+When fallback is triggered:
+- An issue is created instead of a discussion
+- A note is added to the issue body indicating it was intended to be a discussion
+- The issue includes all the same content as the intended discussion
+
+To disable fallback behavior and fail if discussions cannot be created:
+
+```yaml wrap
+safe-outputs:
+  create-discussion:
+    fallback-to-issue: false
+```
+
+Common scenarios where fallback is useful:
+- Repositories with discussions disabled
+- Insufficient permissions (requires `discussions: write`)
+- Organization policies restricting discussions
+- Testing workflows across different repository configurations
+
 ### Close Discussion (`close-discussion:`)
 
 Closes GitHub discussions with optional comment and resolution reason. Filters by category, labels, and title prefix control which discussions can be closed.
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 10f3410461..bcc2a71305 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -53,14 +53,14 @@ gh extension install github/gh-aw@v0.2.0
 
 ### Alternative: Standalone Installer
 
-Use the standalone installer if extension installation fails (common in Codespaces or with auth issues):
+Use the standalone installer if extension installation fails (common in Codespaces, restricted networks, or with auth issues):
 
 ```bash wrap
 curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash                # Latest
 curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s v0.1.0      # Pinned
 ```
 
-Installs to `~/.local/share/gh/extensions/gh-aw/gh-aw` and works with all `gh aw` commands. Supports Linux, macOS, FreeBSD, and Windows.
+Installs to `~/.local/share/gh/extensions/gh-aw/gh-aw` and works with all `gh aw` commands. Supports Linux, macOS, FreeBSD, and Windows. Works in environments where GitHub API access is blocked by MITM proxies or corporate firewalls by using direct release download URLs.
 
 ### GitHub Actions Setup Action