📚 Add Gemini auth docs and improve Copilot PAT setup

docs/src/content/docs/reference/auth.mdx

@@ -22,6 +22,7 @@ You will need one of the following GitHub Actions secrets configured in your rep
 - **Copilot** – Add [`COPILOT_GITHUB_TOKEN`](#copilot_github_token)
 - **Claude by Anthropic** – Add [`ANTHROPIC_API_KEY`](#anthropic_api_key)
 - **Codex by OpenAI** – Add [`OPENAI_API_KEY`](#openai_api_key)
+- **Gemini by Google** – Add [`GEMINI_API_KEY`](#gemini_api_key)
 
 Depending on what your workflow needs to do, you may need additional GitHub tokens added as repository secrets:
 
@@ -69,17 +70,16 @@ A reference for all GitHub Actions secrets and tokens used by GitHub Agentic Wor
 
 ### `COPILOT_GITHUB_TOKEN`
 
-If using Copilot as your AI engine, you need a GitHub Actions Secret set to a GitHub Personal Access Token (PAT) with the `copilot-requests` scope to authenticate Copilot CLI.
-
-**Setup**:
+If using Copilot as your AI engine, you need a GitHub Actions Secret set to a GitHub Personal Access Token (PAT) to authenticate Copilot CLI.
 
 Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new):
 
-1. Select your user account, not an organization.
-2. Choose **"Public repositories"** access, even if adding a workflow to a private repo.
-3. Enable "Copilot Requests" permissions.
+1. Select your **user account**, not an organization.
+2. Choose **"Public repositories"**, even if you will be using it with private repositories. This is required for the "Copilot Requests" permission to be available.
+3. Click "Add permissions" and choose "Copilot Requests".
+4. Click "Generate token" and copy the token value.
 
-You **must have "Public repositories" selected**; otherwise, the Copilot Requests permission option will not appear.
+You **must have "Public repositories" selected**; otherwise, the Copilot Requests permission option will not be available.
 
 Then add the PAT to your GitHub Actions repository secrets as `COPILOT_GITHUB_TOKEN`, either by CLI or GitHub UI (see video).
 
@@ -134,6 +134,24 @@ See also (/gh-aw/reference/engines/#using-openai-codex) for additional configura
 
 ---
 
+### `GEMINI_API_KEY`
+
+If using the Gemini by Google engine, you need to set a GitHub Actions secret `GEMINI_API_KEY` with an API key from Google AI Studio.
+
+**Setup**:
+
+1. Create an API key at https://aistudio.google.com/api-keys
+
+2. Add it to your repository secrets:
+
+   ```bash wrap
+   gh aw secrets set GEMINI_API_KEY --value "YOUR_GEMINI_API_KEY"
+   ```
+
+See also (/gh-aw/reference/engines/#using-google-gemini-cli) for additional configuration needed when using Gemini with GitHub MCP.
+
+---
+
 ### `GH_AW_GITHUB_TOKEN`
 
 A Personal Access Token (PAT) with appropriate scopes and permissions for enhanced security and cross-repository operations.

docs/src/content/docs/reference/engines.md

@@ -26,21 +26,7 @@ To use Copilot CLI with GitHub Agentic Workflows:
    engine: copilot
    ```
 
-2. Create a fine-grained GitHub Personal Access Token (PAT)
-
-   You need a GitHub Personal Access Token (PAT) with the `copilot-requests` scope to authenticate Copilot CLI. Create a fine-grained PAT at <https://github.com/settings/personal-access-tokens/new>.
-
-   - Select your user account, not an organization.
-   - Choose "Public repositories" access.
-   - Enable "Copilot Requests" permissions.
-
-   You **must** have "Public repositories" selected; otherwise, the Copilot Requests permission option will not appear.
-
-3. Add the PAT to your GitHub Actions repository secrets as `COPILOT_GITHUB_TOKEN`:
-
-   ```bash wrap
-   gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-github-pat>"
-   ```
+2. Configure the `COPILOT_GITHUB_TOKEN` secret. See [Authentication: COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) for setup instructions.
 
 ## Using Claude by Anthropic (Claude Code)
 
@@ -52,13 +38,7 @@ To use [Claude by Anthropic](https://www.anthropic.com/index/claude) (aka Claude
    engine: claude
    ```
 
-2. Configure `ANTHROPIC_API_KEY` GitHub Actions secret.
-
-   [Create an Anthropic API key](https://platform.claude.com/docs/en/get-started) and add it to your repository:
-
-   ```bash wrap
-   gh aw secrets set ANTHROPIC_API_KEY --value "<your-anthropic-api-key>"
-   ```
+2. Configure the `ANTHROPIC_API_KEY` secret. See [Authentication: ANTHROPIC_API_KEY](/gh-aw/reference/auth/#anthropic_api_key) for setup instructions.
 
 ## Using OpenAI Codex
 
@@ -70,13 +50,7 @@ To use [OpenAI Codex](https://openai.com/blog/openai-codex):
    engine: codex
    ```
 
-2. Configure `OPENAI_API_KEY` GitHub Actions secret.
-
-   [Create an OpenAI API key](https://platform.openai.com/api-keys) and add it to your repository:
-
-   ```bash wrap
-   gh aw secrets set OPENAI_API_KEY --value "<your-openai-api-key>"
-   ```
+2. Configure the `OPENAI_API_KEY` secret. See [Authentication: OPENAI_API_KEY](/gh-aw/reference/auth/#openai_api_key) for setup instructions.
 
 ## Using Google Gemini CLI
 
@@ -88,13 +62,7 @@ To use [Google Gemini CLI](https://github.com/google-gemini/gemini-cli):
    engine: gemini
    ```
 
-2. Configure `GEMINI_API_KEY` GitHub Actions secret.
-
-   [Create a Gemini API key](https://aistudio.google.com/apikey) and add it to your repository:
-
-   ```bash wrap
-   gh aw secrets set GEMINI_API_KEY --value "<your-gemini-api-key>"
-   ```
+2. Configure the `GEMINI_API_KEY` secret. See [Authentication: GEMINI_API_KEY](/gh-aw/reference/auth/#gemini_api_key) for setup instructions.
 
 ## Extended Coding Agent Configuration
 

pkg/cli/engine_secrets.go

@@ -92,7 +92,7 @@ func getSecretRequirementsForEngine(engine string, includeSystemSecrets bool, in
 func getEngineSecretDescription(opt *constants.EngineOption) string {
 	switch opt.Value {
 	case string(constants.CopilotEngine):
-		return "Fine-grained PAT with Copilot Requests permission and repo access where Copilot workflows run."
+		return "Fine-grained PAT with Copilot Requests permission."
 	case string(constants.ClaudeEngine):
 		return "API key from Anthropic Console for Claude API access."
 	case string(constants.CodexEngine):
@@ -237,8 +237,7 @@ func promptForSecret(req SecretRequirement, config EngineSecretConfig) error {
 // promptForCopilotPATUnified prompts the user for a Copilot PAT with detailed instructions
 func promptForCopilotPATUnified(req SecretRequirement, config EngineSecretConfig) error {
 	fmt.Fprintln(os.Stderr, "")
-	fmt.Fprintln(os.Stderr, "GitHub Copilot requires a fine-grained Personal Access Token (PAT) with Copilot permissions.")
-	fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Classic PATs (ghp_...) are not supported. You must use a fine-grained PAT (github_pat_...)."))
+	fmt.Fprintln(os.Stderr, "GitHub Copilot requires a fine-grained Personal Access Token (PAT) with 'Copilot requests' permissions.")
 	fmt.Fprintln(os.Stderr, "")
 	fmt.Fprintln(os.Stderr, "Please create a token at:")
 	fmt.Fprintln(os.Stderr, console.FormatCommandMessage("  "+req.KeyURL))
@@ -247,9 +246,10 @@ func promptForCopilotPATUnified(req SecretRequirement, config EngineSecretConfig
 	fmt.Fprintln(os.Stderr, "  • Token name: Agentic Workflows Copilot")
 	fmt.Fprintln(os.Stderr, "  • Expiration: 90 days (recommended for testing)")
 	fmt.Fprintln(os.Stderr, "  • Resource owner: Your personal account")
-	fmt.Fprintln(os.Stderr, "  • Repository access: \"Public repositories\" (you must use this setting even for private repos)")
-	fmt.Fprintln(os.Stderr, "  • Account permissions → Copilot Requests: Read-only")
+	fmt.Fprintln(os.Stderr, "  • Repository access: \"Public repositories\" (you must use this setting for Copilot Requests permission to appear)")
+	fmt.Fprintln(os.Stderr, "  • Add permissions → Copilot Requests: Read-only")
 	fmt.Fprintln(os.Stderr, "")
+	fmt.Fprintln(os.Stderr, "If you run into trouble see https://github.github.com/gh-aw/reference/auth/#copilot_github_token.")
 
 	var token string
 	form := huh.NewForm(