@open-agent-toolkit/cli 0.2.5 → 0.2.7

package/assets/skills/explainer-kit/palettes/ember.json

@@ -0,0 +1,37 @@
+{
+  "name": "ember",
+  "modes": {
+    "light": {
+      "surface": {
+        "canvas": "#fffbeb",
+        "panel": "#fef3c7",
+        "elevated": "#fde68a"
+      },
+      "ink": { "primary": "#451a03", "muted": "#713f12", "inverse": "#ffffff" },
+      "accent": { "primary": "#9a3412", "secondary": "#92400e" },
+      "status": {
+        "success": "#166534",
+        "warning": "#854d0e",
+        "danger": "#991b1b",
+        "info": "#1e40af"
+      },
+      "diagramSeries": ["#9a3412", "#92400e", "#166534", "#1e40af"]
+    },
+    "dark": {
+      "surface": {
+        "canvas": "#431407",
+        "panel": "#7c2d12",
+        "elevated": "#78350f"
+      },
+      "ink": { "primary": "#fff7ed", "muted": "#fed7aa", "inverse": "#431407" },
+      "accent": { "primary": "#fdba74", "secondary": "#fcd34d" },
+      "status": {
+        "success": "#86efac",
+        "warning": "#fde047",
+        "danger": "#fca5a5",
+        "info": "#93c5fd"
+      },
+      "diagramSeries": ["#fdba74", "#fcd34d", "#86efac", "#93c5fd"]
+    }
+  }
+}

package/assets/skills/explainer-kit/palettes/forest.json

@@ -0,0 +1,37 @@
+{
+  "name": "forest",
+  "modes": {
+    "light": {
+      "surface": {
+        "canvas": "#f7fee7",
+        "panel": "#ecfccb",
+        "elevated": "#d9f99d"
+      },
+      "ink": { "primary": "#052e16", "muted": "#365314", "inverse": "#ffffff" },
+      "accent": { "primary": "#166534", "secondary": "#3f6212" },
+      "status": {
+        "success": "#166534",
+        "warning": "#854d0e",
+        "danger": "#991b1b",
+        "info": "#1e40af"
+      },
+      "diagramSeries": ["#166534", "#3f6212", "#854d0e", "#1e40af"]
+    },
+    "dark": {
+      "surface": {
+        "canvas": "#052e16",
+        "panel": "#14532d",
+        "elevated": "#365314"
+      },
+      "ink": { "primary": "#f7fee7", "muted": "#d9f99d", "inverse": "#052e16" },
+      "accent": { "primary": "#86efac", "secondary": "#bef264" },
+      "status": {
+        "success": "#86efac",
+        "warning": "#fde047",
+        "danger": "#fca5a5",
+        "info": "#93c5fd"
+      },
+      "diagramSeries": ["#86efac", "#bef264", "#fde047", "#93c5fd"]
+    }
+  }
+}

package/assets/skills/explainer-kit/palettes/neutral.json

@@ -0,0 +1,37 @@
+{
+  "name": "neutral",
+  "modes": {
+    "light": {
+      "surface": {
+        "canvas": "#ffffff",
+        "panel": "#f3f4f6",
+        "elevated": "#e5e7eb"
+      },
+      "ink": { "primary": "#111827", "muted": "#4b5563", "inverse": "#ffffff" },
+      "accent": { "primary": "#374151", "secondary": "#4b5563" },
+      "status": {
+        "success": "#166534",
+        "warning": "#854d0e",
+        "danger": "#991b1b",
+        "info": "#1e40af"
+      },
+      "diagramSeries": ["#374151", "#1e40af", "#166534", "#854d0e"]
+    },
+    "dark": {
+      "surface": {
+        "canvas": "#111827",
+        "panel": "#1f2937",
+        "elevated": "#374151"
+      },
+      "ink": { "primary": "#f9fafb", "muted": "#d1d5db", "inverse": "#111827" },
+      "accent": { "primary": "#d1d5db", "secondary": "#e5e7eb" },
+      "status": {
+        "success": "#86efac",
+        "warning": "#fde047",
+        "danger": "#fca5a5",
+        "info": "#93c5fd"
+      },
+      "diagramSeries": ["#d1d5db", "#93c5fd", "#86efac", "#fde047"]
+    }
+  }
+}

package/assets/skills/explainer-kit/palettes/ocean.json

@@ -0,0 +1,37 @@
+{
+  "name": "ocean",
+  "modes": {
+    "light": {
+      "surface": {
+        "canvas": "#f8fafc",
+        "panel": "#e2e8f0",
+        "elevated": "#cbd5e1"
+      },
+      "ink": { "primary": "#0f172a", "muted": "#334155", "inverse": "#ffffff" },
+      "accent": { "primary": "#075985", "secondary": "#155e75" },
+      "status": {
+        "success": "#166534",
+        "warning": "#854d0e",
+        "danger": "#991b1b",
+        "info": "#075985"
+      },
+      "diagramSeries": ["#075985", "#155e75", "#166534", "#854d0e"]
+    },
+    "dark": {
+      "surface": {
+        "canvas": "#082f49",
+        "panel": "#0c4a6e",
+        "elevated": "#164e63"
+      },
+      "ink": { "primary": "#f0f9ff", "muted": "#bae6fd", "inverse": "#082f49" },
+      "accent": { "primary": "#7dd3fc", "secondary": "#67e8f9" },
+      "status": {
+        "success": "#86efac",
+        "warning": "#fde047",
+        "danger": "#fca5a5",
+        "info": "#bae6fd"
+      },
+      "diagramSeries": ["#7dd3fc", "#67e8f9", "#86efac", "#fde047"]
+    }
+  }
+}

package/assets/skills/explainer-kit/palettes/violet.json

@@ -0,0 +1,37 @@
+{
+  "name": "violet",
+  "modes": {
+    "light": {
+      "surface": {
+        "canvas": "#faf5ff",
+        "panel": "#f3e8ff",
+        "elevated": "#e9d5ff"
+      },
+      "ink": { "primary": "#2e1065", "muted": "#581c87", "inverse": "#ffffff" },
+      "accent": { "primary": "#6b21a8", "secondary": "#5b21b6" },
+      "status": {
+        "success": "#166534",
+        "warning": "#854d0e",
+        "danger": "#991b1b",
+        "info": "#1e40af"
+      },
+      "diagramSeries": ["#6b21a8", "#5b21b6", "#166534", "#854d0e"]
+    },
+    "dark": {
+      "surface": {
+        "canvas": "#2e1065",
+        "panel": "#4c1d95",
+        "elevated": "#581c87"
+      },
+      "ink": { "primary": "#faf5ff", "muted": "#e9d5ff", "inverse": "#2e1065" },
+      "accent": { "primary": "#d8b4fe", "secondary": "#c4b5fd" },
+      "status": {
+        "success": "#86efac",
+        "warning": "#fde047",
+        "danger": "#fca5a5",
+        "info": "#93c5fd"
+      },
+      "diagramSeries": ["#d8b4fe", "#c4b5fd", "#86efac", "#fde047"]
+    }
+  }
+}

package/assets/skills/explainer-kit/profiles/clean.json

@@ -0,0 +1,42 @@
+{
+  "name": "clean",
+  "typography": {
+    "sans": ["system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+    "serif": ["ui-serif", "Georgia", "serif"],
+    "mono": ["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+    "scale": {
+      "caption": "0.875rem",
+      "body": "1rem",
+      "title": "1.5rem",
+      "display": "2.25rem"
+    },
+    "lineHeight": { "caption": 1.4, "body": 1.6, "title": 1.25, "display": 1.1 }
+  },
+  "spacing": {
+    "unit": 4,
+    "scale": { "xs": 4, "sm": 8, "md": 16, "lg": 24, "xl": 40 }
+  },
+  "geometry": { "radius": { "sm": 4, "md": 8, "lg": 12 }, "borderWidth": 1 },
+  "elevation": {
+    "shadows": {
+      "low": "0 1px 2px rgb(0 0 0 / 0.08)",
+      "high": "0 12px 28px rgb(0 0 0 / 0.16)"
+    }
+  },
+  "density": "comfortable",
+  "motion": {
+    "enabled": true,
+    "durationMs": { "fast": 120, "normal": 200, "slow": 320 },
+    "easing": {
+      "standard": "ease",
+      "emphasized": "cubic-bezier(0.2, 0, 0, 1)"
+    },
+    "reducedMotion": "disable-nonessential"
+  },
+  "diagrams": {
+    "lineWidth": 2,
+    "nodeGap": 32,
+    "arrowStyle": "straight",
+    "labelTreatment": "boxed"
+  }
+}

package/assets/skills/explainer-kit/profiles/editorial.json

@@ -0,0 +1,42 @@
+{
+  "name": "editorial",
+  "typography": {
+    "sans": ["system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+    "serif": ["Charter", "Bitstream Charter", "Georgia", "serif"],
+    "mono": ["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+    "scale": {
+      "caption": "0.875rem",
+      "body": "1.0625rem",
+      "title": "1.75rem",
+      "display": "2.75rem"
+    },
+    "lineHeight": { "caption": 1.5, "body": 1.7, "title": 1.2, "display": 1.05 }
+  },
+  "spacing": {
+    "unit": 5,
+    "scale": { "xs": 5, "sm": 10, "md": 20, "lg": 30, "xl": 50 }
+  },
+  "geometry": { "radius": { "sm": 2, "md": 4, "lg": 8 }, "borderWidth": 1 },
+  "elevation": {
+    "shadows": {
+      "low": "0 1px 3px rgb(0 0 0 / 0.1)",
+      "high": "0 16px 36px rgb(0 0 0 / 0.18)"
+    }
+  },
+  "density": "spacious",
+  "motion": {
+    "enabled": true,
+    "durationMs": { "fast": 150, "normal": 240, "slow": 400 },
+    "easing": {
+      "standard": "ease-out",
+      "emphasized": "cubic-bezier(0.16, 1, 0.3, 1)"
+    },
+    "reducedMotion": "disable-nonessential"
+  },
+  "diagrams": {
+    "lineWidth": 1.5,
+    "nodeGap": 40,
+    "arrowStyle": "curved",
+    "labelTreatment": "inline"
+  }
+}

package/assets/skills/explainer-kit/profiles/technical.json

@@ -0,0 +1,39 @@
+{
+  "name": "technical",
+  "typography": {
+    "sans": ["system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+    "serif": ["ui-serif", "Georgia", "serif"],
+    "mono": ["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+    "scale": {
+      "caption": "0.8125rem",
+      "body": "0.9375rem",
+      "title": "1.375rem",
+      "display": "2rem"
+    },
+    "lineHeight": { "caption": 1.35, "body": 1.5, "title": 1.2, "display": 1.1 }
+  },
+  "spacing": {
+    "unit": 3,
+    "scale": { "xs": 3, "sm": 6, "md": 12, "lg": 18, "xl": 30 }
+  },
+  "geometry": { "radius": { "sm": 2, "md": 4, "lg": 6 }, "borderWidth": 1 },
+  "elevation": {
+    "shadows": {
+      "low": "0 1px 2px rgb(0 0 0 / 0.12)",
+      "high": "0 8px 20px rgb(0 0 0 / 0.2)"
+    }
+  },
+  "density": "compact",
+  "motion": {
+    "enabled": false,
+    "durationMs": { "fast": 0, "normal": 0, "slow": 0 },
+    "easing": { "standard": "linear", "emphasized": "linear" },
+    "reducedMotion": "disable-nonessential"
+  },
+  "diagrams": {
+    "lineWidth": 2,
+    "nodeGap": 24,
+    "arrowStyle": "straight",
+    "labelTreatment": "boxed"
+  }
+}

package/assets/skills/explainer-kit/recipes/engineer-tour.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "explainer-kit.recipe/v1",
+  "id": "engineer-tour",
+  "version": "1",
+  "sourceRoles": [
+    {
+      "role": "codebase",
+      "required": true,
+      "accepts": ["directory", "git"],
+      "minBindings": 1,
+      "maxBindings": 1
+    }
+  ],
+  "requiredNarrative": [
+    "orientation",
+    "architecture",
+    "execution-flow",
+    "key-code",
+    "validation"
+  ],
+  "artifacts": [
+    {
+      "id": "engineer-tour",
+      "type": "explainer",
+      "template": "engineer-tour",
+      "required": true
+    }
+  ],
+  "discoveryLimits": {
+    "consecutiveNoNewFindingsRounds": 2,
+    "maxRounds": 8
+  }
+}

package/assets/skills/explainer-kit/recipes/project-explainer.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "explainer-kit.recipe/v1",
+  "id": "project-explainer",
+  "version": "1",
+  "sourceRoles": [
+    {
+      "role": "project",
+      "required": true,
+      "accepts": ["file", "directory", "git", "github"],
+      "minBindings": 1,
+      "maxBindings": 1
+    }
+  ],
+  "requiredNarrative": [
+    "planned-architecture",
+    "decisions",
+    "risks",
+    "phases",
+    "validation-approach"
+  ],
+  "artifacts": [
+    {
+      "id": "project-explainer",
+      "type": "hub",
+      "template": "house-style",
+      "required": true
+    }
+  ],
+  "discoveryLimits": {
+    "consecutiveNoNewFindingsRounds": 2,
+    "maxRounds": 8
+  }
+}

package/assets/skills/explainer-kit/recipes/project-recap.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "explainer-kit.recipe/v1",
+  "id": "project-recap",
+  "version": "1",
+  "sourceRoles": [
+    {
+      "role": "project",
+      "required": true,
+      "accepts": ["file", "directory", "git", "github"],
+      "minBindings": 1,
+      "maxBindings": 1
+    }
+  ],
+  "requiredNarrative": [
+    "original-request",
+    "key-agent-decisions",
+    "as-built-architecture",
+    "implementation-record",
+    "validation-evidence",
+    "outcome"
+  ],
+  "artifacts": [
+    {
+      "id": "project-recap",
+      "type": "hub",
+      "template": "house-style",
+      "required": true
+    }
+  ],
+  "discoveryLimits": {
+    "consecutiveNoNewFindingsRounds": 2,
+    "maxRounds": 8
+  }
+}

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

@@ -0,0 +1,101 @@
+# Core run contract
+
+`scripts/run.mjs` is the config-blind orchestration entry point. It reads only
+the explicit `ExplainerRunRequestV1`, bundled skill assets, and source paths
+named by that request. It does not search for `.oat`, user configuration,
+provider configuration, vaults, or destinations.
+
+## Invocation
+
+Programmatic callers import `runExplainer(request, options)`. Command-line
+callers use:
+
+```bash
+node scripts/run.mjs --request request.json
+```
+
+Federated runs require a provider-neutral critic callback. A command-line
+caller supplies one with `--critic-module critic.mjs`; the module exports
+`critic(request)` or a default function. The callback receives reconciled
+claims, sources, overrides, and the freshness policy. It returns:
+
+```json
+{
+  "criticId": "skeptical-pass",
+  "executedAt": "2026-07-17T20:00:00Z",
+  "findings": []
+}
+```
+
+No provider name, command, credential, or dispatch protocol is part of this
+contract.
+
+## Explicit source forms
+
+- `factBase.mode: supplied` points to a valid `FactBaseV1` JSON file. The core
+  performs only the lightweight consistency and freshness check and never
+  invokes the critic.
+- `factBase.mode: federated` names explicit source bindings. File locators
+  contain JSON with a `claims` array of `{ "id", "text", "locator"? }`.
+  Non-file bindings require a caller-supplied `sourceLoader(source)` callback.
+  Every binding names its recipe `role` and `sourceSetId`. Multiple documents
+  may share one source-set ID; recipe cardinality counts distinct sets, not
+  documents. The core validates these bindings before loading facts, then
+  reconciles the loaded claims and invokes the critic exactly once.
+
+An unattended request asserts that its explicit source artifacts are already
+approved. It does not prompt. Interactive review and same-run approval/resume
+are introduced separately and are not part of this contract.
+
+## Pipeline and retained package
+
+The core executes:
+
+1. validate request and recipe
+2. reconcile or check the fact base
+3. apply bounded discovery and create recipe content
+4. resolve one theme
+5. render typed artifacts
+6. run structural and optional browser QA
+7. write the manifest and build record
+
+The run package retains `source/fact-base.json`, `source/fact-base.md`,
+`source/content/*.md`, `theme.resolved.json`, rendered `site/` files,
+`manifest.json`, and `build-record.json` as far as each stage succeeds. A stage
+failure records a structured error and recovery action without deleting earlier
+outputs. Raw art direction is omitted unless the request explicitly opts in.
+
+When a caller supplies `discover({ round, recipe, factBase })`, the callback
+returns the findings added in that round. The core stops after two consecutive
+empty rounds and always stops at the recipe's `maxRounds`.
+
+## Optional seams
+
+Durability and publishing are never implicit.
+
+- `durability.strategy: none` invokes neither seam.
+- `durability.strategy: commit` invokes the explicit `durability` callback.
+  Caller-created commit evidence is subsequently verified with
+  `record-durability.mjs`; the core never creates commits. The first evidence
+  commit must contain every path and byte hash in `manifest.immutableHashes`:
+  fact-base JSON and Markdown, all content Markdown, the resolved theme, and
+  every built artifact retained in the package. Mutable `manifest.json` and
+  `build-record.json` remain excluded for the separate evidence update.
+- `durability.strategy: publish` invokes the explicit `publish` callback with
+  the complete publish request. A verified receipt is subsequently recorded as
+  durability evidence.
+
+CLI callers provide these callbacks only with `--durability-module` and
+`--publish-module`. Building remains `built-not-durable` until evidence is
+verified. Publishing remains independently human-gated by the caller.
+
+## Result
+
+`runExplainer` returns the run root, manifest path, build-record path, outcome,
+warnings, and bounded-discovery summary. Input validation and unsupported
+recipes reject before output mutation. Failures after initialization return a
+`failed` result with paths to the retained record and intermediates.
+
+V1 readers reject unknown schema majors and unknown contract fields. Relative
+record paths are run-root confined, hashes use `sha256:<hex>`, and command
+metadata uses argv arrays rather than shell strings.

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

@@ -0,0 +1,94 @@
+# S3 static destination contract
+
+The `s3-static` connector publishes only files declared as built artifacts in a
+validated manifest. Publishing is human-gated:
+
+```bash
+node scripts/publish.mjs \
+  --request /path/to/publish-request.json \
+  --receipt /path/to/publish-receipt.json \
+  --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`.
+
+For example:
+
+| Input                   | Value                                                           |
+| ----------------------- | --------------------------------------------------------------- |
+| `siteRoot`              | `/tmp/run/site`                                                 |
+| manifest `renderedPath` | `site/initiatives/demo/index.html`                              |
+| `s3Uri`                 | `s3://example-bucket/published`                                 |
+| `publicBaseUrl`         | `https://cdn.example.com/published`                             |
+| object                  | `s3://example-bucket/published/initiatives/demo/index.html`     |
+| 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.
+
+## Safety and ordering
+
+The connector validates the request, manifest, paths, hashes, and duplicate
+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;
+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`.
+
+If public sentinel verification fails, no artifact is uploaded. The connector
+attempts sentinel cleanup and emits no successful receipt.
+
+Publishing is additive. The implementation uses individual `put-object`,
+`head-object`, and sentinel-only `delete-object` operations. It never performs
+root-wide synchronization, never passes a delete flag, never walks or uploads
+undeclared files, and never deletes an artifact object. Existing declared
+objects with matching hash and metadata are skipped; changed declared objects
+may be replaced.
+
+## Metadata
+
+Every upload sets metadata explicitly:
+
+| File    | Content type                                      |
+| ------- | ------------------------------------------------- |
+| `.html` | `text/html; charset=utf-8`                        |
+| `.json` | `application/json`                                |
+| `.css`  | `text/css; charset=utf-8`                         |
+| `.js`   | `text/javascript; charset=utf-8`                  |
+| `.svg`  | `image/svg+xml`                                   |
+| `.txt`  | `text/plain; charset=utf-8`                       |
+| 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.
+
+## Failures and retries
+
+Authentication and permission failures stop immediately. The connector does
+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.
+
+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.