docs: Support both local and restricted environments for gh-aw installation

create.md

@@ -22,19 +22,31 @@ to upgrade to latest. If it is not installed, run the installation script from t
 curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
 ```
 
-**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/`
+**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/gh-aw`
 
 **Verify installation**:
 
+The verification and usage approach depends on your environment:
+
+**Option 1: Local development environment (with GitHub token)**
+
+If you have GitHub CLI (`gh`) installed and authenticated:
+
 ```bash
 gh aw version
 ```
 
-You should see version information displayed. If you encounter an error, check that:
+You can use `gh aw` commands throughout this guide.
+
+**Option 2: Restricted environment (without GitHub token)**
+
+If you're in a restricted environment (like Copilot's coding agent) where the GitHub token is not available, use the full path to the binary:
+
+```bash
+~/.local/share/gh/extensions/gh-aw/gh-aw version
+```
 
-- GitHub CLI (`gh`) is installed and authenticated
-- The installation script completed without errors
-- `~/.local/share/gh/extensions` is in your PATH
+In this case, replace all `gh aw` commands in this guide with `~/.local/share/gh/extensions/gh-aw/gh-aw`.
 
 ## Step 2: Create the Workflow or do Other Actions
 

docs/src/content/docs/guides/upgrading.md

@@ -50,6 +50,8 @@ gh extension upgrade gh-aw
 > curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
 > ```
 >
+> **Note**: When installing with the script, the CLI will refuse to run if the GitHub token is not available. In this case, you should run the tool using the full local path: `~/.local/share/gh/extensions/gh-aw/gh-aw` instead of using `gh aw`.
+>
 
 Check your version with `gh aw version` and compare against the [latest release](https://github.com/github/gh-aw/releases). If you encounter issues, try a clean reinstall with `gh extension remove gh-aw` followed by `gh extension install github/gh-aw`.
 

docs/src/content/docs/setup/cli.md

@@ -62,6 +62,8 @@ curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh |
 
 Installs to `~/.local/share/gh/extensions/gh-aw/gh-aw` and works with all `gh aw` commands. Supports Linux, macOS, FreeBSD, and Windows.
 
+**Note**: When installing with the script, the CLI will refuse to run if the GitHub token is not available. In this case, you should run the tool using the full local path: `~/.local/share/gh/extensions/gh-aw/gh-aw` instead of using `gh aw`.
+
 ### GitHub Actions Setup Action
 
 Install the CLI in GitHub Actions workflows using the `setup-cli` action:

docs/src/content/docs/troubleshooting/common-issues.md

@@ -19,6 +19,8 @@ curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh |
 
 After installation, the binary is installed to `~/.local/share/gh/extensions/gh-aw/gh-aw` and can be used with `gh aw` commands just like the extension installation.
 
+**Note**: When installing with the script, the CLI will refuse to run if the GitHub token is not available. In this case, you should run the tool using the full local path: `~/.local/share/gh/extensions/gh-aw/gh-aw` instead of using `gh aw`.
+
 ### Extension Not Found After Installation
 
 If you installed the extension but `gh aw` command is not found:

install.md

@@ -18,19 +18,31 @@ Run the installation script from the main branch of the gh-aw repository:
 curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
 ```
 
-**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/`
+**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/gh-aw`
 
 **Verify installation**:
 
+The verification and usage approach depends on your environment:
+
+**Option 1: Local development environment (with GitHub token)**
+
+If you have GitHub CLI (`gh`) installed and authenticated:
+
 ```bash
 gh aw version
 ```
 
-You should see version information displayed. If you encounter an error, check that:
+You can use `gh aw` commands throughout this guide.
+
+**Option 2: Restricted environment (without GitHub token)**
+
+If you're in a restricted environment (like Copilot's coding agent) where the GitHub token is not available, use the full path to the binary:
+
+```bash
+~/.local/share/gh/extensions/gh-aw/gh-aw version
+```
 
-- GitHub CLI (`gh`) is installed and authenticated
-- The installation script completed without errors
-- `~/.local/share/gh/extensions` is in your PATH
+In this case, replace all `gh aw` commands in this guide with `~/.local/share/gh/extensions/gh-aw/gh-aw`.
 
 ## Step 2: Initialize Repository for Agentic Workflows