[docs] Update documentation for features from 2026-01-22

docs/src/content/docs/reference/permissions.md

@@ -32,6 +32,21 @@ This model prevents AI agents from accidentally or maliciously modifying reposit
 
 Key permissions include `contents` (code access), `issues` (issue management), `pull-requests` (PR management), `discussions`, `actions` (workflow control), `checks`, `deployments`, `packages`, `pages`, and `statuses`. Each has read and write levels. See [GitHub's permissions reference](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) for the complete list.
 
+#### Special Permission: `id-token`
+
+The `id-token: write` permission is a special case that is explicitly allowed in workflows, including strict mode. This permission enables [OpenID Connect (OIDC) authentication](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) for cloud provider authentication (AWS, GCP, Azure) without storing long-lived credentials.
+
+Unlike other write permissions, `id-token: write` does not grant any ability to modify repository content. It only allows the workflow to request a short-lived OIDC token from GitHub's token service for authentication with external cloud providers.
+
+```yaml wrap
+# Example: Deploy to AWS using OIDC authentication
+permissions:
+  id-token: write      # Allowed for OIDC authentication
+  contents: read       # Read repository code
+```
+
+This permission is safe to use and does not require safe-outputs, even in strict mode.
+
 ## Configuration
 
 ### Basic Configuration
@@ -111,6 +126,8 @@ permissions:
   contents: read
 ```
 
+**Exception:** The `id-token: write` permission is explicitly allowed as it is used for OIDC authentication with cloud providers and does not grant repository write access.
+
 #### Migrating Existing Workflows
 
 To migrate workflows with write permissions, use the automated codemod (recommended):

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

@@ -127,11 +127,24 @@ gh aw init --codespaces                 # Configure devcontainer for current rep
 gh aw init --codespaces repo1,repo2     # Configure devcontainer for additional repos
 gh aw init --campaign                   # Enable campaign functionality
 gh aw init --completions                # Install shell completions
+gh aw init --push                       # Initialize and automatically commit/push changes
 ```
 
 **Interactive Mode:** When invoked without `--engine`, prompts you to select an engine and optionally configure repository secrets using the `gh` CLI.
 
-**Options:** `--engine` (copilot, claude, codex), `--no-mcp`, `--tokens`, `--codespaces`, `--campaign`, `--completions`
+**Options:** `--engine` (copilot, claude, codex), `--no-mcp`, `--tokens`, `--codespaces`, `--campaign`, `--completions`, `--push`
+
+##### `--push` Flag
+
+The `--push` flag automatically commits and pushes initialization changes to the remote repository:
+
+1. **Pre-check**: Validates working directory is clean before starting
+2. **Initialization**: Runs normal init process
+3. **Automatic commit**: Stages all changes with commit message "chore: initialize agentic workflows"
+4. **Pull and push**: Pulls latest changes with rebase, then pushes to remote
+5. **Graceful fallback**: If no remote is configured (local testing), commits locally only
+
+When used, requires a clean working directory (no uncommitted changes) before starting.
 
 #### `add`
 
@@ -381,6 +394,32 @@ gh aw update ci-doctor --major --force    # Allow major version updates
 
 **Options:** `--dir`, `--merge`, `--major`, `--force`
 
+#### `upgrade`
+
+Upgrade the gh-aw extension and update all workflow files to the latest version. Applies codemods to fix deprecated fields, updates agent instruction files, and recompiles workflows.
+
+```bash wrap
+gh aw upgrade                              # Upgrade extension and all workflows
+gh aw upgrade --no-fix                     # Update agent files only (skip codemods and compilation)
+gh aw upgrade --push                       # Upgrade and automatically commit/push changes
+gh aw upgrade --push --no-fix              # Update agent files and push
+```
+
+**Options:** `--dir`, `--no-fix`, `--push`
+
+##### `--push` Flag
+
+The `--push` flag automatically commits and pushes upgrade changes to the remote repository:
+
+1. **Pre-check**: Validates working directory is clean before starting
+2. **Version check**: Ensures gh-aw extension is on latest version
+3. **Upgrade process**: Updates agent files, applies codemods, and recompiles workflows
+4. **Automatic commit**: Stages all changes with commit message "chore: upgrade agentic workflows"
+5. **Pull and push**: Pulls latest changes with rebase, then pushes to remote
+6. **Graceful fallback**: If no remote is configured (local testing), commits locally only
+
+When used, requires a clean working directory (no uncommitted changes) before starting.
+
 ### Advanced
 
 #### `mcp`