@open-agent-toolkit/cli 0.2.30 → 0.2.32

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

package/assets/skills/explainer-kit/schemas/publish-receipt.v2.schema.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.publish-receipt/v2",
+  "title": "PublishReceiptV2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider",
+    "publishedAt",
+    "publicAccess",
+    "roots",
+    "sentinel",
+    "artifacts"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "explainer-kit.publish-receipt/v2"
+    },
+    "provider": {
+      "const": "s3-static"
+    },
+    "publishedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "publicAccess": {
+      "enum": ["public", "protected"]
+    },
+    "roots": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["s3Uri", "publicBaseUrl"],
+      "properties": {
+        "s3Uri": {
+          "type": "string",
+          "pattern": "^s3://[a-z0-9][a-z0-9.-]{1,61}[a-z0-9](?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?$"
+        },
+        "publicBaseUrl": {
+          "type": "string",
+          "pattern": "^https://[^\\s/?#@]+(?::[0-9]+)?(?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?$"
+        }
+      }
+    },
+    "sentinel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "relativePath",
+        "objectVerification",
+        "publicVerification",
+        "deleted"
+      ],
+      "properties": {
+        "relativePath": {
+          "$ref": "#/$defs/safeRelativePath"
+        },
+        "objectVerification": {
+          "$ref": "#/$defs/objectVerification"
+        },
+        "publicVerification": {
+          "$ref": "#/$defs/publicVerification"
+        },
+        "deleted": {
+          "type": "boolean"
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/artifact"
+      },
+      "uniqueItems": true
+    },
+    "publicRootPolicy": {
+      "description": "Present only when EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT was set and the public root was in fact a non-public address, so a publication made with the anti-SSRF control disabled is distinguishable in durable evidence.",
+      "enum": ["private-allowed"]
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "source": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "artifactId"],
+          "properties": {
+            "kind": {
+              "const": "manifest"
+            },
+            "artifactId": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "name"],
+          "properties": {
+            "kind": {
+              "const": "auxiliary"
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      ]
+    },
+    "objectVerification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "method", "hash"],
+      "properties": {
+        "status": {
+          "const": "verified"
+        },
+        "method": {
+          "enum": ["service-checksum", "authenticated-download"]
+        },
+        "hash": {
+          "$ref": "#/$defs/hash"
+        }
+      }
+    },
+    "publicVerification": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "httpStatus", "hash"],
+          "properties": {
+            "status": {
+              "const": "verified"
+            },
+            "httpStatus": {
+              "type": "integer",
+              "minimum": 200,
+              "maximum": 299
+            },
+            "hash": {
+              "$ref": "#/$defs/hash"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": {
+              "const": "skipped-protected"
+            }
+          }
+        }
+      ]
+    },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "relativePath",
+        "hash",
+        "s3Uri",
+        "publicUrl",
+        "contentType",
+        "objectVerification",
+        "publicVerification"
+      ],
+      "properties": {
+        "source": {
+          "$ref": "#/$defs/source"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/safeRelativePath"
+        },
+        "hash": {
+          "$ref": "#/$defs/hash"
+        },
+        "s3Uri": {
+          "type": "string",
+          "pattern": "^s3://[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]/[^\\s?#\\\\]+$"
+        },
+        "publicUrl": {
+          "type": "string",
+          "pattern": "^https://[^\\s/?#@]+(?::[0-9]+)?/[^\\s?#\\\\]+$"
+        },
+        "contentType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "objectVerification": {
+          "$ref": "#/$defs/objectVerification"
+        },
+        "publicVerification": {
+          "$ref": "#/$defs/publicVerification"
+        }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/publish-request.v2.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.publish-request/v2",
+  "title": "S3StaticPublishRequestV2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider",
+    "s3Uri",
+    "publicBaseUrl",
+    "awsRegion",
+    "publicAccess",
+    "siteRoot",
+    "manifestPath"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.publish-request/v2" },
+    "provider": { "const": "s3-static" },
+    "s3Uri": {
+      "type": "string",
+      "pattern": "^s3://[a-z0-9][a-z0-9.-]{1,61}[a-z0-9](?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?/?$"
+    },
+    "publicBaseUrl": {
+      "type": "string",
+      "pattern": "^https://[^\\s/?#@]+(?::[0-9]+)?(?:/[^\\s/?#\\\\]+(?:/[^\\s/?#\\\\]+)*)?/?$"
+    },
+    "awsRegion": { "type": "string", "minLength": 1 },
+    "awsProfile": { "type": "string", "minLength": 1 },
+    "publicAccess": { "enum": ["public", "protected"] },
+    "siteRoot": { "type": "string", "minLength": 1 },
+    "manifestPath": { "type": "string", "minLength": 1 }
+  }
+}

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

@@ -46,7 +46,10 @@
           "enum": ["none", "commit", "publish"]
         },
         "publish": {
-          "$ref": "explainer-kit.publish-request/v1"
+          "oneOf": [
+            { "$ref": "explainer-kit.publish-request/v1" },
+            { "$ref": "explainer-kit.publish-request/v2" }
+          ]
         }
       }
     },