Surface jobs.<job>.setup-steps in .github/aw syntax docs and clarify setup vs pre hook semantics

.github/aw/reuse.md

@@ -17,7 +17,8 @@ Only these frontmatter fields are merged when a file is imported:
 | `tools:`, `mcp-servers:`, `safe-outputs:`, `network:`, `permissions:`, `runtimes:`, `services:`, `cache:`, `features:` | Deep-merged |
 | `env:` | Merged; duplicate keys → compile error |
 | `github-app:`, `on.github-app:` | First-wins across imports |
-| `steps:`, `pre-steps:`, `pre-agent-steps:`, `post-steps:` | Appended in import order |
+| `steps:`, `pre-agent-steps:`, `post-steps:` | Appended in import order |
+| `jobs.<job-id>.setup-steps`, `jobs.<job-id>.pre-steps` | For each job, imported steps run first, then main workflow steps; `setup-steps` remains separate from `pre-steps` |
 | Markdown body | Appended as prompt instructions |
 
 All other fields (`on:`, `engine:`, `timeout-minutes:`, …) are ignored in imported files.

.github/aw/syntax-agentic.md

@@ -245,13 +245,19 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - Each job can have: `name`, `runs-on`, `steps`, `needs`, `if`, `env`, `permissions`, `timeout-minutes`, etc.
   - For most agentic workflows, jobs are auto-generated; only specify this for advanced multi-job workflows
   - **Security Notice**: Custom jobs run OUTSIDE the firewall sandbox. Execute with standard GitHub Actions security but NO network egress controls. Use only for deterministic preprocessing, data fetching, or static analysis—not agentic compute or untrusted AI execution.
-  - **`pre-steps:`** - Steps injected after compiler-generated setup and before any `steps:` in a custom or built-in job (array). For built-in jobs (`activation`, `pre_activation`), injected after the `id: setup` step and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
+  - **`setup-steps:`** - Steps injected at the earliest point in a custom or built-in job, before framework GitHub App token minting and before checkout (array). Use this for OIDC login, secret fetch, and credential bootstrap that must happen before framework token/checkout steps. Imported `setup-steps` run before main workflow `setup-steps`.
+  - **`pre-steps:`** - Steps injected after framework setup scaffolding and before the job's main `steps:` in a custom or built-in job (array). For built-in jobs, this is after the `id: setup` step (which includes framework token minting/checkout setup) and before the first checkout. Imported `pre-steps` run before main workflow `pre-steps`.
+  - **`setup-steps` vs `pre-steps`** - Use `setup-steps` for work that must run before framework GitHub App token minting and checkout (e.g., OIDC/secret bootstrap). Use `pre-steps` for work that should run later, after setup scaffolding and before the job's main `steps:`.
+  - **Migration note** - No migration is required. `setup-steps` is additive; existing workflows that only use `pre-steps` continue to behave as before.
   - Example:
 
     ```yaml
     jobs:
       custom-job:
         runs-on: ubuntu-latest
+        setup-steps:
+          - name: Bootstrap credentials
+            run: echo "runs before framework token/checkout setup"
         pre-steps:
           - name: Pre-flight setup
             run: echo "runs before checkout"
@@ -260,6 +266,27 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
             run: echo "Custom job"
     ```
 
+  - Built-in job example (OIDC/secret bootstrap before token minting). Replace the placeholder fetch command with your real secret manager/API call:
+
+    ```yaml
+    jobs:
+      activation:
+        setup-steps:
+          - name: Configure cloud credentials with OIDC
+            uses: aws-actions/configure-aws-credentials@v4
+            with:
+              # Replace with your AWS account ID and role ARN.
+              role-to-assume: arn:aws:iam::123456789012:role/gh-aw-activation
+              aws-region: us-east-1
+          - name: Fetch bootstrap token
+            id: bootstrap
+            # Example placeholder; replace with a real secret manager/API call.
+            run: echo "token=fetched-value" >> "$GITHUB_OUTPUT"
+        pre-steps:
+          - name: Verify bootstrap token
+            run: test -n "${{ steps.bootstrap.outputs.token }}"
+    ```
+
 - **`engine:`** - AI processor configuration
   - String format: `"copilot"` (default, recommended), `"claude"`, `"codex"`, `"gemini"`, or `"opencode"` (experimental)
   - Object format for extended configuration:

.github/aw/syntax-core.md

@@ -135,6 +135,7 @@ The YAML frontmatter supports these fields:
 - **`run-name:`** - Custom workflow run name (string)
 - **`name:`** - Workflow name (string)
 - **`pre-steps:`** - Custom workflow steps to run at the very beginning of the agent job, before checkout (object). Use for token minting or setup that must happen before the repository is checked out. Step outputs are available via `${{ steps.<id>.outputs.<name> }}` and can be referenced in `checkout.github-token` to avoid masked-value cross-job boundary issues. Same security restrictions apply as for `steps:`.
+  - For job-scoped hooks under `jobs.<job-id>`, `setup-steps` run before framework GitHub App token minting and checkout, while `pre-steps` run after compiler setup and before the job's main steps.
 - **`steps:`** - Custom workflow steps before AI execution (object). **Security Notice**: Custom steps run OUTSIDE the firewall sandbox with standard GitHub Actions security but NO network egress controls. Use only for deterministic data preparation, not agentic compute. **Secrets restriction**: Using `${{ secrets.* }}` expressions (other than `secrets.GITHUB_TOKEN`) in custom steps is an error in strict mode and a warning otherwise — move secret-dependent operations to a separate job outside the agent job.
 - **`pre-agent-steps:`** - Custom workflow steps to run before MCP gateway startup (object or array). Use when preparation must install or configure MCP dependencies before the gateway starts. Same security restrictions apply as for `steps:`.
 - **`post-steps:`** - Custom workflow steps after AI execution (object). **Security Notice**: Post-execution steps run OUTSIDE the firewall sandbox. Use only for deterministic cleanup, artifact uploads, or notifications—not agentic compute or untrusted AI execution. Same secrets restriction applies as for `steps:`.

.github/aw/syntax-tools-imports.md

@@ -269,7 +269,10 @@ The following frontmatter fields in imported files are merged into the importing
 - `checkout:` - Checkout configurations appended (main workflow's checkouts take precedence)
 - `github-app:` - Top-level GitHub App credentials (first-wins across imports)
 - `on.github-app:` - Activation GitHub App credentials (first-wins across imports)
-- `steps:`, `pre-steps:`, `pre-agent-steps:`, `post-steps:` - Steps appended in import order
+- `steps:` - Steps appended in import order
+- `pre-agent-steps:` - Steps appended in import order
+- `post-steps:` - Steps appended in import order
+- `jobs.<job-id>.setup-steps` and `jobs.<job-id>.pre-steps` - Merged per job with imported steps first, then main workflow steps. Execution order is `setup-steps` before `pre-steps`.
 - `runtimes:`, `network:`, `permissions:`, `services:`, `cache:`, `features:`, `mcp-servers:`
 
 Example import file:

.github/aw/workflow-constraints.md

@@ -62,6 +62,7 @@ When a requested feature increases risk:
 - auto-merge or bypassing review
 - overly broad network access
 - unbounded bash allowlists for untrusted input
+- placing OIDC/secret bootstrap in `pre-steps` instead of earlier `setup-steps`
 - using `post-steps:` for agent-driven write actions
 
 ## Self-Hosted Runner Compatibility