@event4u/agent-config 9.0.0 → 9.1.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Bootstrap shim for the event4u agent-config suite. This plugin ships ONLY the dispatcher hooks plus one install-pointer skill — ALL content (skills, rules, commands) is installed via `npx -y @event4u/agent-config init`, which writes the file projection AND registers the same hooks in ~/.claude/settings.json. DEPRECATED as a content channel; kept so the marketplace listing stays discoverable and existing installs keep working hooks.",
-    "version": "9.0.0",
+    "version": "9.1.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -48,26 +48,6 @@ foundation also land — both non-breaking by default.
 
 ### Breaking changes (6.0.0)
 
-**0. Consumer rule projection is scoped by default** (`road-to-request-scoped-rule-load` Phase 1 human gate, 2026-07-13)
-
-- **Who is affected:** fresh consumer installs — the settings template now
-  ships `projection.rule_workspaces` filled with every consumer workspace, so
-  the 16 exclusively-maintainer specification rules (plus the recorded
-  `source-of-truth.md` compat exclusion) no longer arrive: 103 → 88 rules,
-  −9,880 cl100k tokens (−13.1%) per install. All domain safety floors and
-  domain rules keep shipping; kernel rules always ship.
-- **Existing installs:** unchanged until you run `agent-config sync` /
-  re-install (settings sync preserves your current value; fill the list to
-  opt in). The first session after opting in rebuilds the KV-cache prefix
-  once (1.25–2× write cost, one session only).
-- **Quality evidence:** deterministic set-inclusion verification
-  (`src/scripts/check_consumer_scope_flip.ts` →
-  `internal/bench/reports/2026-07-13-consumer-scoped-default-flip.json`):
-  only exclusively-maintainer rules drop; zero golden-set-exercised consumer
-  rules affected (90/90 labelled tasks, coverage 86/86).
-- **Rollback:** set `projection.rule_workspaces: []` (= legacy-all).
-
-
 **1. Condensed output moved: root `.agent-src/` → `dist/agent-src/`** ([ADR-058])
 
 - **Who is affected:** consumers whose scripts or tool configs hard-code
@@ -1044,12 +1024,79 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 8.13.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [9.1.0](https://github.com/event4u-app/agent-config/compare/9.0.0...9.1.0) (2026-07-14)
+
+### Features
+
+* **create-pr:** tier-driven body, grounded API examples, capability-gated screenshots ([306f7d5](https://github.com/event4u-app/agent-config/commit/306f7d59e6e7dee4a22e9c34aad4fbc89a75e3e2))
+* **create-pr:** settings for description detail level, API examples, screenshots ([65275bb](https://github.com/event4u-app/agent-config/commit/65275bb1237fc4dfbbcefd86d27bc45ef4be257c))
+* **ai-council:** prompt caching + right-sized output on the paid Anthropic path ([3ec7ff0](https://github.com/event4u-app/agent-config/commit/3ec7ff09d49283b096901e5d4716cc529fef1609))
+* **skills:** add llm-provider-knowledge — verify LLM product facts against official docs ([ba34d94](https://github.com/event4u-app/agent-config/commit/ba34d94530d1b30066470a0316f247be84b5ac2d))
+* **commands:** register discoverable /explain-run command ([13955a1](https://github.com/event4u-app/agent-config/commit/13955a1e7ab40a658ed0879e21266fe49a54c6a0))
+* **doctor:** add rule-scope-drift check for the scoped-projection flip ([71353f8](https://github.com/event4u-app/agent-config/commit/71353f8c6bb66b404916f599c5e168bef1f85601))
+
+### Bug Fixes
+
+* **ai-council:** make prompt caching explicit opt-in (default off) ([bad8070](https://github.com/event4u-app/agent-config/commit/bad80707eda42aacbd3698575e1d22383dbea8b3))
+* **refs:** treat external claude-api plugin as non-repo reference ([75a3431](https://github.com/event4u-app/agent-config/commit/75a34314ca802e8cda39df8ff6b375c52621ae63))
+* **commands:** reference agent-docs-writing skill in /explain-run ([c104279](https://github.com/event4u-app/agent-config/commit/c104279abaaad1035758cc86140be847ed4f4a06))
+* **ci:** honest gate status in skill-lint + self-review comments ([5098465](https://github.com/event4u-app/agent-config/commit/50984659e028c8c0029b1cd1deb8a69bf1c4e61b))
+* **install:** rebuild install bundle with real node_modules paths ([f875244](https://github.com/event4u-app/agent-config/commit/f8752443b1b27bd9471dbf056a65097d898e15de))
+* **install:** rebuild install bundle + reword source-repo comment ([48e9dc2](https://github.com/event4u-app/agent-config/commit/48e9dc2a6f694610322d533b0196346cf07a151d))
+* **tests:** make wrapper-delegation install test hermetic ([8ef5ea2](https://github.com/event4u-app/agent-config/commit/8ef5ea2bdc60f90fde7979bee2dca3d15a2e118e))
+
+### Documentation
+
+* **create-pr:** document PR-description content settings ([812ae6b](https://github.com/event4u-app/agent-config/commit/812ae6ba84ba5508a71b3ab02c351cad4a3a2e55))
+* subagent prompt-cache break-even + record the follow-up council verdict ([fdba56d](https://github.com/event4u-app/agent-config/commit/fdba56dbe06818c4bc50c5b3e94322e10b34bd0d))
+* **roadmap:** API cost-optimization roadmap + dashboard ([3d1b313](https://github.com/event4u-app/agent-config/commit/3d1b3132b0d0d3a52c7eba555b1e3afd95d5750e))
+* **agent-infra:** API cost-levers guideline + token-optimizer index wiring ([a97d0e7](https://github.com/event4u-app/agent-config/commit/a97d0e7eaa4c61eb4db59f8bdf469d112595b1b5))
+* **roadmap:** archive completed road-to-llm-provider-knowledge-skill ([059aa10](https://github.com/event4u-app/agent-config/commit/059aa10b3405597986c12c0de3da6c767385bb97))
+* **roadmap:** add + archive feedback-9.0-followups roadmap ([c8aa510](https://github.com/event4u-app/agent-config/commit/c8aa5104ac774f77f1354ac9c6c3816096b769fe))
+* **changelog:** repair breaking-surface index + add sync lint ([e333d71](https://github.com/event4u-app/agent-config/commit/e333d7150254310fe569dcb6e0fad2c487568d32))
+
+### Refactoring
+
+* **install:** retire the consumer bridge marker (ADR-020 amendment) ([2737b04](https://github.com/event4u-app/agent-config/commit/2737b04441b7e807240c979e874d8e2bb3967b9b))
+
+### Build
+
+* **install:** rebuild bundle with repo-relative module paths ([f30adb5](https://github.com/event4u-app/agent-config/commit/f30adb5a109ac6aee9777bad722ef0146fc208fa))
+* **install:** rebuild install bundle after create_pr settings addition ([a760b9f](https://github.com/event4u-app/agent-config/commit/a760b9f39a41a9621b21ad2fb92851c4a1ea66b2))
+
+### Chores
+
+* **roadmaps:** archive completed pr-description-tiers roadmap ([2c4615f](https://github.com/event4u-app/agent-config/commit/2c4615fe42129eb8bd33e87a368cbed8f5f1ded7))
+* sync generated guideline count (98 -> 99) for api-cost-levers ([17ce22b](https://github.com/event4u-app/agent-config/commit/17ce22bdfc2d99341d7a3edeaaf80554f4d75f33))
+* **evals:** ratchet behavioural-eval coverage floor to current ([84f42fa](https://github.com/event4u-app/agent-config/commit/84f42fab93d77ad8b0b28ce430b79ae222748719))
+
+Tests: 7737 (+21 since 9.0.0)
+
 ## [9.0.0](https://github.com/event4u-app/agent-config/compare/8.13.0...9.0.0) (2026-07-13)
 
 ### BREAKING CHANGES
 
 * **scoping:** flip consumer rule projection default to scoped (Phase-1 human gate, approved) ([565c91a](https://github.com/event4u-app/agent-config/commit/565c91aa25e4c970d5b37258f497366f33e7a7a9))
 
+**Consumer rule projection is scoped by default** (`road-to-request-scoped-rule-load` Phase 1 human gate, 2026-07-13)
+
+- **Who is affected:** fresh consumer installs — the settings template now
+  ships `projection.rule_workspaces` filled with every consumer workspace, so
+  the 16 exclusively-maintainer specification rules (plus the recorded
+  `source-of-truth.md` compat exclusion) no longer arrive: 103 → 88 rules,
+  −9,880 cl100k tokens (−13.1%) per install. All domain safety floors and
+  domain rules keep shipping; kernel rules always ship.
+- **Existing installs:** unchanged until you run `agent-config sync` /
+  re-install (settings sync preserves your current value; fill the list to
+  opt in). The first session after opting in rebuilds the KV-cache prefix
+  once (1.25–2× write cost, one session only).
+- **Quality evidence:** deterministic set-inclusion verification
+  (`src/scripts/check_consumer_scope_flip.ts` →
+  `internal/bench/reports/2026-07-13-consumer-scoped-default-flip.json`):
+  only exclusively-maintainer rules drop; zero golden-set-exercised consumer
+  rules affected (90/90 labelled tasks, coverage 86/86).
+- **Rollback:** set `projection.rule_workspaces: []` (= legacy-all).
+
 ### Features
 
 * **product:** pre-build demand gate folded into improve-before-implement — plate complete, archived ([d6b0fcb](https://github.com/event4u-app/agent-config/commit/d6b0fcb9d020f983a98f8cd0c744d758bb758f9a))

package/MIGRATION.md

@@ -16,6 +16,20 @@ firing (now from `settings.json`), skills/commands stop listing twice, and
 `claude-plugin` no longer reporting a duplicate surface). Augment CLI and
 Copilot CLI plugins are unaffected.
 
+# Migrating to 9.0
+
+> Consumer rule projection is **scoped by default** in 9.0. Full
+> breaking-change detail: [`CHANGELOG.md` § 9.0.0](CHANGELOG.md).
+
+Fresh installs now ship `projection.rule_workspaces` pre-filled with every
+consumer workspace, so the 16 exclusively-maintainer specification rules no
+longer arrive: **103 → 88 rules** per install. All domain safety floors,
+domain rules, and kernel rules keep shipping.
+
+Existing installs are unchanged until you run `agent-config sync` /
+re-install (settings sync preserves your current value). To stay on the
+legacy every-rule behaviour, set `projection.rule_workspaces: []`.
+
 # Migrating to 6.0
 
 > Upgrading an existing install to the **6.0 experience-first** layout.

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-274-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-104-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-183-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-98-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-275-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-104-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-184-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-99-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 > **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
 
@@ -178,7 +178,7 @@ npx -y @event4u/agent-config init
 
 **Verify hook coverage:** `npx @event4u/agent-config hooks:status` prints the per-platform matrix (`--strict` for CI, `--format json` for tooling).
 
-> **Scope (v2.5+):** `init` writes **global** only — `~/.event4u/agent-config/`, `~/.claude/`, `~/.cursor/`, …. The project tree gets `agents/overrides/` + `agents/.event4u-bridge.yml`. `--project` is maintainer-only behind `AGENT_CONFIG_DEV_MODE=1` ([ADR-020](docs/decisions/ADR-020-global-only-consumer-scope.md), [dev-mode](docs/maintainers/dev-mode.md)).
+> **Scope (v2.5+):** `init` writes **global** only — `~/.event4u/agent-config/`, `~/.claude/`, `~/.cursor/`, …. The project tree gets `agents/overrides/` only (the bridge marker was retired — ADR-020 amendment 2026-07-13; the global root resolves from `~/.event4u/agent-config`). `--project` is maintainer-only behind `AGENT_CONFIG_DEV_MODE=1` ([ADR-020](docs/decisions/ADR-020-global-only-consumer-scope.md), [dev-mode](docs/maintainers/dev-mode.md)).
 
 Migrating from a v1.x install? `npx @event4u/agent-config migrate` — full notes in [`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md).
 

package/dist/agent-src/commands/explain-run.md

@@ -0,0 +1,88 @@
+---
+model_tier: inherit
+name: explain-run
+pack: meta
+tier: 2
+visibility: internal
+description: "Read-only 'why did that happen' run report — resolved rule set, rules fired, artefact engagement, subagent dispatches, hook/loop/freshness state — even when the user just says 'explain the last run'."
+argument-hint: "[--task <id>] [--since <ref>]"
+skills: [agent-docs-writing]
+suggestion:
+  eligible: false
+  rationale: "Package-internal maintainer diagnostic — only the event4u/agent-config repo runs this."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# explain-run
+
+Thin runner for the read-only explainability engine `explain_run`
+(`src/scripts/explain_run.ts`). Renders one Markdown
+report answering **"why did the agent do that this run?"** entirely from
+artefacts other parts of the suite already write — no new state, no capture,
+no daemon.
+
+The report covers: the resolved rule set (kernel vs trigger-routed, from
+`dist/router.json`), rules the audit log actually observed firing, artefact
+engagement (consulted vs applied), subagent dispatches (mode / tiers / token
+deltas), a hook / loop / freshness state snapshot, and a parked list of
+"why" questions this v0 cannot answer yet (surfaced, never silently omitted).
+
+## Instructions
+
+### 1. Resolve the window
+
+Both arguments are optional and narrow the report:
+
+- `--task <id>` — restrict to one task id seen in the audit log.
+- `--since <ref>` — an ISO-8601 timestamp / date cutoff (e.g. `2026-07-01`).
+
+With neither, the engine reports over all available artefacts. Pass through
+exactly what the user gave — do not invent a task id or a date.
+
+### 2. Run the engine
+
+```bash
+./scripts-run src/scripts/explain_run [--task <id>] [--since <ISO-8601>]
+```
+
+Exit codes:
+
+- `0` → report rendered to stdout; continue to step 3.
+- `2` → bad argument (unknown flag or unparsable `--since`); surface stderr
+  and stop.
+
+The engine prints an honest `no data — <source> absent or empty` for any
+section whose source file is missing — that is expected output, not an error.
+
+### 3. Surface the report
+
+Show the engine's Markdown output. Do not re-summarize or re-order it — the
+report already opens with a plain-language `## Summary`. If the user wants the
+report written to a file, add `--output <path>` and confirm the write.
+
+## Rules
+
+- **Read-only** — this command only reads on-disk artefacts. It never edits,
+  captures, or writes state (aside from an explicit `--output` file).
+- **Do NOT commit or push** — the working tree is left to the user.
+- **Never edit generated trees** — per [`source-of-truth`](../rules/source-of-truth.md),
+  the engine lives in `src/scripts/`; never hand-edit `dist/agent-src/` or any
+  tool projection.
+- **Honest nulls, not invented rows** — the engine's `no data` lines are
+  correct output; do not fabricate rule firings or dispatches to fill them.
+
+## When NOT to use
+
+- To *change* behaviour — this only explains it. Rule / routing edits go
+  through the normal source-of-truth flow.
+- Kill criterion: the engine self-documents a delete-if-unused-after-3-releases
+  criterion; if this command sees zero use, retire it with the engine.
+
+## See also
+
+- `explain_run` (`src/scripts/explain_run.ts`) — the read-only engine this wraps.
+- `/agent-status` — live session snapshot (this is the retrospective, artefact-sourced view).
+- [`source-of-truth`](../rules/source-of-truth.md) — edit `src/`, never generated trees.

package/dist/agent-src/commands/pr/create/description-only.md

@@ -95,34 +95,164 @@ That's 6 round-trips for what should be 2.
 
 ### 4. Build the PR body
 
+#### 4.0 Resolve the detail level
+
+Read `commands.create_pr.detail_level` from `.agent-settings.yml` (default
+`min` when unset). This tier governs **only the explanatory depth of the
+Description section** — never which template sections exist, and never
+whether a critical callout appears (see 4.1 critical-info-always).
+
+| Tier | Description section content |
+|---|---|
+| `min` (default) | Title-level summary in 2-3 sentences: *what* changed, *why*, and the user/system impact. No per-file walk, no restating commit subjects, no "how to test". |
+| `med` | `min` + grouped logical changes as 3-5 bullets (by concern, not by file) + a one-line tests note (added / none / coverage). |
+| `max` | `med` + how-to-test steps + edge cases / trade-offs + one "reviewer guidance" line (what to focus on). ≈ the legacy output. |
+
+`min` is the default because this is a token-cost optimization: a shorter
+description costs fewer output tokens on every PR. Keep `min` genuinely
+minimal — but never at the expense of the critical-info block below.
+
+#### 4.1 Critical-info-always — tier-independent MUST
+
+```
+CRITICAL INFORMATION APPEARS AT EVERY TIER, INCLUDING min.
+THE TIER GOVERNS EXPLANATORY DEPTH, NEVER WHETHER A CRITICAL CALLOUT APPEARS.
+DROPPING A BREAKING-CHANGE / MIGRATION / SECURITY / ROLLBACK CALLOUT AT min
+IS A P0 DEFECT, NOT A TOKEN SAVING.
+```
+
+If the diff shows any of the following, a one-line callout for it is included
+in the Description **regardless of `detail_level`** (grounded in the diff, not
+guessed):
+
+- **Breaking change** — API contract change (new/removed/renamed field, changed
+  endpoint or response shape), CLI-arg change, changed env var, or a renamed
+  route the frontend depends on. Prefix `⚠️ Breaking:`.
+- **Migration required** — DB migration, config migration, or a deployment step.
+  Prefix `Migration:`.
+- **Security implication** — new permission/scope, auth change, or data-exposure
+  surface. Prefix `🔒 Security:`.
+- **Non-trivial rollback** — when reverting is not a plain `git revert`. Prefix
+  `Rollback:`.
+
+None present → omit the block entirely (do not emit empty "No breaking
+changes" filler at `min`).
+
+#### 4.2 Fill the template sections
+
 **ALWAYS** use the PR template (`.github/pull_request_template.md`). Fill in its sections:
 
 - **Jira badge**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Description**: Summarize the changes in 2-5 sentences. Explain *what* changed and *why*.
-  Use the Jira ticket description and commit messages as input.
+- **Description**: Write it to the resolved tier (4.0) with the critical-info
+  block (4.1) always present. Use the Jira ticket description + commit messages
+  as input.
 - **Type of change**: Check the appropriate checkbox(es) based on the changes.
 - **Checklist**: Leave as-is (the developer fills this in).
 - **Links**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Screenshots**: Leave as `...` unless the user provides screenshots.
+- **Screenshots**: Handled by Step 4.4 (default: leave the placeholder / `...`).
 
-If no PR template exists, use this structure:
+If no PR template exists, use this structure — including only the sections the
+tier calls for (at `min`, the `## Changes` bullets collapse to the 2-3 sentence
+summary and `## How to test` is omitted):
 
 ```markdown
 ## Jira
 [{TICKET-ID}]({JIRA_BASE_URL}/browse/{TICKET-ID})
 
-## Changes
-- Bullet list of what was changed and why
+## Description
+- 2-3 sentence what/why/impact (min) — grouped bullets (med/max)
+- Critical-info callouts (any tier, only if present)
 
 ### Migrations
 - List new/changed migrations (if any)
 
 ### Tests
-- List new/changed tests (if any)
+- List new/changed tests (med/max)
 
 ## How to test
-- Steps to verify the changes
+- Steps to verify the changes (max)
+```
+
+#### 4.3 API response examples (evidence-grounded)
+
+Read `commands.create_pr.api_examples` (default `true`). When `true` **and**
+the diff touches an API endpoint, add a fenced request/response example under
+the Description.
+
+**Detect an API-endpoint change** (fail-open — no false enrichment when
+ambiguous): a changed file matches `commands.create_pr.api_paths` (if set), or
+the light heuristic — a route file (`routes/`, `**/api/**`, `*Controller*`,
+resource/serializer classes) whose diff adds or changes an endpoint or its
+request/response shape. No confident match → skip silently.
+
+**Ground the example in a real source — never invent one:**
+
+```
+NEVER FABRICATE A JSON EXAMPLE. AN INVENTED CONTRACT MISLEADS REVIEWERS
+AND IS WORSE THAN NONE. EMIT A JSON BLOCK ONLY FROM A REAL SOURCE.
+```
+
+Grounding sources, in priority order: the response DTO / API-resource /
+serializer class in the diff · an OpenAPI/JSON-schema in the repo · a test
+fixture or assertion exercising the endpoint · the actual output of a probe you
+ran this session (`curl` / test client). If **none** exists, emit a one-line
+pointer instead — `API contract changed — see \`<file>\`` — never a guessed
+example. This is [`senior-engineering-discipline`](../rules/senior-engineering-discipline.md)
+(never invent an API) applied to the description surface.
+
+Format when grounded:
+
+~~~markdown
+### API example (`POST /api/...`)
+Request:
+```json
+{ ...grounded... }
+```
+Response `201`:
+```json
+{ ...grounded... }
 ```
+~~~
+
+`api_examples: false` → skip this step entirely.
+
+#### 4.4 Screenshots for frontend changes (capability-gated)
+
+Read `commands.create_pr.screenshots` (default `false`). `false` → skip this
+step entirely; leave the template Screenshots placeholder as-is.
+
+When `true`, this is a **capability-gated contract, never a runtime
+orchestrator** — the package ships instructions, the host provides the tools:
+
+1. **Frontend-change gate.** Only proceed if the diff touches a frontend
+   surface — a changed file matches `commands.create_pr.ui_paths` (if set), or
+   the light heuristic (`.vue` / `.tsx` / `.jsx` / `.blade.php` / `.svelte`,
+   component/view/page/template dirs, CSS/Tailwind). No match → skip silently.
+2. **Capability gate — explicit, never silent.** Screenshots need host
+   browser/preview tooling (a Playwright/browser MCP **and** a reachable dev-server
+   or preview URL). There is no capability flag to read, so probe cheaply. If the
+   tooling or a running preview is **absent**:
+   - Leave the template Screenshots placeholder untouched, **and**
+   - Emit ONE line in the chat reply: `Screenshots requested (screenshots: true)
+     but no browser/preview tooling was reachable — skipped.`
+   - **Never** fail, block, or delay PR creation over this.
+3. **Capture (when capable).** Capture the current (head) state of each changed
+   surface. Before/after (base vs head) with changed-region highlighting is
+   **best-effort only** — a base checkout mid-PR is fragile and expensive;
+   attempt it only if cheap and safe, otherwise after-only. One screenshot per
+   changed surface, each with a one-line caption.
+4. **Embedding — honest limits.** The `github-api pulls` write path cannot
+   upload image bytes and GitHub markdown does not render `data:` URIs, so an
+   agent cannot inline captured bytes into the body via the API. Use, in order:
+   (a) a host image-upload capability if one exists (embed the returned URL);
+   (b) otherwise save the screenshots to a local path, reference them in the
+   Screenshots section, and tell the user to drag them into the PR in the
+   GitHub UI. **Never claim an embed that did not happen**
+   ([`direct-answers`](../rules/direct-answers.md) Iron Law 2).
+
+Limitations (state them so expectations are set): default off; depends on host
+browser tooling + a running preview; before/after + highlighting is best-effort;
+byte-embedding into the PR body is not possible via the API.
 
 ### 5. Present as copyable block
 

package/dist/agent-src/commands/pr/create.md

@@ -140,6 +140,12 @@ completion is read from the checkbox counts.
 Run `/create-pr:description-only` Steps 1–4 to generate the PR title and body.
 This handles: Jira ticket extraction, diff analysis, commit messages, **PR template filling**.
 
+The generation honors the cached content flags from step 1 (§4e):
+`detail_level` sets the Description tier (default `min`), `api_examples`
+adds a grounded JSON block for API-endpoint changes, and `screenshots`
+(capability-gated) adds frontend screenshots. Critical-info callouts
+(breaking changes / migrations / security / rollback) appear at every tier.
+
 **CRITICAL**: The PR body MUST use the project's PR template (`.github/pull_request_template.md`).
 Read the template file and fill in its sections. If the template does not exist, use the
 fallback structure defined in `/create-pr:description-only`. NEVER invent a custom body structure.
@@ -316,11 +322,16 @@ an actual Jira API call succeeded** — never announce "skipped".
 
 #### 4e. Settings short-circuit — single read per run
 
-`verbosity.routine_confirmations`, `verbosity.post_action_reports`, and
-`commands.create_pr.preview_description` are read **once** at the top
-of the run and cached for the whole `/create-pr` invocation. Do **not**
-re-read `.agent-settings.yml` in 4b / 4d — both branches resolve from
-the cached values from step 1.
+`verbosity.routine_confirmations`, `verbosity.post_action_reports`,
+`commands.create_pr.preview_description`, `commands.create_pr.detail_level`,
+`commands.create_pr.api_examples`, `commands.create_pr.screenshots`,
+`commands.create_pr.ui_paths`, and `commands.create_pr.api_paths` are read
+**once** at the top of the run and cached for the whole `/create-pr`
+invocation. Do **not** re-read `.agent-settings.yml` in Step 2 or 4b / 4d —
+every branch resolves from the cached values from step 1. The content flags
+(`detail_level`, `api_examples`, `screenshots`, `ui_paths`, `api_paths`) are
+consumed by the `/create-pr:description-only` generation step (Step 2); the
+confirmation/report flags by steps 3–4.
 
 When all three resolve to their silent defaults (`false` / `minimal` /
 `false`), steps 4b + 4d collapse to the single `→ #N opened: <url>` line

package/dist/agent-src/skills/llm-provider-knowledge/SKILL.md

@@ -0,0 +1,146 @@
+---
+model_tier: inherit
+name: llm-provider-knowledge
+description: "Before stating any specific fact about an LLM provider's product — models, pricing, limits, context windows, SDK/API — for OpenAI, Gemini, Claude & others, verify against official docs, not memory."
+source: package
+domain: process
+personas: []
+workspaces:
+  - agent-config-maintainer
+  - engineering
+  - product
+  - founder
+  - small-business
+  - gtm
+  - ops
+packs:
+  - meta
+trust:
+  level: experimental
+install:
+  removable: true
+execution:
+  type: manual
+---
+
+# llm-provider-knowledge
+
+Verify LLM-provider product facts against **official documentation**, never
+memory. This skill is the multi-provider sibling of Claude Code's bundled
+`product-self-knowledge` — extended to OpenAI, Google Gemini, Anthropic,
+Mistral, xAI, DeepSeek, Cohere, and Meta Llama, and portable to every host this
+package projects to (not just Claude Code).
+
+**This skill is a signpost, not a library.** It routes you to the authoritative
+source and forces a source-cited answer. It does **not** cache model IDs,
+context windows, prices, or rate limits — those churn constantly, and a cached
+copy is exactly the stale "from memory" answer this skill exists to prevent.
+
+## When to use
+
+- Your reply would state a specific fact about a provider's product: a model ID
+  or its context window, token pricing, a rate/quota limit, an SDK/API detail
+  (endpoint, parameter, auth, batch, streaming, function-calling shape), or a
+  consumer-app plan limit (ChatGPT/Gemini/Claude app tiers).
+- Coding against a provider SDK where a wrong model name, parameter, or limit
+  would break at runtime.
+- Content or comparisons that assert provider capabilities or pricing.
+- Any time you would otherwise answer such a fact from training data — it may be
+  outdated or wrong.
+
+## When NOT to fire
+
+- Ordinary SDK code that asserts **no** product fact (wiring a call whose model
+  and params the user already gave).
+- The user already supplied the verified fact — use it; don't re-litigate.
+- Writing provider-specific prompt grammar → `prompt-engineering-patterns`.
+- Choosing which model to use for the host → `model-recommendation` (never
+  recommend another vendor's model over the host's; this skill only reports
+  facts, it does not steer model choice).
+- Image-provider selection → `image-provider-routing`.
+
+## Core principles
+
+1. **Accuracy over guessing** — if unsure, route to the docs; never assert.
+2. **Distinguish products** — a provider's API, its developer platform, and its
+   consumer app are separate surfaces with separate facts and separate docs.
+3. **Source everything** — every product fact in the reply carries an official
+   URL. No URL → not verified → don't state it as fact.
+4. **Route, don't cache** — hand off to the live docs; do not transcribe
+   volatile specs into the reply as if durable.
+
+## Provider routing table
+
+Route to the **stable root** and read live from there — do not deep-link to
+pages that churn. Prefer a provider's machine-readable index where one exists.
+
+| Provider | Docs root | API reference | Product / support |
+|---|---|---|---|
+| **OpenAI** (GPT) | `platform.openai.com/docs` | `platform.openai.com/docs/api-reference` | `help.openai.com` |
+| **Google Gemini** | `ai.google.dev/gemini-api/docs` | `ai.google.dev/api` | `support.google.com` (Gemini app) |
+| **Anthropic** (Claude) | `docs.claude.com/en/docs` (index: `/en/docs_site_map.md`) | `docs.claude.com/en/api/overview` | `support.claude.com` |
+| **Mistral** | `docs.mistral.ai` | `docs.mistral.ai/api` | `help.mistral.ai` |
+| **xAI** (Grok) | `docs.x.ai` | `docs.x.ai/developers` | `x.ai` |
+| **DeepSeek** | `api-docs.deepseek.com` | `api-docs.deepseek.com/api` | `platform.deepseek.com` |
+| **Cohere** | `docs.cohere.com` (index: `docs.cohere.com/llms.txt`) | `docs.cohere.com/reference` | `dashboard.cohere.com` |
+| **Meta Llama** | `llama.com` (dev docs: `ai.developer.meta.com/docs`) | `ai.developer.meta.com/docs` | `llama.com` |
+
+**Claude Code specifics** (install, Node.js requirement, MCP, config):
+`docs.anthropic.com/en/docs/claude-code/claude_code_docs_map.md`.
+
+**Hosted access** (not a distinct vendor): Azure OpenAI, AWS Bedrock, and
+Google Vertex AI resell the underlying vendor's models. Route to BOTH the
+underlying vendor's row above AND the cloud's own docs (`learn.microsoft.com`,
+`docs.aws.amazon.com/bedrock`, `cloud.google.com/vertex-ai`) — model IDs,
+quotas, and regions differ from the vendor's direct API.
+
+## Procedure
+
+1. **Identify the provider and the surface** — API / developer platform /
+   consumer app. A ChatGPT-Plus limit is not an OpenAI-API rate limit.
+2. **Pick the row + column** from the table; go to the stable root.
+3. **Read the live docs** for the exact fact (navigate from the root; follow
+   the provider's own index / `llms.txt` where present).
+4. **State the fact with its source URL.** If the docs can't be reached or are
+   ambiguous, say so and point the user at the root rather than guessing.
+5. **Never transcribe a volatile spec as durable** — frame it as "per <URL> as
+   of now"; the source is authoritative, the reply is a pointer.
+
+## Output format
+
+Every reply that states a provider product fact MUST include:
+
+1. **The fact, scoped to the product surface** — name the provider AND which
+   surface (API / platform / consumer app) it applies to.
+2. **The official source URL** — the specific docs page the fact came from (or
+   the stable root when you're directing the user to read it themselves).
+3. **A freshness caveat when the fact is volatile** (pricing, limits, model
+   availability): "verify at <URL> — these change without notice."
+
+## Do NOT
+
+- **Do NOT** state a model ID, context window, price, or rate limit from
+  memory — route to the docs and cite the URL, or say you're unsure.
+- **Do NOT** transcribe a volatile spec (pricing, limits, model availability)
+  into the reply as if durable — frame it as "per <URL> as of now".
+- **Do NOT** conflate a provider's API with its consumer app — they carry
+  different limits and different docs.
+- **Do NOT** steer the user to another vendor's model over the host's — that is
+  `model-recommendation`; this skill reports facts neutrally.
+- **Do NOT** cache a provider's docs into this skill. When a root URL moves,
+  fix the one table row; a mismatch a user reports is a signal to correct the
+  row, never to start transcribing pages here.
+
+## Gotcha
+
+- **Provider docs URLs churn** (Meta's Llama dev-docs host redirected during
+  this skill's authoring). That is *why* the skill links to stable roots and
+  reads live — a deep-linked page memorised here would rot. If a root itself
+  moves, fix the one table row; never start caching pages to compensate.
+- **Do not conflate surfaces.** "Gemini" the app and the Gemini API have
+  different limits and different docs; the same for ChatGPT vs the OpenAI API
+  and Claude.ai vs the Claude API.
+- **Redundant with the harness on Claude Code.** Claude Code's own
+  `product-self-knowledge` also fires for Anthropic facts — both route to the
+  same Anthropic docs, so the overlap is harmless. On every other host this is
+  the only such skill.

package/dist/agent-src/skills/llm-provider-knowledge/evals/triggers.json

@@ -0,0 +1,20 @@
+{
+  "skill": "llm-provider-knowledge",
+  "last_eval": "2026-07-14",
+  "description": "7 should-trigger + 6 should-not-trigger. Should-trigger covers specific product-fact claims (context window, pricing, rate limit, API detail, model spec, consumer-app plan limit) across OpenAI, Google, Anthropic, Mistral, DeepSeek, Cohere. Should-not-trigger covers near-misses: SDK wiring with a user-supplied model, prompt authoring (prompt-engineering-patterns), model choice for the host (model-recommendation), image-provider selection (image-provider-routing), a user-supplied fact, and a plain SDK refactor.",
+  "queries": [
+    {"q": "what's the context window of GPT-5?", "trigger": true},
+    {"q": "how much does Gemini 2.5 Pro cost per million input tokens?", "trigger": true},
+    {"q": "what are the rate limits on the Anthropic API for tier 1?", "trigger": true},
+    {"q": "does the Mistral API support function calling, and what parameter enables it?", "trigger": true},
+    {"q": "what's the max output length for DeepSeek's chat model?", "trigger": true},
+    {"q": "how many messages does ChatGPT Plus allow in the app per window?", "trigger": true},
+    {"q": "what embedding dimension does Cohere's embed model return?", "trigger": true},
+    {"q": "wire up an openai chat completions call using the model id I already gave you", "trigger": false, "note": "SDK wiring; user supplied the model — no unverified product fact asserted"},
+    {"q": "write a good prompt to make Gemini summarize this document", "trigger": false, "note": "prompt authoring → prompt-engineering-patterns"},
+    {"q": "which model should I use for this task on my current host?", "trigger": false, "note": "model choice → model-recommendation (never steer to another vendor)"},
+    {"q": "route this logo-with-text image to the right generation provider", "trigger": false, "note": "image-provider selection → image-provider-routing"},
+    {"q": "I already know Claude Sonnet has a 200k context window — just use that number", "trigger": false, "note": "user supplied the verified fact; use it, do not re-litigate"},
+    {"q": "refactor this function that calls the Anthropic SDK to add retries", "trigger": false, "note": "plain code refactor; asserts no product fact"}
+  ]
+}

package/dist/agent-src/skills/subagent-orchestration/prompts/README.md

@@ -33,6 +33,17 @@ hits (Anthropic `cache_control: ephemeral`) across the cohort — the prefix is
 cached after the first sibling and served from cache for the rest, cutting
 input-token cost proportionally to cohort size.
 
+**Break-even + failure modes.** A cache write costs ~1.25× the base input rate
+(5-min TTL); a read costs ~0.1×. So the prefix pays off once **≥ 2** siblings
+read it — a lone subagent with no sibling reuse only pays the write premium and
+saves nothing. The cache is a **byte-exact prefix match**: any drift in the
+shared prefix (a timestamp, a per-sibling id, reordered text) forces a re-write
+instead of a read, and the prefix must be re-hit within the **5-minute TTL**, so
+dispatch siblings promptly rather than trickling them. This is why the win is
+real for **fan-out** (many siblings, one prefix) and marginal for one-shot
+dispatch. Verify a cohort is actually reading, not re-writing, by checking
+`usage.cache_read_input_tokens > 0` on the 2nd+ sibling.
+
 ## Loading
 
 `tests/test_subagent_prompt_loading.py` asserts that every mode named