[docs] Update documentation for features from 2025-10-18

docs/src/content/docs/reference/frontmatter.md

@@ -22,7 +22,7 @@ tools:
 
 ## Frontmatter Elements
 
-The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout_minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `imports`, `engine`, `strict`, `roles`, `safe-outputs`, `network`, `tools`, `cache-memory`).
+The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout_minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `github-token`, `imports`, `engine`, `strict`, `roles`, `safe-outputs`, `network`, `tools`, `cache-memory`).
 
 ### Trigger Events (`on:`)
 
@@ -60,6 +60,23 @@ source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0"
 
 When you run `gh aw add githubnext/agentics/ci-doctor@v1.0.0`, the source field is automatically added to the workflow frontmatter. This field is optional for manually created workflows.
 
+### GitHub Token (`github-token:`)
+
+The `github-token:` field configures the default GitHub token for the entire workflow. This token is used for engine authentication, checkout steps, and safe-output operations unless overridden at more specific levels.
+
+```yaml
+github-token: ${{ secrets.CUSTOM_PAT }}
+```
+
+The token precedence hierarchy allows fine-grained control:
+
+1. **Individual safe-output `github-token`** (highest priority) - e.g., `create-issue.github-token`
+2. **Safe-outputs global `github-token`** - e.g., `safe-outputs.github-token`
+3. **Top-level `github-token`** - Workflow-level default
+4. **Default fallback** - `${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}`
+
+This enables setting a workflow default while allowing specific operations to use different tokens. See the [Security Guide](/gh-aw/guides/security/#authorization-and-token-management) for complete token configuration documentation.
+
 ### Permissions (`permissions:`)
 
 The `permissions:` section uses standard GitHub Actions permissions syntax to specify the permissions relevant to the agentic (natural language) part of the execution of the workflow. See [GitHub Actions permissions documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).

docs/src/content/docs/tools/cli.md

@@ -56,6 +56,7 @@ gh aw new issue-handler --force
 gh aw add githubnext/agentics/ci-doctor
 gh aw add githubnext/agentics/ci-doctor --name my-custom-doctor --pr --engine copilot
 gh aw add githubnext/agentics/ci-doctor --number 3  # Create 3 copies
+gh aw add githubnext/agentics/ci-doctor --append "Extra content"  # Append custom content
 
 # Remove workflows
 gh aw remove WorkflowName
@@ -127,6 +128,7 @@ gh aw trial ./my-local-workflow.md         # Test local file
 gh aw trial workflow1 workflow2            # Compare multiple workflows
 gh aw trial ./workflow.md --logical-repo myorg/myrepo --host-repo myorg/host-repo # Act as if in a different logical repo. Uses PAT to see issues/PRs
 gh aw trial ./workflow.md --clone-repo myorg/myrepo --host-repo myorg/host-repo # Copy the code of the clone repo for into host repo. Agentic will see the codebase of clone repo but not the issues/PRs.
+gh aw trial ./workflow.md --append "Extra content"  # Append custom content to workflow
 
 # Test issue-triggered workflows with context
 gh aw trial ./issue-workflow.md --trigger-context https://github.com/owner/repo/issues/123
@@ -138,6 +140,7 @@ Other flags:
  --repeat N                  # Repeat N times
  --force-delete-host-repo-before  # Force delete existing host repo BEFORE start
  --delete-host-repo-after         # Delete host repo AFTER trial
+ --append TEXT                # Append extra content to workflow files
 ```
 
 Trial results are saved to `trials/` directory and captured in the trial repository for inspection. Set `GH_AW_GITHUB_TOKEN` to override authentication. See the [Security Guide](/gh-aw/guides/security/#authorization-and-token-management).