@open-agent-toolkit/cli 0.2.30 → 0.2.32

package/assets/bundle-metadata.json

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

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/provider-sync/commands.md

@@ -33,15 +33,16 @@ Key behavior:
 
 - Scope support (`project`, `user`, `all`)
 - Optional interactive stray adoption
-- Cursor-local skills are handled individually: Adopt moves the skill into the
-  matching canonical `.agents/skills` directory, while Keep Cursor-only
-  preserves it and records its exact path in the applicable sync config
-- Aborting a Cursor migration preserves completed choices and leaves the
-  current and remaining skills unresolved
-- Keep Cursor-only is blocked when a canonical skill has the same name; rename
-  one skill before retrying
-- Non-interactive and JSON modes report unresolved Cursor skill actions without
-  choosing or mutating a disposition
+- Cursor-local and Copilot-local skills are handled individually: Adopt moves
+  the skill into the matching canonical `.agents/skills` directory, while Keep
+  provider-only preserves it and records its exact path in the applicable sync
+  config
+- Aborting a native-read skill migration preserves completed choices and leaves
+  the current and remaining skills unresolved
+- Keep provider-only is blocked when a canonical skill has the same name;
+  rename one skill before retrying
+- Non-interactive and JSON modes report unresolved native-read skill actions
+  without choosing or mutating a disposition
 - JSON output for automation
 
 ## `oat sync`
@@ -57,7 +58,11 @@ Key behavior:
 - Provider enable/disable honored via sync config
 - Cursor skills are native-read from canonical `.agents/skills`; sync does not
   create `.cursor/skills` mirrors
-- Upgrade cleanup removes only verified clean legacy Cursor skill views.
+- Copilot skills are native-read from canonical `.agents/skills`; sync does not
+  create `.github/skills` or `~/.copilot/skills` mirrors. Copilot agents and
+  project rules still sync to `.github/agents`, `~/.copilot/agents`, and
+  `.github/instructions`.
+- Upgrade cleanup removes only verified clean legacy Cursor or Copilot skill views.
   Changed or unverified views are preserved and detached from obsolete manifest
   ownership.
 

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -97,6 +97,29 @@ manifest-owned path before acting:
 Use `oat sync --scope <project|user|all> --dry-run` to distinguish planned
 removal from preserve-and-detach operations before running a mutating sync.
 
+### Copilot skill migration
+
+Copilot reads canonical project and user skills directly from `.agents/skills`
+and `~/.agents/skills`. OAT no longer generates `.github/skills` or
+`~/.copilot/skills` views, but it still scans those legacy directories as
+adoption sources.
+
+Interactive `oat init` and `oat status` ask about each unresolved Copilot-local
+skill separately. Adopt moves it into the matching canonical directory without
+recreating a provider view or manifest entry. Keep Copilot-only leaves it in
+place and records its exact path as a known stray. A same-name canonical skill
+blocks Keep Copilot-only until one package is renamed. Non-interactive and JSON
+modes report pending migration actions without choosing a disposition.
+
+During upgrade cleanup, OAT removes only verified clean manifest-owned views.
+Changed, replaced, broken, unreadable, or otherwise unverifiable paths are
+preserved and detached from obsolete manifest ownership so they remain
+available for adoption or manual resolution.
+
+Copilot agent mappings remain materialized under `.github/agents` and
+`~/.copilot/agents`, and project rules remain rendered under
+`.github/instructions`; this retirement behavior applies only to skill views.
+
 For rules, adoption maps provider-native files back into `.agents/rules/*.md`:
 
 - Claude: `.claude/rules/*.md`

package/assets/docs/provider-sync/providers.md

@@ -31,8 +31,12 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
 
 === "Copilot"
 
-    - Project: `.agents/skills` -> `.github/skills`, `.agents/agents` -> `.github/agents`, `.agents/rules` -> `.github/instructions`
-    - User: `~/.agents/skills` -> `~/.copilot/skills`, `~/.agents/agents` -> `~/.copilot/agents`
+    - Project skills are native-read from `.agents/skills`; agents and rules still sync to `.github/agents` and `.github/instructions`
+    - User skills are native-read from `~/.agents/skills`; agents still sync to `~/.copilot/agents`
+    - `.github/skills` and `~/.copilot/skills` are legacy adoption sources. OAT does not generate skill views there.
+    - Interactive `oat init` and `oat status` ask for an individual disposition for each unresolved Copilot-local skill: adopt it into `.agents/skills` or keep it Copilot-only and remember the exact path in sync config
+    - Keep-local is blocked when a canonical skill has the same name
+    - During upgrades, OAT removes only verified clean legacy managed skill views. Changed or unverifiable views are preserved, detached from manifest ownership, and offered for adoption.
     - Rule files render as `.github/instructions/*.instructions.md`
     - Canonical always-on rules render with `applyTo: "**"` so Copilot activates them repo-wide; provider rules with exactly `applyTo: "**"` adopt back to `activation: always`
     - Comma-containing globs are not supported for Copilot rule sync because Copilot uses a comma-separated `applyTo` field
@@ -113,6 +117,8 @@ than falling back to the root target or a base role.
 - Adoption reconciles canonical plus the adopted provider first.
 - Native-read Cursor skill adoption moves the provider-local skill into `.agents/skills` without recreating a `.cursor/skills` view or manifest entry.
 - Choosing Keep Cursor-only leaves the skill in place and records its exact normalized path in the project or user sync config.
+- Native-read Copilot skill adoption moves a legacy provider-local skill into the matching canonical `.agents/skills` directory without recreating a `.github/skills` or `~/.copilot/skills` view or manifest entry.
+- Choosing Keep Copilot-only leaves the skill in place and records its exact normalized path in the project or user sync config.
 - Rule adoption normalizes provider filenames back to canonical `.agents/rules/*.md` entries before cross-provider fanout.
 - Cross-provider fanout is explicit via `oat sync --scope all`.
 

package/assets/docs/provider-sync/scope-and-surface.md

@@ -13,8 +13,9 @@ This capability is intentionally independent from OAT workflow artifacts. Teams
 
 - Canonical directories: `.agents/skills`, `.agents/agents`, `.agents/rules`
 - Managed provider views: `.claude/*`, `.cursor/*`, `.github/*`, `.copilot/*`, `.codex/*` (where applicable)
-- Native-read mappings use canonical `.agents/*` directly without mirrored provider directories. Cursor skills, Gemini skills and agents, and Codex canonical mappings use this model.
+- Native-read mappings use canonical `.agents/*` directly without mirrored provider directories. Cursor and Copilot skills, Gemini skills and agents, and Codex canonical mappings use this model.
 - Cursor's `.cursor/skills` and `~/.cursor/skills` directories are provider-local extension and adoption surfaces, not managed output directories.
+- Copilot's legacy `.github/skills` and `~/.copilot/skills` directories are adoption sources, not managed output directories. Copilot agents and project rules still use `.github/agents`, `~/.copilot/agents`, and `.github/instructions` provider views.
 - Manifest tracking: `.oat/sync/manifest.json` (project) and `~/.oat/sync/manifest.json` (user)
 
 Rules are currently project-scoped canonical content. Unlike skills and agents, synced rule files for Claude, Cursor, and Copilot are rendered copies with provider-specific frontmatter and filename extensions.
@@ -51,6 +52,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
 - `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
 - Cursor provider enablement still controls agents, rules, migration discovery, and legacy cleanup even though Cursor reads canonical skills without a generated skill view.
+- Copilot provider enablement still controls agents, project rules, migration discovery, and legacy cleanup even though Copilot reads canonical skills without a generated skill view.
 - Codex project-scope subagent sync writes `.codex/config.toml` and `.codex/agents/*.toml` at command layer after path-mapping sync. Every generated project Codex variant and registration is repository-owned, version-controlled provider output. OAT provides no automatic ignore mechanism for this project output; collaborators review and commit it like other project configuration.
 - Default Codex execution requires `root (0) → phase implementer (1)`. Sync and direct materialization continue to apply an `agents.max_depth` floor of `2` as optional nested-work capability without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
 - Missing depth or depth `1` does not block default phase execution. Invalid values or explicit values below `1` fail managed implementation preflight. `oat doctor` reports whether optional depth-two nesting is available and gives a scope-specific repair when the configured value is unusable.

package/assets/docs/reference/file-locations.md

@@ -17,6 +17,11 @@ For detailed `.oat/` tree semantics, see:
 - Cursor reads project skills directly from `.agents/skills/` and user skills
   directly from `~/.agents/skills/`. `.cursor/skills/` remains a Cursor-only
   extension and adoption surface, not generated output.
+- Copilot reads project skills directly from `.agents/skills/` and user skills
+  directly from `~/.agents/skills/`. OAT treats legacy `.github/skills/` and
+  `~/.copilot/skills/` as adoption sources, not generated output. Copilot agents
+  still sync to `.github/agents/` and `~/.copilot/agents/`, and project rules
+  still sync to `.github/instructions/`.
 
 ## OAT runtime/state
 

package/assets/docs/reference/troubleshooting.md

@@ -31,6 +31,24 @@ Use `.cursor/skills` only for intentionally Cursor-specific packages. Interactiv
 `oat init` and `oat status` offer each unresolved Cursor-local skill for
 canonical adoption or a remembered Keep Cursor-only choice.
 
+## Copilot appears detected but no skill sync actions are listed
+
+Expected for native-read skill mappings. Verify project skills under
+`.agents/skills` and personal skills under `~/.agents/skills`; Copilot reads
+those canonical directories directly. Sync will not create `.github/skills` or
+`~/.copilot/skills` mirrors.
+
+Legacy skills in those provider directories remain adoption candidates. Run
+`oat sync --scope <project|user|all> --dry-run` before upgrading: verified clean
+managed views may be removed, while changed or unverifiable paths are preserved
+and detached from obsolete manifest ownership. Copilot agents and project rules
+continue to sync to `.github/agents`, `~/.copilot/agents`, and
+`.github/instructions`.
+
+Interactive `oat init` and `oat status` offer each unresolved legacy skill for
+canonical adoption or a remembered Keep Copilot-only choice. Keep is blocked
+when a same-name canonical skill exists; rename one package before retrying.
+
 ## `sync` reports provider config mismatch
 
 - For interactive runs, select detected providers to enable when prompted.

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.32",
+  "docs-config": "0.2.32",
+  "docs-theme": "0.2.32",
+  "docs-transforms": "0.2.32"
 }