[docs] Update documentation for features from 2026-04-18

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

@@ -61,6 +61,23 @@ Tracks workflow origin in format `owner/repo/path@ref`. Automatically populated
 source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0"
 ```
 
+### Redirect (`redirect:`)
+
+Specifies a new canonical location when a workflow has been moved or renamed. When `gh aw update` encounters a workflow with a `redirect` field, it follows the redirect chain to the resolved location, rewrites the local `source` field to point to the new location, and emits a warning for each redirect hop. Redirect loops are detected and reported as errors.
+
+```yaml wrap
+redirect: "githubnext/agentics/workflows/new-workflow-name.md@main"
+```
+
+Use `gh aw update --no-redirect` to refuse updates when the source workflow has a `redirect` field — the update fails rather than following the redirect. This is useful for auditing or when you want to explicitly control when redirects are followed.
+
+`gh aw compile` emits an informational message when a workflow has a `redirect` field configured, so the redirect is visible during local development.
+
+The `redirect` field uses the same `owner/repo/path@ref` format as `source:`. Redirect chains are followed transitively (up to a depth limit).
+
+> [!NOTE]
+> The `redirect` field is set by workflow *authors* to signal that a workflow has moved. It is not typically set by end-users. If you see a redirect when running `gh aw update`, it means the upstream workflow has been relocated.
+
 ### Private Workflows (`private:`)
 
 Mark a workflow as private to prevent it from being installed into other repositories via `gh aw add`.

docs/src/content/docs/reference/safe-outputs-pull-requests.md

@@ -41,6 +41,9 @@ safe-outputs:
     target-repo: "owner/repo"     # cross-repository
     allowed-repos: ["org/repo1", "org/repo2"]  # additional allowed repositories
     base-branch: "vnext"          # target branch for PR (default: github.base_ref || github.ref_name)
+    allowed-base-branches:        # allow agent to override base branch at runtime (glob patterns)
+      - main
+      - release/*
     fallback-as-issue: false      # disable issue fallback (default: true)
     auto-close-issue: false       # don't auto-add "Fixes #N" to PR description (default: true)
     preserve-branch-name: true    # omit random salt suffix from branch name (default: false)
@@ -54,6 +57,17 @@ safe-outputs:
 
 The `base-branch` field specifies which branch the pull request should target. This is particularly useful for cross-repository PRs where you need to target non-default branches (e.g., `vnext`, `release/v1.0`, `staging`). When not specified, defaults to `github.base_ref` (the PR's target branch) with a fallback to `github.ref_name` (the workflow's branch) for push events.
 
+The `allowed-base-branches` field enables per-run base branch overrides by the agent at runtime. When configured, the agent may supply a `base` field in the `create_pull_request` tool call to target a branch other than the compiled `base-branch`. The override is accepted only when it matches one of the configured glob patterns (e.g., `main`, `release/*`). Without `allowed-base-branches`, only the compiled `base-branch` is used regardless of what the agent requests. This is useful when agent-computed data (such as a version string or user request) determines the target branch at runtime:
+
+```yaml wrap
+safe-outputs:
+  create-pull-request:
+    base-branch: main
+    allowed-base-branches:
+      - main
+      - release/*
+```
+
 **Example use case:** A workflow in `org/engineering` that creates PRs in `org/docs` targeting the `vnext` branch for feature documentation:
 
 ```yaml wrap

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

@@ -239,7 +239,13 @@ gh aw fix --list-codemods              # List available codemods
 
 **Options:** `--write`, `--list-codemods`
 
-Notable codemods include `expires-integer-to-string`, which converts bare integer `expires` values (e.g., `expires: 7`) to the preferred day-string format (e.g., `expires: 7d`) in all `safe-outputs` blocks. Run `gh aw fix --list-codemods` to see all available codemods.
+Available codemods include:
+
+- `expires-integer-to-string` — converts bare integer `expires` values (e.g., `expires: 7`) to the preferred day-string format (e.g., `expires: 7d`) in all `safe-outputs` blocks.
+- `steps-run-secrets-to-env` — rewrites inline `${{ secrets.NAME }}` interpolations in step `run:` commands to `$NAME` and adds step-level `env` bindings. Required for strict-mode compliance.
+- `engine-env-secrets-to-engine-config` — removes secret-bearing entries from `engine.env` that are unsafe under strict mode, preserving required engine credential keys.
+
+Run `gh aw fix --list-codemods` to see all available codemods.
 
 #### `compile`
 
@@ -552,7 +558,9 @@ gh aw update --disable-release-bump       # Update workflows; only force-update
 gh aw update --create-pull-request        # Update and open a pull request
 ```
 
-**Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile`
+**Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile`, `--no-redirect`
+
+The `--no-redirect` flag causes `update` to fail when the source workflow has a [`redirect`](/gh-aw/reference/frontmatter/#redirect) field, rather than following the redirect to its new location. Use this when you want explicit control over redirect handling.
 
 #### `upgrade`