🔐 Refactor auth docs and add GH_AW_CI_TRIGGER_TOKEN magic secret support

.github/aw/create-agentic-workflow.md

@@ -266,7 +266,7 @@ These resources contain workflow patterns, best practices, safe outputs, and per
    **Authentication Setup:**
    ```yaml
    safe-outputs:
-     github-token: ${{ secrets.CROSS_REPO_PAT }}  # PAT with access to target repos
+     github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}  # PAT with access to target repos
      create-issue:
        max: 5
      add-comment:
@@ -315,7 +315,7 @@ These resources contain workflow patterns, best practices, safe outputs, and per
    **Documentation Reference:**
    - Full guide: https://github.github.com/gh-aw/patterns/multi-repo-ops/
    - Safe Outputs Reference: https://github.github.com/gh-aw/reference/safe-outputs/
-   - GitHub Tools: https://github.github.com/gh-aw/reference/tools/#github-tools-github
+   - GitHub Tools: https://github.github.com/gh-aw/reference/github-tools/
 
    **Custom Safe Output Jobs (for new safe outputs):**
 
@@ -618,7 +618,7 @@ Based on the parsed requirements, determine:
 If the workflow involves cross-repository operations, follow these additional guidelines:
 
 **Authentication Configuration:**
-- Add `safe-outputs.github-token: ${{ secrets.CROSS_REPO_PAT }}` for PAT authentication
+- Add `safe-outputs.github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}` for PAT authentication
 - Or use `safe-outputs.app` for GitHub App authentication
 - Document required PAT scopes in the workflow description
 
@@ -648,7 +648,7 @@ tools:
   github:
     toolsets: [repos, issues, pull_requests]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     max: 5
   add-comment:

actions/setup/js/extra_empty_commit.cjs

@@ -9,7 +9,10 @@
  * GITHUB_TOKEN do not trigger other workflow runs.
  *
  * The token comes from `github-token-for-extra-empty-commit` in safe-outputs config
- * (passed as GH_AW_EXTRA_EMPTY_COMMIT_TOKEN env var), or `app` for GitHub App authentication.
+ * (passed as GH_AW_EXTRA_EMPTY_COMMIT_TOKEN env var). Supported values:
+ * - `app` - Use GitHub App token from safe-outputs-app-token step
+ * - `default` - Use the magic secret GH_AW_CI_TRIGGER_TOKEN
+ * - `${{ secrets.CUSTOM_TOKEN }}` - Use a custom PAT or secret
  */
 
 /**

docs/astro.config.mjs

@@ -209,6 +209,7 @@ export default defineConfig({
 					items: [
 						{ label: 'AI Engines', link: '/reference/engines/' },
 						{ label: 'Authentication', link: '/reference/auth/' },
+						{ label: 'Authentication (Projects)', link: '/reference/auth-projects/' },
 						{ label: 'Cache Memory', link: '/reference/cache-memory/' },
 						{ label: 'Command Triggers', link: '/reference/command-triggers/' },
 						{ label: 'Compilation Process', link: '/reference/compilation-process/' },

docs/src/content/docs/examples/multi-repo.md

@@ -26,7 +26,7 @@ All multi-repo workflows require proper authentication:
 gh auth token
 
 # Store as repository or organization secret
-gh aw secrets set CROSS_REPO_PAT --value "ghp_your_token_here"
+gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here"
 ```
 
 The PAT needs permissions **only on target repositories** (not the source repository where the workflow runs): `repo` for private repos, `contents: write` for commits, `issues: write` for issues, and `pull-requests: write` for PRs.
@@ -92,7 +92,7 @@ Most safe output types support the `target-repo` parameter for cross-repository
 
 ```yaml wrap
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     target-repo: "org/tracking-repo"  # Cross-repo: creates in tracking-repo
     title-prefix: "[component] "
@@ -141,7 +141,7 @@ engine:
       uses: actions/checkout@v5
       with:
         repository: org/secondary-repo
-        token: ${{ secrets.CROSS_REPO_PAT }}
+        token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
         path: secondary-repo
 ```
 
@@ -158,6 +158,6 @@ For comprehensive documentation on the MultiRepoOps design pattern, see:
 ## Related Documentation
 
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Configuration options
-- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - API access configuration
+- [GitHub Tools](/gh-aw/reference/github-tools/) - API access configuration
 - [Security Best Practices](/gh-aw/introduction/architecture/) - Authentication and security
 - [Reusing Workflows](/gh-aw/guides/packaging-imports/) - Sharing workflows

docs/src/content/docs/examples/multi-repo/feature-sync.md

@@ -36,7 +36,7 @@ tools:
   bash:
     - "git:*"
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     target-repo: "myorg/downstream-service"
     title-prefix: "[sync] "
@@ -71,7 +71,7 @@ tools:
   bash:
     - "git:*"
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     max: 3
     title-prefix: "[core-sync] "
@@ -103,7 +103,7 @@ tools:
   bash:
     - "git:*"
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     target-repo: "myorg/production-service"
     title-prefix: "[upgrade] "
@@ -139,7 +139,7 @@ tools:
   bash:
     - "git:*"
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     target-repo: "myorg/client-sdk"
     title-prefix: "[types] "
@@ -173,7 +173,7 @@ tools:
   bash:
     - "git:*"
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     target-repo: "myorg/sister-project"
     title-prefix: "[config-sync] "
@@ -208,7 +208,7 @@ tools:
   bash:
     - "git:*"
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     target-repo: "myorg/integration-tests"
     title-prefix: "[feature-test] "
@@ -238,7 +238,7 @@ tools:
   bash:
     - "git:*"
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     target-repo: "myorg/downstream-fork"
     title-prefix: "[weekly-sync] "
@@ -260,7 +260,7 @@ Cross-repo sync workflows require authentication via PAT or GitHub App.
 Create a PAT with `repo`, `contents: write`, and `pull-requests: write` permissions, then store it as a repository secret:
 
 ```bash
-gh aw secrets set CROSS_REPO_PAT --value "ghp_your_token_here"
+gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here"
 ```
 
 ### GitHub App Configuration
@@ -272,4 +272,4 @@ For enhanced security, use GitHub App installation tokens. See [Using a GitHub A
 - [MultiRepoOps Design Pattern](/gh-aw/patterns/multi-repo-ops/) - Complete multi-repo overview
 - [Cross-Repo Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/) - Issue management patterns
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Pull request configuration
-- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - Repository access tools
+- [GitHub Tools](/gh-aw/reference/github-tools/) - Repository access tools

docs/src/content/docs/examples/multi-repo/issue-tracking.md

@@ -31,7 +31,7 @@ tools:
   github:
     toolsets: [issues]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     target-repo: "myorg/central-tracker"
     title-prefix: "[component-alpha] "
@@ -66,7 +66,7 @@ tools:
   github:
     toolsets: [issues]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   add-comment:
     target-repo: "myorg/central-tracker"
     target: "*"  # Find related tracking issue
@@ -99,7 +99,7 @@ tools:
   github:
     toolsets: [issues]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     max: 3  # May create issues in multiple tracking repos
     target-repo: "myorg/central-tracker"
@@ -136,7 +136,7 @@ tools:
     toolsets: [issues]
   web-fetch:
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     target-repo: "myorg/dependency-tracker"
     title-prefix: "[upstream] "
@@ -168,7 +168,7 @@ tools:
   github:
     toolsets: [issues]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     max: 2
     title-prefix: "[auto-triaged] "
@@ -197,7 +197,7 @@ tools:
   github:
     toolsets: [issues]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-discussion:
     target-repo: "myorg/central-tracker"
     category: "Status Reports"
@@ -228,7 +228,7 @@ tools:
   github:
     toolsets: [issues]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     target-repo: "myorg/central-tracker"
     title-prefix: "[linked] "
@@ -261,7 +261,7 @@ tools:
   github:
     toolsets: [issues]
 safe-outputs:
-  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }}
   create-issue:
     max: 1
     title-prefix: "[priority-routed] "
@@ -285,7 +285,7 @@ Cross-repo issue tracking requires appropriate authentication:
 
 ```bash
 # Create PAT with issues and repository read permissions
-gh aw secrets set CROSS_REPO_PAT --value "ghp_your_token_here"
+gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here"
 ```
 
 **Required Permissions:**
@@ -301,4 +301,4 @@ For enhanced security, use GitHub App installation tokens. See [Using a GitHub A
 - [MultiRepoOps Design Pattern](/gh-aw/patterns/multi-repo-ops/) - Complete multi-repo overview
 - [Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/) - Code sync patterns
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Issue creation configuration
-- [GitHub Tools](/gh-aw/reference/tools/#github-tools-github) - API access configuration
+- [GitHub Tools](/gh-aw/reference/github-tools/) - API access configuration

docs/src/content/docs/examples/project-tracking.md

@@ -64,8 +64,6 @@ safe-outputs:
     github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}
 ```
 
-### Configuration Fields
-
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `project` | string | (required) | GitHub Project URL for update-project or create-project-status-update |
@@ -75,38 +73,9 @@ safe-outputs:
 
 See [Safe Outputs: Project Board Updates](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) for complete configuration details.
 
-## Prerequisites
-
-### 1. Create a GitHub Project
-
-Create a Projects V2 board in the GitHub UI before configuring your workflow. You'll need the Project URL from the browser address bar.
-
-### 2. Set Up Authentication
-
-#### For User-Owned Projects
-
-Use a **classic PAT** with scopes:
-- `project` (required)
-- `repo` (if accessing private repositories)
-
-#### For Organization-Owned Projects
-
-Use a **fine-grained PAT** with:
-- Repository access: Select specific repos
-- Repository permissions:
-  - Contents: Read
-  - Issues: Read (if workflow triggers on issues)
-  - Pull requests: Read (if workflow triggers on pull requests)
-- Organization permissions:
-  - Projects: Read & Write
-
-### 3. Store the Token
-
-```bash
-gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_TOKEN"
-```
+### Authentication
 
-See the [GitHub Projects V2 authentication](/gh-aw/reference/auth/#gh_aw_project_github_token) for complete details.
+See [Authentication (Projects)](/gh-aw/reference/auth-projects/).
 
 ## Example: Issue Triage
 
@@ -314,6 +283,6 @@ Update the project item with the team field.
 - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe-outputs documentation
 - [update-project](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) - Detailed update-project configuration
 - [create-project-status-update](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) - Status update configuration
-- [GitHub Projects V2 Authentication](/gh-aw/reference/auth/#gh_aw_project_github_token) - Token setup guide
+- [GitHub Projects Authentication](/gh-aw/reference/auth-projects/) - Token setup guide
 - [Projects & Monitoring](/gh-aw/patterns/monitoring/) - Design pattern guide
 - [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide

docs/src/content/docs/guides/getting-started-mcp.md

@@ -132,17 +132,6 @@ tools:
 ```
 Local mode runs the MCP server in a Docker container, useful for pinning specific versions or offline environments.
 
-### Authentication
-
-Tokens are used in order: `github-token` configuration field, [`GH_AW_GITHUB_TOKEN`](/gh-aw/reference/auth/#gh_aw_github_token) secret, then `GITHUB_TOKEN` (default).
-
-```yaml wrap
-tools:
-  github:
-    github-token: "${{ secrets.CUSTOM_PAT }}"  # Optional custom token
-    toolsets: [default]
-```
-
 ### Read-Only Mode
 
 Restrict operations to read-only for security-sensitive workflows:
@@ -314,7 +303,7 @@ gh aw compile my-workflow --validate --strict
 
 **Tool not found:** Run `gh aw mcp inspect my-workflow` to verify available tools. Ensure the correct toolset is enabled or that tool names in `allowed:` match exactly.
 
-**Authentication errors:** Verify the secret exists in repository settings and has required scopes. For remote mode, set [`GH_AW_GITHUB_TOKEN`](/gh-aw/reference/auth/#gh_aw_github_token) with a PAT.
+**Authentication errors:** Verify the secret exists in repository settings and has required scopes.
 
 **Connection failures:** Check URL syntax for HTTP servers, network configuration for containers, and verify Docker images exist.
 

docs/src/content/docs/index.mdx

@@ -41,7 +41,7 @@ Developed by GitHub Next and Microsoft Research, workflows run with added guardr
   <FeatureCard icon="cpu" title="AI-Powered Decision Making" href="/gh-aw/introduction/how-they-work/">
     Workflows that understand context and adapt to situations
   </FeatureCard>
-  <FeatureCard icon="mark-github" title="GitHub Integration" href="/gh-aw/reference/tools/#github-tools-github">
+  <FeatureCard icon="mark-github" title="GitHub Integration" href="/gh-aw/reference/github-tools/">
     Deep integration with Actions, Issues, PRs, Discussions, and repository management
   </FeatureCard>
   <FeatureCard icon="shield-lock" title="Safety First" href="/gh-aw/introduction/architecture">

docs/src/content/docs/patterns/central-repo-ops.mdx

@@ -48,7 +48,7 @@ on:
 
 tools:
   github:
-    github-token: ${{ secrets.ORG_GITHUB_MCP_SERVER_TOKEN }}
+    github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }}
     toolsets: [repos]
 
 safe-outputs:
@@ -81,7 +81,7 @@ Categorize and orchestrate Dependabot rollout across repositories.
 ```
 
 Compile this workflow to generate the lock file: `gh aw compile`.
-Create a fine-grained PAT `ORG_GITHUB_MCP_SERVER_TOKEN` with the organization as an owner,
+Create a fine-grained PAT `GH_AW_READ_ORG_TOKEN` with the organization as an owner,
 select "All repositories" (or allowlist of specific repos), and grant Repository permission: `Contents: Read-only`.
 Add this into your Actions repository secrets. This gives the orchestrator read access to all candidate repositories.
 
@@ -113,11 +113,11 @@ permissions:
 
 tools:
   github:
-    github-token: ${{ secrets.ORG_GITHUB_MCP_SERVER_TOKEN }}
+    github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }}
     toolsets: [repos]
 
 safe-outputs:
-  github-token: ${{ secrets.REPO_SAFE_OUTPUTS_TOKEN }}
+  github-token: ${{ secretsGH_AW_CROSS_REPO_PAT }}
   create-pull-request:
     target-repo: ${{ github.event.inputs.target_repo }}
     title-prefix: '[dependabot] '