[workshop] Add node: Organization-Wide Governance with gh aw env

workshop/26-manage-costs-and-budgets.md

@@ -104,6 +104,9 @@ In this example, each run is capped at 1000 AIC and the 24-hour total is capped
 gh aw compile
 ```
 
+> [!TIP]
+> Managing many repositories instead of just one? Try [Side Quest: Organization-Wide Governance with `gh aw env`](side-quest-26-02-organization-governance.md) to set these same guardrails at organization or enterprise scope, so every workflow inherits them without per-file edits.
+
 ## :white_check_mark: Checkpoint
 
 - [ ] You located your AIC usage for this billing cycle in the GitHub billing dashboard

workshop/README.md

@@ -105,6 +105,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [Audit Reference — Artifacts, Firewall Logs, and Report Contents](side-quest-25-01-audit-reference.md) — detailed breakdown of `gh aw audit` report fields, agent artifact files, ⌖ AIC billing, `firewall.md`, and `network.allow`; branches from [Step 25](25-audit-and-observability.md).
 - [Self-Hosted Runner Infrastructure Deep Dive](side-quest-24-01-runner-infrastructure.md) — enterprise infrastructure primer covering ephemeral and JIT runners, proxy configuration, and network isolation for air-gapped environments; branches from [Step 24](24-self-hosted-runners.md).
 - [Project Future AI Credit Costs with `gh aw forecast`](side-quest-26-01-forecast-costs.md) — full walkthrough of `gh aw forecast`: reading P10/P50/P90 output, using `--period week` and `--days 7`, forecasting all workflows, and deriving a `max-daily-ai-credits` value from the P90 figure; branches from [Step 26](26-manage-costs-and-budgets.md).
+- [Organization-Wide Governance with `gh aw env`](side-quest-26-02-organization-governance.md) — enterprise/platform-admin guide to setting `GH_AW_DEFAULT_*` cost and timeout guardrails and `GH_AW_POLICY_*` capability gates at repository, organization, or enterprise scope with `gh aw env`; branches from [Step 26](26-manage-costs-and-budgets.md).
 - [Skill Injection Strategies — Hint, Fusion, and Inline](side-quest-29-01-skill-injection-strategies.md) — decision table, code examples, and a practice exercise for the hint, fusion, and inline strategies for wiring a `SKILL.md` into a workflow prompt; branches from [Step 29](29-skills-and-domain-knowledge.md).
 - [Recognizing Common Agentic Workflow Failure Modes](side-quest-22-01-failure-modes.md) — worked examples of empty data, tool error, timeout, and prompt drift failures with a match-the-fix practice exercise; branches from [Step 22](22-error-handling-and-resilience.md).
 - [How the `agentic-workflows` Skill Dispatcher Works](side-quest-10-03-skill-dispatcher.md) — full task-type table with trigger phrases, plus practice scenarios for matching a request to the Edit, Debug, or Optimize path; branches from [Step 9](09-agentic-editing.md).

workshop/side-quest-26-02-organization-governance.md

@@ -0,0 +1,108 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+# Side Quest: Organization-Wide Governance with `gh aw env`
+
+> _A companion to [Manage Costs and AI Credit Budgets](26-manage-costs-and-budgets.md). Use this side quest if you're a platform admin, or if you want every repository in your org to inherit the same cost guardrails instead of setting `max-ai-credits` by hand in every workflow file._
+
+## :dart: What You'll Do
+
+You'll export current `gh aw` defaults, change one value, and apply it at repository scope with `gh aw env update --dry-run` before committing to a real change. You'll also see how organization and enterprise scopes percolate down so a single setting can cover many repositories at once.
+
+## :clipboard: Before You Start
+
+- You completed [Manage Costs and AI Credit Budgets](26-manage-costs-and-budgets.md) and understand `max-ai-credits` and `max-daily-ai-credits`.
+- You have **admin** access to a repository (organization or enterprise scope requires org/enterprise admin permissions instead).
+
+## Understand what `gh aw env` manages
+
+Instead of editing `max-ai-credits` in every workflow file across every repository, `gh aw env` sets `GH_AW_DEFAULT_*` values as [GitHub Actions variables](https://docs.github.com/en/actions/learn-github-actions/variables) at **repository**, **organization**, or **enterprise** scope. Any workflow that doesn't set an explicit frontmatter value falls back to these defaults.
+
+Scopes percolate from most to least specific — a repository variable always wins over an organization one, which wins over an enterprise one:
+
+1. Workflow frontmatter value (if set)
+2. Repository variable
+3. Organization variable
+4. Enterprise variable
+5. Built-in compiler fallback
+
+This means you can set a conservative enterprise-wide baseline, loosen it for specific organizations that need more headroom, and let individual workflows override only when truly necessary.
+
+## Steps
+
+### Export current defaults
+
+Start by seeing what's already configured at repository scope. This step is read-only and safe to run on any repository you can access:
+
+```bash
+gh aw env get repo-defaults.yml --scope repo --repo OWNER/REPO
+```
+
+Open `repo-defaults.yml`. If nothing has been set yet, most keys will be empty — that's expected for a first run.
+
+### Edit one value
+
+Open `repo-defaults.yml` and set a conservative daily spending guardrail:
+
+```yaml title="repo-defaults.yml"
+default_max_daily_ai_credits: "2500"
+default_timeout_minutes: "15"
+```
+
+> [!NOTE]
+> Set a key to `null` (or remove the line) to delete that variable from the scope during `gh aw env update`.
+
+### Preview before applying
+
+Always preview with `--dry-run` first — it shows exactly which variables would change without writing anything:
+
+```bash
+gh aw env update repo-defaults.yml --scope repo --repo OWNER/REPO --dry-run
+```
+
+Read the output carefully. Confirm only the keys you intended to change are listed.
+
+### Apply the change
+
+Once the dry run looks correct, apply it for real:
+
+```bash
+gh aw env update repo-defaults.yml --scope repo --repo OWNER/REPO
+```
+
+Any workflow in that repository without its own `max-daily-ai-credits` now inherits `2500` automatically — no frontmatter edits required.
+
+### Scale to organization or enterprise scope
+
+The same commands work at wider scopes if you have the right admin access. Organization and enterprise scopes also accept a `--visibility` flag (`all`, `private`, or `selected`) that controls which repositories can see the variable:
+
+```bash
+gh aw env update org-defaults.yml --scope org --org MY_ORG --visibility all --dry-run
+gh aw env update org-defaults.yml --scope org --org MY_ORG --visibility all
+```
+
+> [!TIP]
+> Roll out governance in layers: set an enterprise baseline first, add organization-level overrides only where a team genuinely needs different limits, and keep repository-level and workflow-level overrides rare and explicit. This keeps most repositories aligned while still allowing narrow exceptions.
+
+## Policy variables: hard capability gates
+
+`GH_AW_DEFAULT_*` values are **defaults** — a workflow can still override them in its own frontmatter. For capabilities you want to block outright, use `GH_AW_POLICY_*` variables instead. For example, to stop every workflow in an organization from opening pull requests, regardless of what any workflow's frontmatter says:
+
+```bash
+gh variable set GH_AW_POLICY_ALLOW_CREATE_PULL_REQUEST \
+  --org MY_ORG --body "false"
+```
+
+With this policy active, any workflow configured with `safe-outputs.create-pull-request` fails at startup with a clear error naming the blocking policy variable — instead of silently running with reduced capability.
+
+## :white_check_mark: Checkpoint
+
+- [ ] You ran `gh aw env get` and reviewed the current repository-scope defaults
+- [ ] You edited a defaults YAML file with at least one `default_` key
+- [ ] You ran `gh aw env update --dry-run` and confirmed the preview matched your intent
+- [ ] You applied the change with `gh aw env update` (without `--dry-run`)
+- [ ] You can explain the precedence order: frontmatter > repository > organization > enterprise > compiler fallback
+- [ ] You can name one `GH_AW_POLICY_*` variable and what it blocks
+
+<!-- journey: all -->
+Return to [Manage Costs and AI Credit Budgets](26-manage-costs-and-budgets.md).
+<!-- /journey -->