@open-agent-toolkit/cli 0.2.30 → 0.2.32

package/assets/skills/create-agnostic-skill/references/docs/skills-guide.md

@@ -279,13 +279,24 @@ supported home for Cursor-only skills. Cursor also reads `.claude/skills/` and
 **Skill locations:**
 
 - Project:
-  - `.github/skills/<skill-name>/SKILL.md`
+  - `.agents/skills/<skill-name>/SKILL.md` (**native canonical path**)
+  - `.github/skills/<skill-name>/SKILL.md` (**legacy/adoption path**)
   - `.claude/skills/<skill-name>/SKILL.md` (**Claude compatibility**)
 - Personal:
-  - `~/.copilot/skills/<skill-name>/SKILL.md` (Copilot coding agent and GitHub Copilot CLI only)
+  - `~/.agents/skills/<skill-name>/SKILL.md` (**native canonical path**)
+  - `~/.copilot/skills/<skill-name>/SKILL.md` (**legacy/adoption path**)
   - `~/.claude/skills/<skill-name>/SKILL.md` (**Claude compatibility**; Copilot coding agent and GitHub Copilot CLI only)
 
-**Notable:** Like Cursor, Copilot reads from `.claude/skills/` for cross-tool compatibility at both project and personal scopes. Organization-level and enterprise-level skill support is coming soon.
+**Notable:** Like Cursor, Copilot reads canonical `.agents/skills/` at project
+and personal scope. OAT does not generate `.github/skills` or
+`~/.copilot/skills` views; existing packages there remain adoption inputs.
+Copilot agents and project rules still use `.github/agents`,
+`~/.copilot/agents`, and `.github/instructions`.
+
+OAT asks whether to adopt each unresolved legacy Copilot skill into canonical
+storage or keep it Copilot-only as an exact known stray. Same-name canonical
+collisions block keep-local. Legacy cleanup removes only verified clean managed
+views and preserves changed or unverifiable content.
 
 **Notes:** The `license` field may be required in practice even though the spec marks it optional (see https://github.com/github/copilot-cli/issues/894).
 
@@ -343,16 +354,14 @@ Installs skills from GitHub repos, local paths, or GitLab URLs to any supported
 
 ### Symlink Approach (Recommended)
 
-Author skills in `.agents/skills/` (canonical) and distribute to provider-specific directories:
+Author skills in `.agents/skills/` (canonical) and distribute only to providers
+that require a provider-specific directory:
 
 ```bash
 # Claude Code
 ln -s ../../.agents/skills/my-skill .claude/skills/my-skill
 
-# GitHub Copilot
-ln -s ../../.agents/skills/my-skill .github/skills/my-skill
-
-# Cursor, Codex, and Gemini read .agents/skills/ natively — no symlink needed
+# Cursor, Copilot, Codex, and Gemini read .agents/skills/ natively — no symlink needed
 ```
 
 For automated distribution, use **OAT sync** (for local/internal skills) or **`npx skills add`** (for remote/community skills):
@@ -365,11 +374,12 @@ oat sync --scope all
 npx skills add github-user/skill-repo -a claude-code -a github-copilot
 ```
 
-**Result: one canonical source, two symlinks, five tools.**
+**Result: one canonical source, one symlink, five tools.**
 
-**Note:** Cursor, Codex, and Gemini read `.agents/skills/` directly at project
-and user scope. Keep `.cursor/skills/` for intentionally Cursor-only skills,
-not as a generated mirror of canonical content.
+**Note:** Cursor, Copilot, Codex, and Gemini read `.agents/skills/` directly at
+project and user scope. Keep `.cursor/skills/` for intentionally Cursor-only
+skills, not as a generated mirror of canonical content. Treat `.github/skills/`
+and `~/.copilot/skills/` as legacy Copilot adoption inputs, not mirrors.
 
 ---
 
@@ -523,31 +533,33 @@ The proposal has community interest but no official timeline or maintainer respo
 
 **Source:** https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices, https://github.com/agentskills/agentskills/tree/main/skills-ref
 
-### Q: Does Cursor's native `.agents/skills/` support eliminate all provider views?
+### Q: Do native `.agents/skills/` mappings eliminate all provider views?
 
-**Answer:** No. Cursor, Codex, and Gemini need no skill mirror, but Claude Code
-and GitHub Copilot still use provider-specific paths:
+**Answer:** No. Cursor, Copilot, Codex, and Gemini need no skill mirror, but
+Claude Code still uses a provider-specific path. Provider-specific agent and
+rule views also remain where those runtimes require them:
 
 | Tool           | Native Path       | Reads `.claude/skills/`? | Reads `.agents/skills/`? |
 | -------------- | ----------------- | ------------------------ | ------------------------ |
 | Claude Code    | `.claude/skills/` | ✅ (native)              | ❌                       |
 | Cursor         | `.agents/skills/` | ✅ (compatibility)       | ✅ (native)              |
 | Codex CLI      | `.agents/skills/` | ❌                       | ✅ (native)              |
-| GitHub Copilot | `.github/skills/` | ✅ (compatibility)       | ❌                       |
+| GitHub Copilot | `.agents/skills/` | ✅ (compatibility)       | ✅ (native)              |
 | Gemini CLI     | `.agents/skills/` | ❌                       | ✅ (native alias)        |
 
-**Recommended approach:** Author skills in `.agents/skills/` (tool-agnostic canonical source), then symlink only where needed:
+**Recommended approach:** Author skills in `.agents/skills/` (tool-agnostic
+canonical source), then symlink only where needed:
 
 ```bash
-# Two symlinks needed:
+# One symlink needed:
 ln -s ../../.agents/skills/my-skill .claude/skills/my-skill    # Claude Code + Copilot compatibility
-ln -s ../../.agents/skills/my-skill .github/skills/my-skill    # GitHub Copilot (native path)
-# Cursor, Codex, and Gemini read .agents/skills/ natively — no symlink needed
+# Cursor, Copilot, Codex, and Gemini read .agents/skills/ natively — no symlink needed
 ```
 
-**One canonical source, two symlinks, five tools.** (Copilot reads `.claude/skills/` cross-compat, so the `.github/skills` symlink is optional but recommended for explicitness.)
+**One canonical source, one symlink, five tools.** Legacy `.github/skills` and
+`~/.copilot/skills` entries are migration candidates, not recommended mirrors.
 
-**Note (updated July 2026):** Cursor, Codex, and Gemini read
+**Note (updated August 2026):** Cursor, Copilot, Codex, and Gemini read
 `.agents/skills/` natively at project and user scope. No skill symlinks are
 needed for those providers.
 

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
+  }
+}

package/assets/skills/explainer-kit/references/contracts.md

@@ -34,25 +34,34 @@ Every run, interactive or unattended, also requires a provider-neutral author
 callback; a run without one fails `E_AUTHOR_REQUIRED`. An in-process caller
 supplies `options.author(request)`; a JSON-only CLI caller uses
 `--author-module author.mjs`. The core invokes it once per resolved artifact
-with an `explainer-kit.author-request/v2` payload containing the artifact
+with an `explainer-kit.author-request/v3` payload containing the artifact
 identity and type, the artifact's authoring path, the inlined brief, the bundled
 `visualAuthoringGuidance`, the reconciled fact base, the resolved theme, the
 shell source for artistic artifacts, the required narrative sections for
-narrative floor artifacts, and bounded-discovery context. The guidance is
+narrative floor artifacts, bounded-discovery context, and `artifactLinks`.
+Each canonical link entry names the planned artifact, its explicit site-relative
+path ending in `index.html`, and the relative `href` from the receiving
+artifact's own location. The guidance is
 loaded only from the installed skill's `references/visual-authoring.md`; no
 ambient or home-directory file is consulted. The callback must return an
 `explainer-kit.author-result/v2` carrying exactly one of `content.markdown` or
 `content.html`, matching the artifact's declared authoring path, plus non-secret
 provenance. The executable callback is never persisted in `run-request.json`.
 
-Project recap requests have an explicit `recapMode`. Omitting it selects and
-persists `artistic`, which keeps the recipe's rich HTML floor. Selecting
-`deterministic-markdown` before the run applies the recipe-owned fallback to
-the complete planned portfolio, including optional expansions, while retaining
-the same adaptive hub, architecture, and deck identities. The resulting
-Markdown author records and `source/content/*.md` paths remain distinct in the
-manifest and immutable rebuild package. An artistic author failure fails the
-run; the core never silently retries or downgrades it as Markdown.
+New project recap producers select immutable `project-recap@2`. Its
+navigational hub is the only mandatory artifact. A diagram, deck, or deep dive
+is an optional expansion only when its justification states a distinct reader
+question, supporting source evidence, and the rationale for using that medium.
+Project recap requests also have an explicit `recapMode`. Omitting it selects
+and persists `artistic`, which keeps the recipe's rich HTML floor. Selecting
+`deterministic-markdown` before the run applies the recipe-owned fallback to the
+complete planned portfolio — the hub plus any accepted expansions — without
+changing its artifact identities. The resulting Markdown author records and
+`source/content/*.md` paths remain distinct in the manifest and immutable
+rebuild package. An artistic author failure fails the run; the core never
+silently retries or downgrades it as Markdown. `project-recap@1` is immutable
+replay guidance only: retained v1 requests remain readable, but current
+producers do not select it.
 
 Before artifact authoring, a caller supplies one provider-neutral `planSet`
 callback. It receives the reconciled fact base and recipe policy and returns
@@ -62,7 +71,7 @@ callback. It receives the reconciled fact base and recipe policy and returns
 {
   "schemaVersion": "explainer-kit.set-plan/v1",
   "planId": "project-recap-set",
-  "recipe": { "id": "project-recap", "version": "1" },
+  "recipe": { "id": "project-recap", "version": "2" },
   "sourceIds": ["plan"],
   "ledger": {
     "terminology": [],
@@ -87,9 +96,11 @@ The set plan owns the shared terminology/status/number ledger, source coverage,
 adaptive portfolio, per-artifact draft, and visual intent. Optional entries add
 a source-backed `justification`; undeclared sources, conflicting ledger values,
 duplicate artifact IDs, and unjustified optional entries are invalid. Each
-`author-request/v2` carries the complete immutable `setContext` plus the exact
+`author-request/v3` carries the complete immutable `setContext` plus the exact
 matching `plannedArtifact`. The planner finalizes floor and expansion entries
 before authoring; author results cannot add, remove, or replace artifacts.
+Version 2 requests remain valid for deterministic replay; new runs emit only
+the complete v3 request.
 When a planner draft contains a supported non-linear graph, the request also
 carries its closed `graphSemantics` (direction, nodes, edges, and topology).
 Artistic HTML must expose one exact `data-direction`. Each planned node requires
@@ -183,12 +194,33 @@ The core executes:
 5. author every planned artifact against the same set context
 6. render typed artifacts through the narrative renderer or validate
    agent-composed HTML, per each artifact's declared authoring path
-7. run structural and guideline QA, plus required browser and independent
+7. validate every post-render `href`, `src`, `srcset`, and embedded reference
+   against the manifest paths and generated site tree; reject directory links,
+   escapes, missing files or fragments, malformed references, and unsafe
+   embedded resources
+8. optionally apply one bounded author correction, then rerender and revalidate
+   the complete site before any browser callback
+9. run structural and guideline QA, plus required browser and independent
    visual review for unattended project recaps
-8. close any unresolved recap review gate before external persistence
-9. resolve content approval — the interactive gate pauses here, after render and
-   QA and before anything is published or persisted externally
-10. write the manifest and build record
+10. close any unresolved recap review gate before external persistence
+11. resolve content approval — the interactive gate pauses here, after render and
+    QA and before anything is published or persisted externally
+12. write the manifest and build record
+
+The internal-reference gate uses a bounded tokenizer/classifier rather than a
+general HTML parser. Relative references resolve from the current explicit file
+with an isolated HTTPS base, then must bind exactly to the manifest/site tree.
+Referenced fragments must resolve to exactly one ID in the target document;
+unused duplicate renderer-generated IDs do not fail indexing. Safe base64 image
+data references and same-document fragments are classified separately. A
+malformed, unresolved, or ambiguous reference fails `E_INTERNAL_REFERENCE`.
+Once the one correction is exhausted, including after visual correction, 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 not durability- or
+publication-eligible. No finding is retained and nothing names the broken
+reference — terminal evidence is code-only by design, and the failure is
+attributed to the `link-validation` evidence stage rather than to
+`browser-review`.
 
 An incomplete interactive result includes
 `approval.resumeToken: "ekrt2:<64 lowercase hex characters>"`. The token is an

package/assets/skills/explainer-kit/references/destination-contract.md

@@ -10,15 +10,39 @@ node scripts/publish.mjs \
   --confirm-publish
 ```
 
-The request uses `explainer-kit.publish-request/v1`. Credentials come only from
-the standard AWS credential chain or the request's optional profile. Never put
-access keys, secret keys, session tokens, or SSO tokens in a request.
-
-## Corresponding roots
-
-`s3Uri` and `publicBaseUrl` must identify corresponding roots. Both are
-normalized without trailing slashes. For a path `P` relative to `siteRoot`, the
-connector writes `<s3Uri>/P` and verifies `<publicBaseUrl>/P`.
+New requests use `explainer-kit.publish-request/v2` and explicitly declare
+`publicAccess` as `public` or `protected`. V1 remains readable as public-mode
+replay. Credentials come only from the standard AWS credential chain or the
+request's optional profile. Never put access keys, secret keys, session tokens,
+or SSO tokens in a request.
+
+## How the two roots compose
+
+`s3Uri` and `publicBaseUrl` are each normalized without trailing slashes. For a
+path `P` relative to `siteRoot`, the connector writes `<s3Uri>/P` and verifies
+`<publicBaseUrl>/P`. That composition is the whole of the relationship.
+
+**No relational validation is performed between the two roots, by design.** The
+mapping from an S3 key to a public URL is underdetermined by these two strings:
+it lives in CDN configuration the connector cannot read. Both of these are
+legitimate, and they disagree structurally:
+
+| Shape | `s3Uri`                      | `publicBaseUrl`               |
+| ----- | ---------------------------- | ----------------------------- |
+| A     | `s3://bucket/repositories/x` | `https://host/repositories/x` |
+| B     | `s3://bucket/explainers`     | `https://host`                |
+
+B is an ordinary CloudFront **Origin Path** deployment, where a bucket prefix is
+mapped to the distribution root. Requiring the public path to equal the S3 key
+prefix rejects it. Suffix-containment does not rescue the rule either — an empty
+public path is a suffix of everything, so B would pass vacuously while
+path-rewriting deployments (CloudFront Functions, Lambda@Edge, custom origins)
+still produce false rejections.
+
+Divergence between the two paths is therefore reported as a **non-blocking
+warning**, never a failure. Correctness of an advertised URL is established by
+verification, not by string shape — which is also why `publicAccess: protected`,
+where no anonymous fetch happens, cannot establish it at all.
 
 For example:
 
@@ -32,7 +56,39 @@ For example:
 | public URL              | `https://cdn.example.com/published/initiatives/demo/index.html` |
 
 Use explicit `index.html` URLs. Directory redirects are not portable evidence.
-The destination must serve uploaded bytes at the corresponding public path.
+The destination must serve the uploaded bytes at the composed public path. That
+is a requirement on the deployment, not something the connector validates from
+the two root strings; see below.
+
+## The manifest a connector receives is intentionally incomplete
+
+The core persists the manifest **before** it invokes the publisher callback, so
+the file at `manifestPath` carries `outcome: "incomplete"` while the `publish`
+stage is still `running`. This is a contractually intended intermediate state,
+not a corrupt or half-written record, and a connector must not reject it on the
+strength of `outcome` alone.
+
+Do not decide publishability from the manifest by itself. Read the build record
+named by `manifest.buildRecord.path` (resolved relative to the manifest) and
+require all of:
+
+- the manifest carries no `visual-review-required:` warning;
+- the build record's own `outcome` is `incomplete`;
+- its `publish` stage exists and is `running`; and
+- every stage before `publish` is `passed`, `warned`, or `skipped` and carries
+  no `visual-review-required:` warning.
+
+Only that combination makes an `incomplete` manifest publishable. The one other
+eligible shape is a finalized `built-durable` manifest that is not
+review-flagged. Any other `incomplete` manifest, and every manifest whose run is
+flagged, failed, or superseded, must be refused. The built-in connector performs
+exactly this check before its first network call; third-party connectors are
+required to perform an equivalent one.
+
+The published bytes cannot diverge from the finalized manifest: the catalog
+projection omits `outcome` and `warnings`, and both manifest writes share one
+`finalizedAt`. After the callback returns a valid receipt, the core rewrites the
+manifest with its terminal outcome.
 
 ## Safety and ordering
 
@@ -41,16 +97,22 @@ site-relative paths before network access. It then:
 
 1. uploads a sentinel whose path contains the run ID and a random 128-bit
    suffix;
-2. verifies the sentinel with `head-object`;
-3. fetches that exact sentinel through the public root;
+2. verifies the sentinel with a service-computed SHA-256 checksum or an
+   authenticated download hash;
+3. for public destinations, fetches that exact sentinel anonymously through the
+   public root; protected destinations skip this public fetch explicitly;
 4. deletes only that sentinel;
 5. uploads or idempotently skips each declared artifact;
-6. verifies object metadata, content type, and SHA-256 of the exact response
-   bytes from each public artifact URL; and
-7. atomically writes `explainer-kit.publish-receipt/v1`.
+6. verifies exact object bytes from service-computed SHA-256 evidence or an
+   authenticated download hash, then additionally verifies the exact anonymous
+   response bytes for public destinations; and
+7. atomically writes `explainer-kit.publish-receipt/v2` with separate
+   authenticated-object and anonymous-public verification facts.
 
-If public sentinel verification fails, no artifact is uploaded. The connector
-attempts sentinel cleanup and emits no successful receipt.
+If required sentinel verification fails or its verification capability is
+unavailable, no artifact is uploaded. The connector attempts sentinel cleanup
+and emits no successful receipt. An undeclared `401` or `403` in public mode is
+a verification failure, never evidence that the destination is protected.
 
 Publishing is additive. The implementation uses individual `put-object`,
 `head-object`, and sentinel-only `delete-object` operations. It never performs
@@ -74,10 +136,13 @@ Every upload sets metadata explicitly:
 | other   | manifest media type or `application/octet-stream` |
 
 Artifacts use `Cache-Control: public, max-age=300`. The connector stores the
-SHA-256 digest as object metadata for idempotency and verifies content type,
-cache control, and digest after upload. Public verification hashes response
-bytes without text decoding, so binary artifacts and stale wrong-byte 200
-responses are covered.
+SHA-256 digest as object metadata for idempotency and supplies
+`--checksum-sha256` on upload. It requests service checksum evidence with
+`--checksum-mode ENABLED`; caller-authored metadata and ETags are never treated
+as object-byte proof. When service SHA-256 evidence is unavailable, the
+connector hashes bytes from an authenticated download. Public verification
+separately hashes response bytes without text decoding, so binary artifacts and
+stale wrong-byte 200 responses are covered.
 
 ## Failures and retries
 
@@ -86,9 +151,60 @@ not run `aws sso login`, retry with another profile, expose AWS diagnostics, or
 persist credentials. Refresh credentials separately and rerun after approval.
 
 Only transient individual object-operation failures receive bounded retries.
-Input, authorization, root-correspondence, metadata, and public-verification
-failures are not retried. A failed publish preserves the local package.
+Input, authorization, metadata, and public-verification failures are not
+retried. A failed publish preserves the local package.
 
 Public roots must be credential-free HTTPS URLs with no username, password,
-query, or fragment. Invalid roots fail before AWS or HTTP operations and are
-never persisted in receipts.
+query, or fragment. Three further rejections apply, all before any AWS or HTTP
+operation, and none of them are ever persisted in receipts:
+
+- **Control characters.** Any codepoint in `0x00`–`0x1f` or `0x7f`–`0x9f`, and
+  any backslash, in either root. These otherwise reach S3 object keys, composed
+  public URLs, the catalog, the receipt and `aws` argv; `0x9b` is the 8-bit CSI.
+- **Non-public addresses.** Loopback, link-local (`169.254.0.0/16`, `fe80::/10`,
+  including the `169.254.169.254` instance-metadata address), unique-local
+  (`fc00::/7`) and RFC 1918 private hosts, in both literal IPv4 and IPv6 forms
+  including IPv4-mapped spellings. Public verification issues an outbound GET
+  against whatever the root names, so an unconstrained root is a request
+  primitive aimed at internal addresses. Set
+  `EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT=1` to opt back in for a genuinely
+  internal mirror. The policy is address-literal only: a hostname that happens
+  to resolve inward is not detected.
+- **Redirects.** Public verification uses `redirect: 'error'`. A canonical
+  artifact URL is uploaded to a known key and should never legitimately
+  redirect, so any redirecting destination is a hard verification failure rather
+  than something to follow. A destination that requires redirects is
+  incompatible with this connector and will report as such rather than failing
+  opaquely later.
+
+## The generated initiative catalog
+
+The connector generates one auxiliary artifact the manifest does not declare: an
+initiative catalog at `site/initiatives/<slug>/catalog.json`, uploaded alongside
+the declared artifacts and recorded in the receipt as
+`source: { kind: 'auxiliary', name: 'catalog' }`.
+
+A third-party connector must reproduce it **byte for byte**, because
+`recordDurability` rebuilds it from the manifest and compares hashes; a mismatch
+rejects the publication with `cross-record-mismatch`. Build it with
+`catalogFromManifest(manifest, publicBaseUrl, { publicAccess })` and serialize
+with `serializeInitiativeCatalog`, rather than constructing it by hand.
+
+Two properties matter most:
+
+- The `{ publicAccess }` option is **required**. Omitting it raises a
+  `TypeError` rather than defaulting, because the policy selects a field inside
+  the serialized bytes and therefore changes the hash. Pass
+  `{ publicAccess: undefined }` for `publish-request/v1`, which has no such
+  field and is public by definition.
+- `publicVerification` carries **policy, never outcome**: `"required"` for
+  public destinations and `"skipped-by-policy"` for protected ones. The catalog
+  is serialized and hashed before the first upload and long before any
+  per-artifact verification runs, so it cannot carry a verification result
+  without invalidating its own hash. The authoritative outcome lives in the
+  publish receipt, which the catalog's `runId` identifies. Never write
+  `"verified"` into a catalog.
+
+Publishability is gated by `assertManifestPublishable`, which raises
+`E_PUBLISH_OUTCOME` for a manifest that is not eligible; see the intermediate
+`incomplete` state described above.