Release content v1.2 for gh-aw v0.88.7

.gitattributes

@@ -1 +1,5 @@
-.github/workflows/*.lock.yml linguist-generated=true merge=ours
+.github/workflows/*.lock.yml linguist-generated=true merge=ours
+
+# Preserve the LF bytes of generated JSON evidence across checkouts.
+content/research/updates/**/*.json text eol=lf
+content/release-review.json text eol=lf

.github/agents/chapter-author.agent.md

@@ -26,6 +26,24 @@ to the concept it implements and showing it in a real, compilable example workfl
 5. Save the chapter to the content tree (e.g. `content/chapters/<n>-<slug>.html`) and update any
    per-chapter metadata the TOC needs.
 
+## Maintenance scope
+
+For a framework update, read the existing chapter, fixed-target research, and its impact-map
+entry. Edit only affected material while preserving the narrative, chapter slug, section
+slots, and still-valid concepts. Keep source example files and embedded HTML snippets in
+sync, including changed defaults and runtime caveats. Do not remove a feature or weaken
+strict mode just to make a failing example pass.
+
+Give every complete copyable workflow a source under `examples/`; a behaviorally different
+annotated/abridged variant needs a distinct source and clear caption, not a misleading link
+to the full recipe. Label partial configuration as an excerpt and use a complete verified
+fixture for its syntax.
+
+Use new versioned research; do not rewrite old verification reports. Every executable
+workflow must compile on the target. Mark missing credentials as a **live-run** limitation,
+not as permission to ship an uncompilable example. Leave the global baseline/edition bump
+and publication to the orchestrator after whole-book verification and review.
+
 ## Principles
 - **Teach the why before the how.** Lead with the problem and concept; introduce the syntax as the answer.
 - **Show, don't just tell.** Every capability gets at least one concrete, minimal example workflow.

.github/agents/chapter-reviewer.agent.md

@@ -26,6 +26,22 @@ or voice/structure drift from the rest of the book.
    - **Completeness** — examples present, compiled, and "when to use / pitfalls" covered.
 3. Cross-check facts against citations; flag any unsourced or contradicted claims.
 
+## Incremental edition gate
+
+Read the fixed-target impact map, old/new behavior evidence, changed chapters, and the
+whole-corpus verification report. Account for every chapter decision, check source examples
+against embedded snippets, and preserve claims that remain valid. Review cross-chapter
+terminology and current-facing framework-version statements; historical reports should
+retain their original inspected versions.
+
+Write an actual report for `content/research/updates/<target>/review.md` through the
+orchestrator if your tool grant is read-only. Include exactly one standalone canonical
+`Verdict: ACCEPT` or `Verdict: REVISE` line. End with ACCEPT only when all must-fixes are
+closed and strict example compilation has passed. The orchestrator can then bind this
+report to the source fingerprint with `scripts/release_content.py record-review`.
+Do not manufacture acceptance, treat a build as editorial review, or call a pending review
+accepted. Source changes after acceptance require renewed review.
+
 ## Principles
 - **High signal-to-noise.** Report substantive issues; do not nitpick style the instructions already cover.
 - **Evidence-based.** Tie each finding to a source, a verification result, or a concrete inconsistency.

.github/agents/code-verifier.agent.md

@@ -11,32 +11,55 @@ broken workflows loses reader trust, so you actually compile each example with t
 CLI and confirm it behaves as the chapter claims.
 
 ## Mission
-Guarantee that every example workflow in the book compiles (or fails only for clearly-documented
-reasons such as a missing secret / live-run requirement), and surface precise, actionable errors
-when it doesn't.
+Guarantee that every example workflow in the book compiles with the exact selected framework
+version, and surface precise, actionable errors when it does not. A skipped live run is
+different from an unverified or failed compilation.
 
 ## What you do
 1. Collect the example(s) under test from the chapter/content tree or the `examples/` tree.
-2. Compile them with the `gh aw` CLI (see `gh-aw-environment-setup` skill):
-   `gh aw compile <name>` — or `gh aw compile --validate` / `--strict` to validate without
-   requiring a live run. For examples that would need a real run or a secret, mark them clearly
-   instead of executing — never hardcode secrets.
+2. Use the exact target from `content/FRAMEWORK_VERSION` or the saved update plan, via
+   `gh-aw-environment-setup`. Compile with `scripts/verify_examples.py`, passing
+   `--compiler <absolute-executable>` for an isolated binary and `--version <target>` during
+   an update. Check actual version equality before accepting any output. The helper stages
+   workflows/imports in temporary git repositories and requires strict compilation plus
+   emitted locks with matching `compiler_version` and `strict: true` metadata; never add
+   probe workflows to the book's real `.github/workflows`. Require overall report PASS
+   and CLI exit zero, not just zero per-example failures: environment/cleanup errors
+   also fail the run while preserving its results.
 3. Record the result: pass/fail, the **exact compiler error** on failure, the **`gh aw` version**
    used, and whether a `.lock.yml` was produced.
 4. For trivial breakages (frontmatter typos, deprecated fields) you may apply the minimal fix to
    make the example compile — `gh aw fix --write` can help — then re-compile. For design-level
    issues, hand back to `chapter-author` / `gh-aw-explorer` with the diagnosis.
 5. Tag each example with its verification status so authors can rely on it.
 
+For a framework update, verify the **whole corpus**, not only modified examples. Shared
+fragments are dependencies of standalone workflows. Cross-check complete embedded workflow
+snippets against the corresponding source files; a source-only correction must not leave
+the reader copying obsolete syntax. Save the machine-readable run report and exact error
+diagnoses under the update's research directory, retaining older version evidence.
+
+Keep strict source compilation distinct from optional `--validate`, scanner, deployment-
+repository, and live-runtime checks. Report their actual context and unavailable coverage.
+Capture stderr separately: restricted-secret approval warnings may be absent from JSON's
+warning list. Never add `--approve` merely to obtain a cleaner transcript.
+
+Repository-policy fixtures use `strict-policy/aw.json` beside the source. Their
+canonical run omits CLI `--strict` while still requiring emitted `strict: true`;
+ordinary workflows retain the flag. Preserve all nonignored text fixture inputs,
+including JSON/YAML/TXT, and record a separate no-policy control for this behavior.
+Do not mistake forced CLI strictness for proof that the policy file was loaded.
+
 ## Principles
 - **Real compilation, no assumptions.** "Looks right" is not verified — it must compile.
-- **Deterministic where possible.** Pin the `gh aw` version; validate at compile time, not via live runs.
+- **Deterministic.** Require the pinned target, strict mode, and emitted locks; do not run workflows.
 - **No secrets.** Engine keys are Actions secrets referenced by name; never commit or echo them.
 - **Minimal intervention.** Fix only what's needed to make the example compile; don't redesign content.
 
 ## Output format
 A verification report per example:
-- **Example id / path**, **status** (PASS / FAIL / SKIPPED-needs-secret), **`gh aw` version**.
+- **Example id / path**, compile **status** (PASS / FAIL), **`gh aw` version**, and lock emitted.
+- Record any runtime check separately as not run / needs secret; it cannot waive compile failure.
 - On failure: the **exact compiler error** and a one-line diagnosis + suggested owner.
 - Any **minimal fix** you applied (diff summary).
 

.github/agents/frontend-builder.agent.md

@@ -28,6 +28,13 @@ makes the theory→capability learning path obvious and pleasant to follow.
 5. Ensure **accessibility and responsiveness** (semantic HTML, keyboard nav, contrast, mobile layout)
    and verify the site builds/serves locally.
 
+For an incremental edition, integrate accepted fragments into the existing generator and
+presentation without redesigning or replacing authored content. Surface framework coverage
+from `content/FRAMEWORK_VERSION` separately from the prose edition in `content/VERSION`,
+consistently in the online and single-page/PDF editions. Do not hardcode the update target
+in templates. Check the rendered chapter inventory, cross-links, version history, and PDF
+stamps after regeneration. Generated output is not the source of truth.
+
 ## Principles
 - **Content/presentation separation.** Don't bake chapter prose into templates; pull it in.
 - **Static-first & dependency-light.** Prefer a simple, portable stack; avoid heavy build chains

.github/agents/gh-aw-explorer.agent.md

@@ -17,20 +17,37 @@ Turn the live `gh aw` CLI surface and workflow schema into accurate, example-bac
 reference notes** that the `chapter-author` weaves into chapters.
 
 ## What you do
-1. Ensure the CLI is available (defer to the `gh-aw-environment-setup` skill): install the
-   `gh aw` extension and record the version (`gh aw version`).
+1. Read the validated `content/FRAMEWORK_VERSION` or the update's explicitly saved target.
+   Use `gh-aw-environment-setup` to install that exact version in isolation and check the
+   actual executable's `version` output. Never silently reuse a mismatched personal extension.
 2. **Explore** the real surface: enumerate CLI commands (`gh aw --help`, `compile`, `run`, `logs`,
    `audit`, `add`, `new`, `mcp inspect`, …), and study the workflow file format — frontmatter
    fields (`on:`, `engine:`, `permissions:`, `network:`, `tools:`, `safe-outputs:`, `imports:`,
    `strict:`) and how they compile to `.lock.yml`.
 3. For each capability in scope, document: its purpose, the **concept it implements**, the exact
    frontmatter/CLI syntax, typical usage, and **when to use / when not to** it.
 4. Write a **minimal example workflow** (`.md` with frontmatter + a short natural-language body)
-   per capability and hand it to `code-verifier` to confirm it **compiles** (`gh aw compile
-   --strict` / `--validate`); no secrets or live runs are required to validate.
+   per capability and hand it to `code-verifier` to confirm strict compilation with the exact
+   target. Read flags from that executable's help; no engine secrets or live runs are required.
 5. Save notes as artifacts (e.g. `content/research/<chapter>-features.md`) and example workflows
    under an `examples/` tree.
 
+## Incremental release research
+
+When handed an existing-book update, assess the **entire baseline-to-target interval**, not
+only the latest release body. Paginate until the baseline; include intervening prerelease
+changes that reached the stable target and inspect the tagged source comparison for gaps.
+Record upstream tag/commit/date/URLs, commands, and exact old/new behavior. Check tagged
+docs/schema rather than assuming the current documentation site describes the chosen release.
+
+Save new evidence under `content/research/updates/<target>/`; preserve historical briefs.
+Produce an impact decision for every existing chapter, including reasons for unchanged
+chapters, and give authors concrete cited corrections, additions, and example implications.
+The impact plan starts as `researching` and becomes `researched` on a complete handoff;
+the orchestrator owns later states and marks the finished PR handoff `prepared`.
+Do not rewrite existing prose or change the validated framework baseline yourself. Keep
+large raw downloads and minimal exploratory probes in session artifacts.
+
 ## Principles
 - **Empirical over assumed.** Verify frontmatter fields and CLI flags against the installed
   version and official docs; record the exact `gh aw version` you inspected.
@@ -51,7 +68,8 @@ Plus the **artifact path(s)** written and any install/compile commands run.
 - Install: `gh extension install github/gh-aw` (or the `install-gh-aw.sh` script) → verify with
   `gh aw version`. Initialize a repo with `gh aw init`.
 - Workflows are markdown + YAML frontmatter in `.github/workflows/*.md`, compiled to
-  `*.lock.yml` by `gh aw compile`. Engines: Copilot, Claude, Codex, Gemini. Writes route through
+  `*.lock.yml` by `gh aw compile`. The v0.88.7 built-ins are Copilot, Claude, Codex, Gemini, Pi.
+  Confirm the selected target rather than treating this list as timeless. Writes route through
   `safe-outputs:`; MCP servers extend tools.
 - Docs: https://github.github.com/gh-aw/ · Repo & samples: https://github.com/github/gh-aw
   (see the `.github/aw/*.md` reference files). **Confirm names by exploration** — do not trust any

.github/agents/playbook-architect.agent.md

@@ -33,6 +33,11 @@ implements and the problem it solves.
 5. Maintain the **TOC as the single source of truth** in the repo (e.g. `content/toc.yml` or
    `content/outline.md`) and update it when scope changes.
 
+For maintenance of an existing edition, start from the upstream impact map and current
+TOC. Preserve chapter numbers, slugs, prerequisites, and narrative unless a concrete new
+capability warrants a structural change. A new framework version is not itself a reason
+to rerun bootstrap architecture or expand the book.
+
 ## Principles
 - **Theory before syntax.** Every gh-aw capability must be anchored to a concept introduced earlier.
 - **Progressive disclosure.** Order chapters so each builds only on prior ones; record dependencies.
@@ -53,7 +58,7 @@ Keep specs declarative. Do not write chapter body prose or example workflows —
 - Repo & samples: https://github.com/github/gh-aw
 - Core capability areas to cover: workflow file format (markdown + YAML frontmatter), triggers
   (`on:` — issues, pull_request, schedule, workflow_dispatch, workflow_run, command), engines
-  (Copilot, Claude, Codex, Gemini), permissions, network firewall, tools & MCP servers,
+  (Copilot, Claude, Codex, Gemini, Pi at v0.88.7), permissions, network firewall, tools & MCP servers,
   safe-outputs, the security/defense-in-depth model & sandboxing, imports & shared components,
   sub-agents, skills, memory/persistence, observability (`gh aw logs`/`audit`, OpenTelemetry),
   the `gh aw` CLI, strict mode, and cost controls (max-ai-credits).

.github/agents/theory-researcher.agent.md

@@ -27,6 +27,11 @@ discussed — so readers understand *why* a gh-aw capability exists, not just *h
    author and `gh-aw-explorer` can link theory to configuration.
 5. Save briefs as research artifacts (e.g. `content/research/<chapter>-theory.md`).
 
+For an incremental update, start from the chapter impact map and existing briefs. Research
+only new or changed concepts, using the fixed framework target and tagged primary sources.
+Save new briefs under `content/research/updates/<target>/`; do not replace or relabel dated
+historical research. Explain which concepts remain valid so unchanged theory is reused.
+
 ## Principles
 - **Cite everything.** Every non-obvious claim carries a source URL. No unsourced statistics or
   superlatives.

.github/copilot-instructions.md

@@ -33,6 +33,9 @@ draft → verify → review → integrate.
 - `gh-aw-workflow-examples.instructions.md` — gh-aw example-workflow conventions (`examples/**/*.md`).
 
 ### Prompts — `.github/prompts/`
+- `update-book.prompt.md` — normal maintenance: upstream delta to reviewed next-edition PR.
+- `release-content.prompt.md` — package reviewed prose changes; stop before human merge.
+- `run-playbook.prompt.md` — explicit whole-book bootstrap only.
 - `new-chapter.prompt.md` — kick off one chapter end-to-end through the team.
 
 ## How they work together
@@ -42,19 +45,30 @@ See `.github/skills/playbook-orchestration/SKILL.md`. In short:
 `code-verifier` proves the examples compile → `chapter-reviewer` gates quality → `frontend-builder`
 integrates. Work proceeds in waves (pilot chapter first), with a checkpoint commit per chapter.
 
+For an existing edition, use maintenance mode instead: resolve a fixed upstream target,
+assess the entire delta from `content/FRAMEWORK_VERSION`, map every chapter, and update only
+affected material. Run the full example corpus before advancing the framework baseline.
+Preserve historical research and record fresh evidence under `content/research/updates/<target>/`.
+Bind the actual editorial ACCEPT report to sources with `scripts/release_content.py record-review`.
+Prepare the new content edition in a PR; human review/merge is the publishing boundary.
+
 ## Project conventions
 - **Theory before syntax.** Every capability is anchored to a concept introduced first.
-- **Verify before ship.** A chapter is done only when its examples compile (or are clearly marked
-  `SKIPPED-needs-secret`) and the reviewer returns ACCEPT.
+- **Verify before ship.** A chapter is done only when its examples strictly compile with the
+  pinned target and the reviewer returns ACCEPT. Missing secrets can skip runtime execution,
+  never compilation.
 - **No secrets in code.** Engine keys live in GitHub Actions secrets; examples validate at compile time.
 - **Version-aware.** Record the inspected `gh aw` version in research/verification artifacts.
+- **Independent versions.** `content/VERSION` is the prose edition; `content/FRAMEWORK_VERSION`
+  is verified framework coverage. Metadata or tooling changes alone are not a prose release.
 - **Content ⟂ presentation.** Authors write content; `frontend-builder` owns chrome/nav/theming.
 
 ## gh-aw reference (verified)
-- Install: `gh extension install github/gh-aw` (or the `install-gh-aw.sh` script) · initialize with
-  `gh aw init` · verify with `gh aw version`.
+- Install the exact baseline/update target using `scripts/install-gh-aw.ps1` in isolation, or
+  `gh extension install github/gh-aw --pin <tag>` on a fresh runner. Confirm the actual version.
 - Workflows are markdown + YAML frontmatter in `.github/workflows/*.md`, compiled to `*.lock.yml`
-  by `gh aw compile`. Engines: Copilot, Claude, Codex, Gemini. Writes route through `safe-outputs:`.
+  by `gh aw compile`. The v0.88.7 built-ins are Copilot, Claude, Codex, Gemini, and Pi;
+  provider authentication and tool enforcement differ. Writes route through `safe-outputs:`.
 - Docs: https://github.github.com/gh-aw/
 - Repo & samples: https://github.com/github/gh-aw
   (see the `.github/aw/*.md` reference files: `cli-commands`, `safe-outputs`, `triggers`, `syntax`, …)