@open-agent-toolkit/cli 0.2.30 → 0.2.31

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.30"
+  "oatVersion": "0.2.31"
 }

package/assets/docs/cli-utilities/configuration.md

@@ -138,6 +138,7 @@ plumbing uses `explainers.*`; project lifecycle preferences use
 | `explainers.publish.publicBaseUrl`     | HTTPS URL                    | shared              | unset           |
 | `explainers.publish.awsRegion`         | non-empty string             | shared              | unset           |
 | `explainers.publish.awsProfile`        | non-empty string             | local, user         | unset           |
+| `explainers.publish.publicAccess`      | `public\|protected`          | shared              | `public`        |
 | `workflow.explainers.projectExplainer` | `always\|ask\|never`         | local, shared, user | `ask`           |
 | `workflow.explainers.projectRecap`     | `always\|ask\|never`         | local, shared, user | `ask`           |
 
@@ -172,6 +173,46 @@ chain applies. Config never starts publishing by itself: lifecycle callers must
 still select publish durability explicitly, and publishing remains
 human-gated. Raw AWS credentials are not config keys.
 
+`publicAccess` declares whether published objects are expected to be reachable
+anonymously; it does not authorize publication and it does not change any
+bucket policy. It selects how publication is verified. The default `public`
+fetches every uploaded object over HTTPS and compares the returned bytes
+against the manifest hash. `protected` skips those anonymous fetches, verifies
+each object through authenticated S3 hashing instead, and records
+`skipped-protected` in the publish receipt. Because no anonymous fetch happens
+under `protected`, a mistyped `publicBaseUrl` is not detected at publish time:
+the advertised URLs are still written into the initiative catalog and receipt,
+and the catalog records `publicVerification: "skipped-by-policy"` so consumers
+can see the URLs were never exercised.
+
+### Explainer publication environment variables
+
+Two escape hatches are read from the process environment rather than from
+config, because both are machine-local operational overrides rather than
+project settings. Neither has a config key.
+
+| Variable                                         | Effect                                                                      | Default |
+| ------------------------------------------------ | --------------------------------------------------------------------------- | ------- |
+| `EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT`        | Permits a loopback, link-local, unique-local or RFC 1918 `publicBaseUrl`    | off     |
+| `EXPLAINER_KIT_SUPPRESS_ROOT_DIVERGENCE_WARNING` | Silences the advisory warning when the S3 key prefix and public path differ | off     |
+
+Both accept `1`, `true` or `on`.
+
+`EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT` disables an anti-SSRF control. Public
+verification issues an outbound GET against whatever `publicBaseUrl` names, so
+by default the connector refuses internal addresses — including the
+`169.254.169.254` instance-metadata endpoint. Enable it only for a genuinely
+internal mirror. When it is set and the root is in fact non-public, the run
+records `publicRootPolicy: "private-allowed"` in the publish receipt, so a
+publication made with the control disabled is distinguishable in durable
+evidence from one made without it. The policy is address-literal only: a
+hostname that resolves inward is not detected either way.
+
+`EXPLAINER_KIT_SUPPRESS_ROOT_DIVERGENCE_WARNING` only affects an advisory
+message. Divergent roots are never a publication failure — a CloudFront Origin
+Path deployment legitimately maps a bucket prefix to the distribution root — so
+this changes no validation outcome.
+
 See [Explainer Kit](../workflows/skills/explainer-kit.md) for recipes, artifact
 locations, lifecycle behavior, and durability.
 

package/assets/docs/contributing/code.md

@@ -41,18 +41,30 @@ OAT is organized as a pnpm workspace with Turborepo orchestration.
 
 ## Quality Gates
 
-Run the workspace checks that match your change surface:
+Every change runs the ordered Definition of Done from the root `AGENTS.md`,
+which mirrors CI's gate steps exactly so a locally green run implies CI green:
 
 ```bash
-pnpm test
-pnpm lint
-pnpm format
+pnpm check
 pnpm type-check
-pnpm build          # excludes docs for speed
-pnpm build:docs     # builds docs site and its dependencies
+pnpm test
+pnpm build                    # excludes docs for speed
+pnpm run check:skill-bumps    # changed .agents/skills/*/SKILL.md must bump version
+pnpm release:check-versions   # lockstep public package version bumps
+pnpm release:validate
+pnpm build:docs               # builds docs site and its dependencies
 ```
 
-For narrower changes, use package-specific checks when possible, but do not merge without passing the relevant workspace gates.
+`pnpm test` is composite: it runs the workspace vitest suites, then
+`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), and
+the named-file `test:release` set. Steps 5 and 6 are the version-lockstep
+gates; they are in the local list because they previously ran only in CI and
+version-bump drift twice reached review with no local gate to surface it.
+
+CI runs neither `pnpm lint` nor `pnpm format` — run both whenever a change
+touches `tools/smoke` or `.agents/skills`, since nothing else covers them.
+For narrower changes, use package-specific checks when possible, but do not
+merge without passing the relevant workspace gates.
 
 ### TypeScript and type-aware linting
 

package/assets/docs/contributing/explainer-kit-verification.md

@@ -62,6 +62,11 @@ The suite recomputes semantic-input hashes, grounds every claim in retained
 source evidence, and evaluates the shared rubric against live runtime output.
 A prose claim or status label without runtime proof does not pass.
 
+The existing three-case, 27-capture golden suite is intentionally unchanged by
+the prose-led visual-review work. Simplifying it is a separate follow-up: first
+audit each case's unique coverage, runtime cost, and flakiness, then remove or
+replace fixtures only with evidence that the same behavior remains protected.
+
 ## Inspect generated evidence
 
 The suite materializes each case's runtime package under its temporary working
@@ -114,9 +119,12 @@ pnpm check
 pnpm type-check
 pnpm test
 pnpm build
+pnpm run check:skill-bumps
+pnpm release:check-versions
+pnpm release:validate
+pnpm build:docs
 pnpm lint
 pnpm format
-pnpm build:docs
 git diff --check
 ```
 

package/assets/docs/contributing/skills.md

@@ -43,6 +43,15 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - `allowed-tools`
 - `oat_gateable`
 
+### The `version` field is gated
+
+Changing any canonical skill's `SKILL.md` requires bumping its frontmatter
+`version` in the same PR — one bump per changed skill in the final PR diff,
+even if the skill was edited multiple times on the branch. The rule is
+enforced by `pnpm run check:skill-bumps`, which runs locally (root `AGENTS.md`
+Definition of Done) and in CI; a changed skill whose version matches
+`origin/main` fails the gate.
+
 ## Practical Authoring Flow
 
 1. Decide whether you are adding a general reusable skill or an OAT-specific lifecycle skill.

package/assets/docs/workflows/skills/explainer-kit-providers.md

@@ -38,9 +38,11 @@ The provider-neutral `planSet` callback runs once after fact reconciliation and
 before any author callback. It returns the complete portfolio and one shared
 claim ledger.
 
-For a project recap, the portfolio must contain the required hub, architecture
-view, and deck. Optional entries must use a recipe-licensed profile, remain
-inside recipe and per-profile limits, and carry source-backed justification.
+For a new project recap, the portfolio must contain the required navigational
+hub. A diagram, deck, or deep dive is optional and must use a recipe-licensed
+profile, remain inside recipe and per-profile limits, and answer a distinct
+reader question with source evidence and a medium rationale. Version 1 recap
+plans remain readable for replay with their historical three-artifact floor.
 Duplicate identities, undeclared sources, conflicting shared terms, and
 unjustified optionals fail validation.
 
@@ -50,14 +52,16 @@ artifact. Authors cannot add, remove, replace, or rename portfolio entries.
 ## Artifact author
 
 The core invokes `author` once per planned artifact with
-`explainer-kit.author-request/v2`. The request contains:
+`explainer-kit.author-request/v3`. Version 2 requests remain readable for
+replay. The current request contains:
 
 - artifact identity, type, and authoring path;
 - the versioned brief and bundled medium-specific guidance;
 - reconciled facts and the shared set context;
 - the matching planned artifact;
 - the resolved theme; and
-- the bundled shell for artistic HTML.
+- the bundled shell for artistic HTML; and
+- canonical artifact links ending in explicit `index.html` paths.
 
 Return `explainer-kit.author-result/v2` with exactly one of
 `content.markdown` or `content.html` and non-secret provenance. The core
@@ -128,6 +132,13 @@ all reviewed artifact IDs, structured findings, and one disposition:
 - `correct` requests one bounded correction and one final review; or
 - `fail` terminates the gate.
 
+Judge typography, hierarchy, composition, density, medium leverage, template
+repetition, diagram semantics, and cross-artifact cohesion from the bound
+browser evidence. `pass` means no required correction remains. `correct`
+findings name concrete artifact-scoped actions that can be completed in the
+single bounded correction round. Keep this judgment in prose; do not invent
+numeric scores or geometry thresholds.
+
 The critic must not mutate rendered files or evidence. The core revalidates all
 bound bytes after each callback.
 

package/assets/docs/workflows/skills/explainer-kit.md

@@ -20,19 +20,19 @@ OAT lifecycle callers use the adapter.
 
 ## Recipes
 
-The core ships four versioned recipes on the `explainer-kit.recipe/v2` file
-schema. Each recipe's own `version` selector remains `"1"`, so `{id, version}`
-callers and manifest cross-checks are unaffected by the schema move.
+The core ships four recipe families on the `explainer-kit.recipe/v2` file
+schema. Most recipe selectors remain at version `"1"`. New project recaps use
+immutable `project-recap@2`, while `project-recap@1` remains readable for replay.
 
 A v2 recipe declares a **floor** — the artifacts every run must produce — plus
 a licensed **expansion** set. Most recipes retain one floor artifact.
-Unattended `project-recap` is the exception: it plans and composes an adaptive
-minimum set before any artifact author runs.
+`project-recap@2` requires one complete navigational hub and plans any additional
+artifact before an author runs.
 
 | Recipe              | Use                                                    | Required floor                                                                                                    |
 | ------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
 | `project-explainer` | Working explanation after project planning             | one Markdown `hub` covering architecture, decisions, risks, phases, and validation                                |
-| `project-recap`     | Final record after implementation and final review     | HTML visual hub, architecture/system diagram, and deck governed by one set plan                                   |
+| `project-recap`     | Final record after implementation and final review     | one HTML navigational hub; diagrams, decks, and deep dives are adaptive expansions                                |
 | `program-recap`     | Bird's-eye record of a multi-wave delivery program     | one Markdown `hub` covering the wave map, outcomes, convention evolution, aggregate numbers, and follow-up ledger |
 | `engineer-tour`     | Engineer-facing orientation to a codebase and its flow | one HTML-composed `explainer` covering orientation, architecture, execution flow, key code, and validation        |
 
@@ -46,8 +46,8 @@ adding an OAT dependency.
 ### Project recap modes
 
 Project recaps default to `recapMode: artistic`. This mode uses the shared set
-plan and provider-neutral author seam to compose the required HTML hub,
-architecture view, and deck.
+plan and provider-neutral author seam to compose the required HTML hub plus any
+source-backed expansion that answers a distinct reader question.
 
 `recapMode: deterministic-markdown` is an explicit fallback for callers that
 need deterministic output. It preserves the same planned artifact portfolio and
@@ -63,16 +63,16 @@ artifact `type`, authoring path, brief, optional shell, and a mandatory
 `maxCount`. Every recipe also carries a mandatory `expansion.limits.maxArtifacts`
 that caps the whole expansion set; floor artifacts do not count against it.
 
-| Recipe              | Profiles (max per profile)                       | `maxArtifacts` |
-| ------------------- | ------------------------------------------------ | -------------- |
-| `project-recap`     | `status-view` 1, `rollout-view` 1, `deep-dive` 3 | 5              |
-| `program-recap`     | `supporting-diagram` 3, `project-page` 12        | 12             |
-| `project-explainer` | `supporting-diagram` 4                           | 4              |
-| `engineer-tour`     | `supporting-diagram` 4                           | 4              |
+| Recipe              | Profiles (max per profile)                                  | `maxArtifacts` |
+| ------------------- | ----------------------------------------------------------- | -------------- |
+| `project-recap@2`   | `supporting-diagram` 1, `walkthrough-deck` 1, `deep-dive` 3 | 5              |
+| `program-recap`     | `supporting-diagram` 3, `project-page` 12                   | 12             |
+| `project-explainer` | `supporting-diagram` 4                                      | 4              |
+| `engineer-tour`     | `supporting-diagram` 4                                      | 4              |
 
-For project recaps, optional status and rollout views require matching
-source-backed justifications, while `deep-dive` remains a Markdown
-`explainer`. Other recipes retain their recipe-owned diagram and project-page
+For project recaps, every optional diagram, deck, or deep dive needs a distinct
+reader question, supporting source evidence, and rationale for choosing that
+medium. Other recipes retain their recipe-owned diagram and project-page
 profiles. Every declared type stays inside the frozen `manifest/v1` enum.
 
 ## Content authoring and review
@@ -116,6 +116,11 @@ author request, so an unattended author receives everything it needs in one
 payload. Changing a brief changes output expectations with no contract
 migration.
 
+The bundled authoring prose covers typographic roles, hierarchy, composition,
+density, medium leverage, template repetition, diagram semantics, and
+cross-artifact cohesion. These remain editorial judgments rather than numeric
+scores or deterministic layout checks.
+
 ### The planning and author seams
 
 Before authoring, one provider-neutral `planSet` callback produces the complete
@@ -125,15 +130,17 @@ portfolio. Every run also requires one provider-neutral author callback, in
 without one fails with `E_AUTHOR_REQUIRED`.
 
 The core invokes the author once per planned artifact with an
-`explainer-kit.author-request/v2` payload carrying the artifact identity and
+`explainer-kit.author-request/v3` payload carrying the artifact identity and
 type, its authoring path, the inlined brief, the reconciled fact base, the
 resolved theme, the shell source for artistic artifacts, the immutable set
-context, the matching planned artifact, and bundled medium-specific authoring
-guidance. The installed skill is the complete unattended baseline; optional
+context, the matching planned artifact, canonical artifact links, and bundled
+medium-specific authoring guidance. Version 2 requests remain readable for
+replay. The installed skill is the complete unattended baseline; optional
 provider capabilities can enhance composition but are not required. The core
-accepts only a schema-valid `explainer-kit.author-result/v2` containing exactly one of
-`content.markdown` or `content.html` plus non-secret provenance. Authored
-content is still checked for excessive verbatim overlap with the fact base.
+accepts only a schema-valid `explainer-kit.author-result/v2` containing exactly
+one of `content.markdown` or `content.html` plus non-secret provenance.
+Authored content is still checked for excessive verbatim overlap with the fact
+base.
 
 Direct callbacks and module entry points are first-class but transient: they
 never enter retained request contracts. See
@@ -143,9 +150,10 @@ planner, author, browser-session, and visual-critic boundaries.
 ### Planner-owned adaptive sets
 
 The set planner finalizes required and optional artifacts before authoring.
-Project recaps always contain a hub, architecture/system diagram, and deck;
-the planner may add only recipe-licensed optional views with a source-backed
-justification. Recipe and per-profile limits still bound the portfolio.
+New project recaps always contain a navigational hub. The planner may add only
+recipe-licensed optional diagrams, decks, or deep dives with a distinct reader
+question, source evidence, and medium rationale. Recipe and per-profile limits
+still bound the portfolio.
 Undeclared sources, conflicting ledger values, duplicate IDs, and unjustified
 optionals fail validation. Author results cannot add, remove, or replace
 artifacts.
@@ -188,11 +196,21 @@ evidence to an independent critic. Fixture sessions are test-only and are
 rejected in unattended production.
 
 A `correct` disposition permits one bounded correction and exactly one final
-review; there is no second correction or third review. Missing, forged,
+review; there is no second correction or third review. The correction budget is
+shared with the internal-link gate described below, so a `correct` disposition
+is refused outright with `E_VISUAL_CORRECTION` when link validation already
+spent the single bounded correction on this run. Missing, forged,
 cross-record-mismatched, or invalid evidence, a failed critic, or an unresolved
 correction ends as `built-needs-review`. Such output is retained for diagnosis
 but cannot become durable, finalized, archived, or published.
 
+The critic reviews the whole set for typography, hierarchy, composition,
+density, medium leverage, template repetition, diagram semantics, and
+cross-artifact cohesion. It returns the existing provider-neutral result:
+`pass` when no required correction remains or `correct` with concrete,
+artifact-scoped actions for the bounded correction round. No numeric design
+threshold is part of the contract.
+
 The approval record is also the durable source of truth for the resolved
 artifact set. It records every floor and accepted expansion artifact for all
 approval states, including pending and rejected, so a paused expanded run
@@ -221,6 +239,26 @@ Every legacy `ekrt1` token is rejected. A paused run created with the legacy
 format must restart to receive an authenticated token; editing retained package
 state cannot opt it into compatibility.
 
+### Internal-link validation
+
+Every internal reference in the rendered set must resolve to a
+manifest-declared target before the run can reach browser review. The gate runs
+after render and uses a bounded tokenizer rather than a general HTML parser.
+Relative references resolve from the current explicit file and must bind
+exactly to the manifest/site tree, and a referenced fragment must resolve to
+exactly one ID in its target document. Directory references, path traversal,
+missing targets, missing fragments, ambiguous fragments, and unsafe schemes all
+fail with `E_INTERNAL_REFERENCE`.
+
+A failure gets one bounded correction round, re-rendered and revalidated. That
+round is the same single budget the visual-review `correct` disposition uses —
+whichever gate reaches it first consumes it. Once it is exhausted the run fails
+hard: the QA stage is recorded `failed` with code-only evidence and the scrubbed
+message `The qa stage failed.`, and the run is neither durability- nor
+publication-eligible. No finding is retained, so nothing in the durable record
+names the broken reference; the failure is attributed to the `link-validation`
+evidence stage.
+
 ## Warnings and QA severity
 
 QA findings are split by severity, and the split is what lets thin content ship
@@ -296,9 +334,17 @@ Reviewed source and citation backlinks are absolute canonical GitHub blob URLs
 pinned to the exact 40-character commit revision and line range, so they
 survive project archival without resolving through a mutable branch or local
 checkout. Each recap also emits
-`site/initiatives/<slug>/catalog.json` from the finalized manifest. Its
-artifact IDs, types, paths, URLs, and source backlinks must remain in exact
-manifest parity; authors do not hand-maintain the catalog.
+`site/initiatives/<slug>/catalog.json` from the finalized manifest, versioned
+as `explainer-kit.initiative-catalog/v2`. Its artifact IDs, types, paths,
+URLs, and source backlinks must remain in exact manifest parity; authors do
+not hand-maintain the catalog. The catalog's `publicVerification` field is a
+**policy marker, never an outcome**: `required` when the run's public access
+policy calls for anonymous URL verification, `skipped-by-policy` for
+protected destinations. It records what the publication policy was — the
+per-artifact verification outcomes live in `publish-receipt.json`.
+Compatibility is regenerate-only: consumers parse the declared version, and
+no v1 read path exists because no released consumer could verify v1 catalog
+evidence.
 
 `manifest.immutableHashes` covers the exact retained bytes for
 `run-request.json`, content approval, fact-base JSON and Markdown, declared
@@ -322,12 +368,25 @@ Build success and durability are separate:
 
 The core verifies caller-supplied commit or publish evidence; it never creates
 Git commits. Publishing is always explicitly requested and human-gated. The
-public `s3-static` connector validates corresponding S3 and HTTPS roots with a
-run-unique sentinel, uploads only manifest-declared `site/` files, verifies the
-content type and SHA-256 response bytes at public URLs, and writes
-`publish-receipt.json`. Public roots cannot contain credentials, queries, or
-fragments. Publishing is additive and does not run a root-wide destructive
-sync.
+public `s3-static` connector validates each S3 and HTTPS root independently and
+proves the destination with a run-unique sentinel, uploads only
+manifest-declared `site/` files, and writes `publish-receipt.json`.
+Verification depends on the declared `publicAccess` policy: in `public` mode
+the connector anonymously fetches each published URL and compares content
+type and SHA-256 response bytes; in `protected` mode it verifies object
+integrity through authenticated S3 hashing instead, and every receipt entry
+records `publicVerification: skipped-protected` so the skipped anonymous
+check is visible rather than implied.
+
+Root screening is strict on both roots: no credentials, queries, or
+fragments; no whitespace, C0/C1 control characters, or backslashes; and the
+gate applies to every publish-request and publish-receipt contract version
+rather than being pinned to one version string. Public roots must be HTTPS
+and must not address loopback, link-local, or private networks, and
+verification fetches refuse redirects (`redirect: 'error'`) — see the
+[publication environment variables](/docs/cli-utilities/configuration#explainer-publication-environment-variables)
+for the explicit private-root opt-in and its durable receipt trace.
+Publishing is additive and does not run a root-wide destructive sync.
 
 Release validation drives the bounded curated-style/template matrix in a real
 installed Chromium browser and retains machine-readable viewport, clipping,
@@ -375,8 +434,9 @@ typed adapter settings.
 Private integrations use the core boundary directly: resolve private inputs
 before the run, construct one versioned request, invoke the core once, then
 publish or link the versioned manifest after the run. Wrapper acceptance reads
-the complete post-run `PublishReceiptV1`, verifies every manifest artifact and
-the core run ID, and rejects foreign or stale receipts. Presets, private source
+the complete post-run `publish-receipt/v2`, verifies every manifest artifact
+and the core run ID, and rejects foreign or stale receipts; `publish-receipt/v1`
+remains readable for replay of older runs only. Presets, private source
 systems, external-document synchronization, and personal destinations remain
 wrapper-owned.
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.30",
-  "docs-config": "0.2.30",
-  "docs-theme": "0.2.30",
-  "docs-transforms": "0.2.30"
+  "cli": "0.2.31",
+  "docs-config": "0.2.31",
+  "docs-theme": "0.2.31",
+  "docs-transforms": "0.2.31"
 }

package/assets/skills/explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explainer-kit
-version: 2.0.3
+version: 2.1.0
 description: Use when building destination-neutral visual explainer artifacts from explicit, versioned inputs.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
@@ -74,11 +74,13 @@ request.
 The recipe — never the author — selects each artifact's authoring path. Floor
 entries and expansion profiles declare `authoring: markdown` for the narrative
 path or `authoring: html` for the artistic path. The core invokes the author
-once per artifact with an `explainer-kit.author-request/v2` payload carrying the
+once per artifact with an `explainer-kit.author-request/v3` payload carrying the
 artifact identity and type, its authoring path, the inlined brief from
 `briefs/`, the reconciled fact base, the resolved theme, the shell source for
-artistic artifacts, and the required narrative sections for narrative floor
-artifacts. It accepts only a schema-valid
+artistic artifacts, the required narrative sections for narrative floor
+artifacts, and canonical `artifactLinks` with explicit `index.html` site paths
+and receiver-relative hrefs. Version 2 requests remain readable for replay. It
+accepts only a schema-valid
 `explainer-kit.author-result/v2` with exactly one of `content.markdown` or
 `content.html` plus non-secret provenance, rejects excessive verbatim source
 overlap, retains each validated result under `source/author/` and its content
@@ -107,11 +109,28 @@ continues. Accepted expansion artifacts render to
 `site/{directory}/{slug}/{artifactId}/index.html` and are linked from the floor
 hub; floor artifacts keep their existing paths.
 
+`project-recap@2` requires one complete navigational hub and makes diagrams,
+decks, and deep dives adaptive expansions. The planner proposes one only when
+it can name a distinct reader question, the supporting source evidence, and why
+that medium improves on adding more hub prose. The prose brief governs
+typographic roles, hierarchy, slide archetypes, diagram semantics,
+fit-to-content composition, density, repetition, and medium choice. These are
+editorial judgments, not new request fields or renderer rules.
+`project-recap@1` remains readable for replay with its historical three-artifact
+floor.
+
 ## Review, Approval, and Warnings
 
-Approval runs after theme, render, safety validation, the guideline checker, and
-render QA, immediately before publish and durability — so a reviewer approves
-rendered artifacts and the complete warning set, not raw prose.
+Approval runs after theme, render, hard internal-reference validation, safety
+validation, the guideline checker, and render QA, immediately before publish and
+durability — so a reviewer approves rendered artifacts and the complete warning
+set, not raw prose. The reference gate resolves `href`, `src`, `srcset`,
+fragments, and safe embedded references against explicit manifest/site-tree
+files. It may invoke the existing correction author once, then rerenders and
+revalidates before any browser or visual review. A later visual correction also
+rerenders and passes through the validation-only reference gate without
+receiving another correction attempt. An exhausted `E_INTERNAL_REFERENCE`
+finding fails closed and cannot reach durability.
 
 Interactive runs stop with an `incomplete` outcome once artifacts are built and
 checked. Review the rendered `site/` tree, the sources under `source/content/`,
@@ -144,7 +163,13 @@ succeed.
 
 Visual critics use the independent whole-set rubric in
 `references/visual-review.md`, which separates review judgment from
-medium-specific authoring rules.
+medium-specific authoring rules. They assess typography, hierarchy,
+composition, density, medium leverage, template repetition, diagram semantics,
+and cross-artifact cohesion from rendered browser evidence. The rubric keeps
+the existing provider-neutral result contract: `pass` means no required
+correction remains, while `correct` carries concrete artifact-scoped actions
+into the one bounded correction round. It does not assign design scores or
+encode geometry thresholds.
 
 Render QA is opt-in. It runs only against an injected `browserProbe`, and the
 core never launches a browser of its own — reviewing the rendered output in a

package/assets/skills/explainer-kit/briefs/project-recap.md

@@ -34,14 +34,32 @@ Use the same terms, statuses, and numbers throughout.
 
 ## Floor
 
-Produce one rich narrative hub covering all six sections above. It must contain
-at least one high-level architecture diagram, structured lists where useful,
-and evidence tables for implementation and validation. The page should remain
-useful without any expansion artifact.
+Produce one rich navigational hub covering all six sections above. It must
+orient the reader, expose the project state and outcome in the first viewport,
+and link every selected artifact with descriptive labels. The hub should remain
+complete and useful without an expansion artifact.
+
+Establish deliberate typographic roles for the title, framing statement,
+section headings, labels, body text, and evidence annotations. Build hierarchy
+through scale, spacing, contrast, and grouping instead of applying one repeated
+card or section treatment everywhere. Keep density fit to the material: shorten
+or restructure crowded passages, but do not pad sparse evidence with decorative
+filler. Choose tables, lists, diagrams, and prose only when each medium makes
+the evidence easier to understand.
 
 ## Expansion license
 
-Propose additional diagrams, a deep-dive, or a walkthrough deck when complexity
-earns it. Expansion should clarify a real boundary, flow, trade-off, or
-operational handoff that would overload the hub. Do not expand to repeat the
+Propose a supporting diagram, walkthrough deck, or deep-dive only when it
+answers a distinct reader question that the hub cannot answer cleanly. For
+every proposal, identify the reader question, the source evidence that supports
+it, and the rationale for choosing that medium. Do not expand to repeat the
 same story in another format.
+
+Use a diagram when topology, direction, ownership, or flow carries meaning.
+Preserve branches, fan-in, cycles, labels, and explicit relationships, and fit
+the frame to the content rather than leaving a tiny graph in a large canvas.
+Use a deck only when pacing adds value; choose slide archetypes to match the
+story, such as an outcome opener, comparison, system view, decision, evidence,
+or next-action frame. Vary composition to fit each claim instead of repeating
+one template. Use a deep-dive when source-backed mechanics or trade-offs need
+more room than the hub can give them.

package/assets/skills/explainer-kit/recipes/project-recap.v2.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": "explainer-kit.recipe/v2",
+  "id": "project-recap",
+  "version": "2",
+  "sourceRoles": [
+    {
+      "role": "project",
+      "required": true,
+      "accepts": ["file", "directory", "git", "github"],
+      "minBindings": 1,
+      "maxBindings": 1
+    }
+  ],
+  "floor": [
+    {
+      "id": "project-recap",
+      "type": "hub",
+      "authoring": "html",
+      "template": "house-style",
+      "required": true,
+      "briefRef": "briefs/project-recap.md",
+      "requiredNarrative": [
+        "original-request",
+        "key-agent-decisions",
+        "as-built-architecture",
+        "implementation-record",
+        "validation-evidence",
+        "outcome"
+      ]
+    }
+  ],
+  "expansion": {
+    "profiles": [
+      {
+        "profileId": "supporting-diagram",
+        "type": "diagram",
+        "authoring": "html",
+        "briefRef": "briefs/supporting-diagram.md",
+        "shell": "diagram-shell",
+        "maxCount": 1
+      },
+      {
+        "profileId": "walkthrough-deck",
+        "type": "deck",
+        "authoring": "html",
+        "briefRef": "briefs/walkthrough-deck.md",
+        "shell": "deck-shell",
+        "maxCount": 1
+      },
+      {
+        "profileId": "deep-dive",
+        "type": "explainer",
+        "authoring": "markdown",
+        "briefRef": "briefs/deep-dive.md",
+        "maxCount": 3
+      }
+    ],
+    "limits": {
+      "maxArtifacts": 5
+    }
+  },
+  "fallback": {
+    "mode": "deterministic-markdown",
+    "selection": "explicit",
+    "authoring": "markdown",
+    "scope": "portfolio"
+  },
+  "discoveryLimits": {
+    "consecutiveNoNewFindingsRounds": 2,
+    "maxRounds": 8
+  }
+}