@open-agent-toolkit/cli 0.2.29 → 0.2.31

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.

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

@@ -20,13 +20,18 @@ Private wrappers may retain presets, vault conventions, Google Docs behavior,
 and personal destinations around this seam. Those values are wrapper-owned;
 they are not OAT config keys and must not be discovered by the core.
 
-## Frozen v1 boundary
+## Frozen versioned boundary
 
 The versioned request, artifact package, manifest, build record, durability
-request, publish request, and publish receipt are the public boundary. V1 has
-no plugin registry and no mid-pipeline callback API for private destinations.
-Provider-neutral callbacks already documented by the core remain explicit run
-options; they do not transfer stage ownership to a wrapper.
+request, publish request, and publish receipt are the public boundary. New
+publication work uses the immutable `explainer-kit.publish-request/v2` and
+`explainer-kit.publish-receipt/v2` contracts. The corresponding
+`publish-request/v1` and `publish-receipt/v1` contracts remain readable for
+replay; v2 is a new contract version, not an in-place mutation of v1. The
+extension seam has no plugin registry and no mid-pipeline callback API for
+private destinations. Provider-neutral callbacks already documented by the
+core remain explicit run options; they do not transfer stage ownership to a
+wrapper.
 
 V1 readers reject unsupported contract majors and identity mismatches rather
 than guessing. Wrappers should preserve unknown future versions for diagnosis,
@@ -59,13 +64,17 @@ or private content.
 
 After the core command returns, the wrapper performs its post-run publication
 and linking work. It retains the immutable core manifest as
-`private-wrapper-manifest.json`, the complete `PublishReceiptV1` as
+`private-wrapper-manifest.json`, the complete `publish-receipt/v2` as
 `private-wrapper-publish-receipt.json`, and its sanitized wrapper result as
 `private-wrapper-result.json`. The wrapper result repeats canonical hashes for
 the request, manifest, and post-run receipt.
 
 The wrapper acceptance stage reads those post-run files separately. It
-validates the closed receipt contract, every manifest artifact/hash and
-destination, the run-unique sentinel, the manifest hash, and the core run ID
-against `private-wrapper-execution.json`. Repeating a matching hash cannot make
-a foreign or stale receipt attributable to the packaged run.
+validates the closed receipt contract, complete manifest and catalog evidence,
+every source identity, path, artifact hash, destination, and verification fact,
+the run-unique sentinel, the manifest hash, and the core run ID against
+`private-wrapper-execution.json`. Public and protected v2 receipts must each
+provide exactly one entry for every finalized manifest artifact and exactly one
+generated catalog entry. A `publish-receipt/v1` remains consumable only for
+replay. Repeating a matching hash cannot make a foreign, duplicate, incomplete,
+or stale receipt attributable to the packaged run.

package/assets/skills/explainer-kit/references/visual-authoring.md

@@ -28,10 +28,30 @@ stands. Use one dominant title, a short framing statement, and the most useful
 visual or status summary before secondary detail. Keep headings descriptive,
 group related items, and use size, spacing, and contrast consistently.
 
+Assign intentional typography roles to the title, framing statement, section
+headings, labels, body copy, evidence, and annotations. Use weight, scale,
+measure, and contrast to clarify those roles rather than making every text block
+equally loud. Keep the role system consistent across artifacts without forcing
+every medium into the same composition.
+
 Use the shared terminology, status labels, and numbers exactly. Never create a
 shorter synonym that changes meaning. Keep source-backed uncertainty visible as
 `needs confirmation`.
 
+## Compose to the evidence
+
+Treat composition and density as editorial choices. Group facts that belong
+together, give the main claim enough emphasis, and let supporting evidence
+recede without becoming hard to find. Restructure crowded content instead of
+shrinking it, and remove decorative filler instead of stretching sparse
+material.
+
+Seek medium leverage: a visual artifact should make a relationship, comparison,
+sequence, or decision easier to understand than prose alone. Vary the treatment
+to fit the evidence and avoid template repetition across sections, cards, or
+slides. Shared visual language should create cross-artifact cohesion, not a set
+of cloned layouts.
+
 ## Hubs and responsive navigation
 
 - Lead with the project outcome and current state, then expose architecture,
@@ -45,6 +65,8 @@ shorter synonym that changes meaning. Keep source-backed uncertainty visible as
 
 ## Diagrams and system visuals
 
+- Preserve diagram semantics: topology, direction, ownership, state, and edge
+  meaning must survive the visual treatment.
 - Encode relationships with position and connectors, not color alone.
 - Label nodes with concrete nouns and edges with actions or data movement.
 - Make direction explicit and include a legend only when the encoding needs it.
@@ -58,6 +80,8 @@ shorter synonym that changes meaning. Keep source-backed uncertainty visible as
   attribute escaping, including `data-edge-label=""` for an unlabeled edge.
 - Give the canvas an accessible name and description. Keep labels readable at
   the required viewport widths and provide bounded pan or zoom for large maps.
+- Fit the frame to the content so the meaningful topology is prominent rather
+  than stranded in unused canvas.
 - Use the same component names and status vocabulary as the hub and deck.
 
 ## Decks

package/assets/skills/explainer-kit/references/visual-review.md

@@ -12,17 +12,30 @@ Inspect the complete set before assigning artifact findings. Verify:
 
 - **First viewport:** each artifact establishes purpose, project state, and the
   primary reader question without scrolling.
+- **Typography:** titles, framing text, headings, labels, body copy, and
+  annotations have distinct, readable roles that remain consistent across the
+  set.
 - **Hierarchy:** the most important outcome or relationship is dominant, with
   secondary detail grouped and ordered consistently.
-- **Representation choice:** the selected medium makes the evidence easier to
-  understand than plain prose would.
+- **Composition:** grouping, alignment, spacing, and emphasis create a clear
+  reading path suited to the artifact's evidence.
+- **Density:** crowded material is restructured instead of miniaturized, while
+  sparse material is not padded with decorative filler.
+- **Medium leverage:** the selected medium makes a relationship, comparison,
+  sequence, or decision easier to understand than plain prose would.
 - **Legibility:** text, labels, status cues, tables, and connectors remain
   readable at every required viewport.
 - **Medium fit:** the hub orients and links, the system visual preserves
   relationships, the deck paces a narrative, and optional artifacts add a
   distinct source-backed perspective.
-- **Cohesion:** terminology, status labels, numbers, color meaning, and visual
-  language match the shared ledger and one another.
+- **Template repetition:** sections, cards, and slides vary when the evidence
+  calls for a different treatment instead of repeating one shell mechanically.
+- **Diagram semantics:** topology, direction, labels, edge meaning, and
+  fit-to-content framing communicate the planned relationships without false
+  linearization or decorative ambiguity.
+- **Cross-artifact cohesion:** terminology, status labels, numbers, color
+  meaning, typographic roles, and visual language match the shared ledger and
+  one another.
 - **Coverage and redundancy:** planned sources and reader questions are covered
   once at the right depth; optional artifacts do not repeat the hub or deck
   without a justified purpose.
@@ -49,7 +62,8 @@ Use severity proportionally:
 Return exactly one provider-neutral disposition:
 
 - `pass` when the full set clears the rubric with no required correction.
-- `correct` when bounded artifact-scoped changes can clear the rubric.
+- `correct` when bounded artifact-scoped changes can clear the rubric; every
+  finding must name a concrete, actionable correction.
 - `fail` when evidence is missing, the plan or ledger is internally invalid, or
   correction would require unsupported facts or a different artifact set.
 

package/assets/skills/explainer-kit/schemas/author-request.v3.schema.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.author-request/v3",
+  "title": "AuthorRequestV3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "artifactId",
+    "artifactType",
+    "authoring",
+    "brief",
+    "visualAuthoringGuidance",
+    "factBase",
+    "theme",
+    "setContext",
+    "plannedArtifact",
+    "artifactLinks"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.author-request/v3" },
+    "artifactId": { "type": "string", "minLength": 1 },
+    "artifactType": {
+      "enum": ["hub", "diagram", "explainer", "deck", "catalog"]
+    },
+    "authoring": { "enum": ["markdown", "html"] },
+    "brief": { "type": "string", "minLength": 1 },
+    "visualAuthoringGuidance": { "type": "string", "minLength": 1 },
+    "factBase": { "$ref": "explainer-kit.fact-base/v1" },
+    "shell": { "type": "string", "minLength": 1 },
+    "theme": { "$ref": "explainer-kit.theme/v1" },
+    "setContext": { "$ref": "explainer-kit.set-plan/v1" },
+    "plannedArtifact": { "$ref": "#/$defs/plannedArtifact" },
+    "artifactLinks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artifactLink" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "graphSemantics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/graphSemantics" },
+      "minItems": 1
+    },
+    "floor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requiredNarrative"],
+      "properties": {
+        "requiredNarrative": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    }
+  },
+  "$defs": {
+    "artifactLink": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifactId", "artifactType", "sitePath", "href"],
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+        },
+        "artifactType": {
+          "enum": ["hub", "diagram", "explainer", "deck", "catalog"]
+        },
+        "sitePath": {
+          "type": "string",
+          "pattern": "^site/[a-z0-9._-]+(?:/[a-z0-9._-]+)*/index\\.html$"
+        },
+        "href": {
+          "type": "string",
+          "pattern": "^(?:index\\.html|(?:\\.\\./)*[a-z0-9._-]+(?:/[a-z0-9._-]+)*/index\\.html)$"
+        }
+      }
+    },
+    "graphSemantics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["direction", "nodes", "edges", "topology"],
+      "properties": {
+        "direction": { "enum": ["TD", "LR"] },
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label", "shape", "explicit"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]*$" },
+              "label": { "type": "string", "minLength": 1 },
+              "shape": { "enum": ["rectangle", "rounded", "diamond"] },
+              "explicit": { "type": "boolean" }
+            }
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "edges": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["from", "to", "kind", "label"],
+            "properties": {
+              "from": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "to": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]*$" },
+              "kind": { "enum": ["arrow", "line"] },
+              "label": { "type": "string" }
+            }
+          },
+          "minItems": 1
+        },
+        "topology": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "features",
+            "branchNodes",
+            "fanInNodes",
+            "cycle",
+            "order"
+          ],
+          "properties": {
+            "kind": { "const": "non-linear" },
+            "features": {
+              "type": "array",
+              "items": {
+                "enum": [
+                  "branch",
+                  "fan-in",
+                  "cycle",
+                  "disconnected",
+                  "non-linear"
+                ]
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "branchNodes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "uniqueItems": true
+            },
+            "fanInNodes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "uniqueItems": true
+            },
+            "cycle": { "type": "boolean" },
+            "order": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "maxItems": 0
+            }
+          }
+        }
+      }
+    },
+    "plannedArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "artifactId",
+        "artifactType",
+        "profileId",
+        "required",
+        "sourceIds",
+        "draft",
+        "visualIntent"
+      ],
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+        },
+        "artifactType": {
+          "enum": ["hub", "diagram", "explainer", "deck", "catalog"]
+        },
+        "profileId": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+        },
+        "required": { "type": "boolean" },
+        "sourceIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "draft": { "type": "string", "minLength": 1 },
+        "visualIntent": { "type": "string", "minLength": 1 },
+        "justification": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "sourceIds", "rationale"],
+          "properties": {
+            "kind": {
+              "enum": [
+                "status-change",
+                "rollout-complexity",
+                "source-backed-detail"
+              ]
+            },
+            "sourceIds": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "rationale": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  }
+}