@open-agent-toolkit/cli 0.2.30 → 0.2.31

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.

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.