Merge branch 'main' into simplify/remove-duplicate-getdiscussionid-71a4ced1158b8298

Author: github-actions[bot]

.github/aw/skills.md

@@ -18,6 +18,25 @@ List available skills before choosing a strategy.
 
 ---
 
+## Frontmatter `skills:` (SHA-Pinned Installs)
+
+Declare external skills to install at activation time with the top-level `skills:` array. At activation, `gh aw` installs each via `gh skill install` and wires it into the engine — no manual vendoring.
+
+```yaml
+skills:
+  - owner/repo@<40-char-sha>              # repository-wide install
+  - owner/repo/skill/path@<40-char-sha>   # path-scoped install
+  - skill: owner/repo@<40-char-sha>       # object form: per-skill auth
+    github-token: ${{ secrets.SKILLS_TOKEN }}
+```
+
+- Static references must be pinned to a full 40-character lowercase commit SHA; `${{ ... }}` expressions are allowed in the ref position and resolved at runtime.
+- Object entries set per-skill auth via `github-token` or `github-app`.
+
+This is distinct from the prompt-side strategies below (hint / fusion / inline), which shape skill *content* into the prompt rather than installing skill packages.
+
+---
+
 ## Strategy 0 — Agent Finder (Discovery First)
 
 **Use when**: the relevant skill is not obvious, the repository may not contain the right skill yet, or you want to discover installable skills before loading local ones.

.github/aw/syntax-agentic.md

@@ -17,18 +17,21 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
   - Values limited to 1024 characters
   - Example: `metadata: { team: "platform", priority: "high" }`
 - **`github-token:`** - Default GitHub token for workflow (must use `${{ secrets.* }}` syntax)
-- **`on.roles:`** - Repository access roles that can trigger workflow (array or "all")
-  - Default: `[admin, maintainer, write]`
-  - Available roles: `admin`, `maintainer`, `write`, `read`, `all`
-- **`bots:`** - Bot identifiers allowed to trigger workflow regardless of role permissions (array)
-  - Example: `bots: [dependabot[bot], renovate[bot], github-actions[bot]]`
-  - Bot must be active (installed) on repository to trigger workflow
+- **`on.roles:`** - Repository access roles that can trigger workflow (array or `"all"`). Default `[admin, maintainer, write]`; available roles: `admin`, `maintainer`, `write`, `read`, `all`.
+- **`bots:`** - Bot identifiers allowed to trigger workflow regardless of role permissions (array; e.g. `[dependabot[bot], renovate[bot], github-actions[bot]]`). The bot must be active (installed) on the repository to trigger.
 - **`strict:`** - Enable enhanced validation for production workflows (boolean, defaults to `true`; strongly recommended)
   - Prefer `strict: true`; `strict: false` is dangerous, should be extremely rare, and must be carefully security reviewed before use
 - **`max-turns:`** - AWF turn cap applied consistently across all agentic engines (integer or expression, e.g. `${{ inputs.max-turns }}`). The engine-level `engine.max-turns` is a deprecated alias kept for backward compatibility — prefer this top-level field. Not supported by the `gemini` engine.
 - **`max-runs:`** - Deprecated legacy alias for the AWF invocation cap (`apiProxy.maxRuns`, defaults to `500` when omitted). Use `max-turns` instead; run `gh aw fix` to migrate.
 - **`max-ai-credits:`** - Per-run AI Credits (AIC) budget enforced by the AWF firewall (integer or `K`/`M` short-form string like `100M`; default `1000`). Set a negative value to disable enforcement and token steering. See [token-optimization.md](token-optimization.md).
 - **`max-turn-cache-misses:`** - Maximum consecutive AWF cache misses allowed before the API proxy blocks further requests (integer, default `5`). Maps to `apiProxy.maxCacheMisses`; precedence is frontmatter → `GH_AW_DEFAULT_MAX_TURN_CACHE_MISSES` env override → built-in default.
+- **`models:`** - Model policy and optional pricing (object). Experimental policy fields `allowed` / `blocked` (lists of model names or patterns) restrict which models the workflow may use; they map to AWF `apiProxy.allowedModels` / `disallowedModels` and merge as unions across imports. Environment-variable overrides are supported. The separate `providers` field supplies custom pricing (see [token-optimization.md](token-optimization.md)).
+
+  ```yaml
+  models:
+    allowed: ["gpt-5", "claude-*"]
+    blocked: ["*-preview"]
+  ```
 - **`max-daily-ai-credits:`** - Per-user 24-hour AI Credits (AIC) guardrail: activation blocks execution once the triggering user's aggregated AI Credits for this workflow over the last 24h exceed the threshold (integer or `K`/`M` short-form string, or `-1`). Enabled by default with a system default threshold; set `-1` to disable or an explicit value to override. See [token-optimization.md](token-optimization.md).
 - **`user-rate-limit:`** - Rate limiting configuration to prevent users from triggering the workflow too frequently (object)
   - **`max-runs-per-window:`** - Maximum runs allowed per user per time window (required, integer 1-10)
@@ -45,10 +48,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
       ignored-roles: [admin, maintain]
     ```
 
-- **`check-for-updates:`** - Control whether the activation job checks if the compiled `gh-aw` version is still supported (boolean, default: `true`)
-  - When `true` (default): blocked versions fail fast; below-recommended versions emit a warning
-  - When `false`: skips the version check; the compiler emits a warning at compile time
-  - Use `check-for-updates: false` only when deploying in isolated environments where version update checks are not feasible
+- **`check-for-updates:`** - Whether the activation job checks that the compiled `gh-aw` version is still supported (boolean, default `true`). When `true`, blocked versions fail fast and below-recommended versions warn. Set `false` only for isolated environments (compiler then warns at compile time).
 
 - **`features:`** - Feature flags for experimental or optional features (object)
   - Each flag is a key-value pair; boolean flags (`true`/`false`) or string values are accepted
@@ -346,6 +346,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
       agent: false
     ```
 
+  - **`sandbox.agent.sudo`** (boolean) controls whether AWF runs in root mode. Default is `false`: AWF runs rootless in network-isolation egress mode (`--network-isolation`), with MCP sidecars attached as bridge containers on the internal `awf-net` network. Set `sudo: true` for the legacy root mode; in strict mode explicit `sudo: true` is an error (warning otherwise).
   - **Strict mode**: `sandbox.agent` blocks without an explicit `id: awf` are rejected in strict mode. Any non-nil, non-disabled agent config without `id`/`type` defaults to AWF at runtime.
 
 - **`tools:`** - Tool configuration for the coding agent (`github`, `agentic-workflows`, `edit`, `web-fetch`, `web-search`, `bash`, `playwright`, custom MCP server names, plus `timeout`/`startup-timeout`/`cli-proxy`). See [syntax-tools-imports.md](syntax-tools-imports.md#tool-configuration) for the full schema (GitHub `mode`/`toolsets`/integrity fields, bash allowlist decision rule, Playwright CLI mode).

.github/aw/syntax-core.md

@@ -105,6 +105,12 @@ The YAML frontmatter supports these fields:
   - Exceptions: `id-token: write` is allowed to enable OIDC token minting; `copilot-requests: write` is recommended when targeting the Copilot coding agent so it can authenticate with `${{ github.token }}`
 - **`runs-on:`** - Runner type for the main agent job (string, array, or object)
 - **`runs-on-slim:`** - Runner type for all framework/generated jobs (activation, safe-outputs, unlock, etc.). Defaults to `ubuntu-slim`. `safe-outputs.runs-on` takes precedence for safe-output jobs specifically.
+- **`runner:`** - Runner topology configuration (object). `topology: arc-dind` (only enum value) targets GitHub ARC runners with rootless Docker-in-Docker: gh-aw emits the topology in the AWF config, redirects the tool cache to a shared volume, and validates that no generated step requires root. AWF then activates split-filesystem handling, network isolation, sysroot staging, and DinD pre-staging automatically.
+
+  ```yaml
+  runner:
+    topology: arc-dind
+  ```
 - **`timeout-minutes:`** - Agent execution step timeout in minutes (integer or GitHub Actions expression, defaults to 20 minutes; custom and safe-output jobs use the GitHub Actions platform default of 360 minutes unless explicitly set). Expressions are useful in compiled workflows that define `workflow_call` inputs, for example `timeout-minutes: ${{ inputs.timeout }}`. This setting applies to the workflow being compiled, not to plain GitHub Actions caller jobs that use job-level `uses:` (GitHub does not allow `timeout-minutes` on those caller jobs).
 - **`concurrency:`** - Concurrency control (string or object)
   - **`queue:`** - Pending run queue behavior for the concurrency group (`single` or `max`, defaults to `single`). `single` keeps one pending run and replaces older pending runs; `max` allows up to 100 pending runs in FIFO order (useful for conclusion jobs that must not be dropped).