@open-agent-toolkit/cli 0.2.26 → 0.2.27

package/assets/NOTICES.md

@@ -0,0 +1,156 @@
+# NOTICES
+
+This file records attribution for externally-sourced prose incorporated
+into this repository. When you adapt or lift prose from an external
+project into a skill, template, or doc, add an entry here — do not
+add attribution footers to the skill files themselves.
+
+## Obra Superpowers
+
+**Source:** https://github.com/obra/superpowers
+**License:** MIT
+**Version referenced:** 5.0.7
+
+### `brainstorming` skill
+
+Source file: `skills/brainstorming/SKILL.md`
+
+Passages adapted or lifted verbatim into OAT:
+
+- "Exploring approaches" (4 lines) — used in `oat-project-design` Component 3.5 (approach reaffirmation)
+- "Presenting the design" (5 lines) — used in `oat-project-design` Component 4 (section iterator)
+- "Design for isolation and clarity" (4 lines) — used as a principle in `oat-project-design`
+- Self-review four-check template — used in `oat-project-design` Component 6
+- User-review gate phrasing — used in `oat-project-design` Component 7
+
+Consumer OAT skills: `oat-project-design`, `oat-project-quick-start`
+(via lightweight-design mode choice inheriting the same prose).
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+### `brainstorming` skill — visual companion
+
+Source files: `skills/brainstorming/scripts/{server.cjs, start-server.sh,
+  stop-server.sh, frame-template.html, helper.js}` and
+`skills/brainstorming/visual-companion.md`.
+
+Files lifted into OAT (under `.agents/skills/oat-brainstorm/`):
+
+- `scripts/server.cjs`, `scripts/stop-server.sh`, `scripts/frame-template.html`,
+  `scripts/helper.js` — verbatim from upstream.
+- `scripts/start-server.sh` — verbatim except for default persistence-path
+  changes (`.superpowers/brainstorm/` → OAT-managed prefixes:
+  `<project>/.oat/brainstorm/`, `<repo-root>/.oat/brainstorm/`,
+  `~/.oat/brainstorm/`).
+- `references/visual-companion.md` — adapted prose: persistence paths and
+  example invocations updated to OAT conventions.
+
+Consumer OAT skills: `oat-brainstorm`.
+
+## shadcn/improve
+
+**Source:** https://github.com/shadcn/improve/tree/main/skills/improve
+**License:** MIT
+**Version referenced:** `main` (retrieved 2026-07-12)
+
+### `improve` skill
+
+Source files: `skills/improve/SKILL.md` and
+`skills/improve/references/{audit-playbook.md,closing-the-loop.md,plan-template.md}`.
+
+Files copied into `.agents/skills/oat-repo-improve/`; the skill identifier,
+heading, invocation examples, and generated-plan attribution were renamed for
+the OAT repository namespace.
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2026 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## visual-explainer
+
+**Source:** https://github.com/nicobailon/visual-explainer
+**License:** MIT
+**Version referenced:** 0.8.1
+
+### Explainer templates and render QA
+
+Visual presentation and QA patterns were adapted into
+`.agents/skills/explainer-kit/`, including self-contained HTML shells,
+responsive navigation, slide-deck interaction and print behavior, overflow
+containment, reduced-motion handling, and structural/render checks.
+
+The OAT implementation replaces upstream branding, destinations, invocation
+commands, and example content with destination-neutral contracts, themes,
+templates, and fixtures. Consumer OAT skill: `explainer-kit`.
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2025 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/assets/docs/contributing/explainer-kit-verification.md

@@ -0,0 +1,125 @@
+---
+title: Verifying Explainer Kit
+description: 'Maintainer runbook for semantic golden cases, temporary real-Chromium evidence, and release validation.'
+---
+
+# Verifying Explainer Kit
+
+Explainer Kit uses portable behavioral goldens and a real-browser release gate.
+The goal is not pixel identity: output may change markup, spacing, and
+composition when it preserves the same meaning, topology, interactions, and
+evidence quality.
+
+## Golden cases
+
+The suite under
+`.agents/skills/explainer-kit/tests/fixtures/golden/` contains three
+portable semantic cases:
+
+| Case                           | What it proves                                             |
+| ------------------------------ | ---------------------------------------------------------- |
+| `simple`                       | Viewport-sized lead evidence and a cohesive baseline recap |
+| `non-linear`                   | Exact branch, fan-in, and cycle preservation               |
+| `explainer-authoring-redesign` | Archive-only rebuild from a dense completed project record |
+
+Every case retains only its descriptor, source input, and content-addressed
+source record. The three cases share one rubric. Generated artifacts, browser
+evidence, screenshots, manifests, catalogs, and review results stay in a
+temporary test directory and are never committed. Paths are
+repository-relative; machine roots, home-relative paths, `file://` URLs,
+Windows drive paths, and UNC paths are rejected.
+
+## Prerequisites
+
+- Install workspace dependencies.
+- Ensure the repository-supported Chromium runtime is installed and launchable.
+- Run from the repository root.
+
+The end-to-end benchmarks require an actual launched Chromium session. A
+deterministic fixture session is valid only for bounded unit/integration tests
+and cannot satisfy a golden production path.
+
+## Run the golden suite
+
+```bash
+node --test \
+  .agents/skills/explainer-kit/tests/golden-conformance.test.mjs
+```
+
+A passing run proves:
+
+- one planner-owned hub, architecture view, and deck;
+- source and terminology cohesion;
+- exact topology and catalog parity;
+- mobile, tablet, and desktop Chromium evidence;
+- one independent critic invocation; and
+- a passing terminal review without correction.
+
+The focused integration suites below separately exercise the one-correction
+ceiling.
+
+The suite recomputes semantic-input hashes, grounds every claim in retained
+source evidence, and evaluates the shared rubric against live runtime output.
+A prose claim or status label without runtime proof does not pass.
+
+## Inspect generated evidence
+
+The suite materializes each case's runtime package under its temporary working
+directory, validates it, and removes it at test completion. Add a local
+debugger breakpoint or temporarily disable cleanup when diagnosing a failure;
+do not add generated runtime output to the fixture directories.
+
+## Focused integrity suites
+
+Use these when changing browser identity, immutable evidence, resume, or archive
+contracts:
+
+```bash
+node --test \
+  .agents/skills/explainer-kit/tests/records.test.mjs \
+  .agents/skills/explainer-kit/tests/run.integration.test.mjs
+
+node --test \
+  .agents/skills/explainer-kit/tests/browser-runtime.test.mjs \
+  .agents/skills/explainer-kit/tests/qa.test.mjs \
+  .agents/skills/explainer-kit/tests/contracts.test.mjs \
+  .agents/skills/explainer-kit/tests/durability.test.mjs \
+  .agents/skills/explainer-kit/tests/rebuildability.test.mjs
+
+pnpm --filter @open-agent-toolkit/cli exec vitest run \
+  src/commands/project/archive/archive-utils.test.ts \
+  src/release/public-package-contract.test.ts
+
+node --test tools/smoke/explainer-kit/*.test.mjs
+```
+
+## Release gate
+
+The required publishable-package gate is:
+
+```bash
+pnpm release:validate
+```
+
+It validates all five lockstep public package tarballs and then runs the bounded
+curated-style/template matrix in real Chromium. The visual gate retains 65
+machine-readable viewport, clipping, motion, keyboard, no-JavaScript, and print
+measurements. Missing Chromium or untrusted retained evidence fails closed.
+
+For the full repository closeout, also run the standard checks documented in
+the root `AGENTS.md`:
+
+```bash
+pnpm check
+pnpm type-check
+pnpm test
+pnpm build
+pnpm lint
+pnpm format
+pnpm build:docs
+git diff --check
+```
+
+Do not treat an isolated transient timeout as a product pass or failure without
+reproducing the failing test. Preserve the exact-head successful rerun evidence
+used for release closure.

package/assets/docs/contributing/index.md

@@ -17,4 +17,5 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Commit Conventions](commit-conventions.md) - Traceable commit patterns for project and docs work.
 - [Hooks and Safety](hooks-and-safety.md) - Safety and mutation contracts for provider-sync behavior.
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
+- [Verifying Explainer Kit](explainer-kit-verification.md) - Golden recap cases, real-Chromium evidence, fixture regeneration, and release validation.
 - [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.

package/assets/docs/reference/troubleshooting.md

@@ -113,9 +113,56 @@ oat tools has <pack> --scope user
 - Reconcile `state.md`, `plan.md` review table, and `implementation.md`.
 - Ensure phase/review status has been updated after reviews and fix cycles.
 
+## An Explainer Kit recap ends as `built-needs-review`
+
+`built-needs-review` means the required unattended visual-review chain did not
+reach a valid `pass`. The run retains available output for diagnosis, but OAT
+will not finalize, archive, attest, publish, or push it as a successful recap.
+Do not bypass the review gate by copying the package into a durable location.
+
+Inspect:
+
+1. `build-record.json` and `manifest.json` for the terminal outcome and warning.
+2. `qa/browser/` for all required mobile, tablet, and desktop PNG/metrics pairs.
+3. `qa/visual-review/attempt-*/request.json` and `result.json` for request
+   binding, critic disposition, and findings.
+4. `qa/visual-review/revision.json` when a correction was requested.
+5. Adapter logs for missing or invalid `browserSession`, `visualCritic`, or
+   correction-provider modules.
+
+Common causes include unavailable Chromium, a fixture or unbranded session,
+missing screenshots, invalid decoded PNG dimensions, runtime/capture identity
+drift, critic exceptions, evidence mutation, `fail`, and an unresolved
+correction. Fix the provider or artifact problem and rebuild the recap; partial
+evidence is diagnostic only.
+
+See
+[Explainer Provider Integration](../workflows/skills/explainer-kit-providers.md)
+for the trusted-session and critic contracts.
+
+## Explainer Kit resume fails with `E_APPROVAL_RESUME`
+
+Interactive resume is same-request only. Keep the opaque `ekrt2` token returned
+as `approval.resumeToken` outside the package and provide it as
+`reviewedSource.resumeToken` with the complete original request.
+
+The error is expected when:
+
+- the token is missing, malformed, or not `ekrt2`;
+- the configured output root or retained run root moved;
+- `run-request.json` or a retained set-plan record changed;
+- the current request differs in source binding, recipe, mode, theme, render
+  strategy, privacy, public URL, durability, or publish destination; or
+- the package contains a legacy `ekrt1` token.
+
+Do not edit retained files or weaken the current request to force a match.
+Restore the exact original request and package bytes. Legacy paused runs cannot
+be upgraded in place; restart them to receive an authenticated `ekrt2` token.
+
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/implementation.md`
 - `.oat/projects/<scope>/<project>/reviews/`
+- `.oat/projects/<scope>/<project>/explainers/<slug>/qa/`
 - `packages/cli/src/commands/doctor/index.ts`
 - `packages/cli/src/commands/instructions/`

package/assets/docs/workflows/projects/artifacts.md

@@ -57,12 +57,30 @@ The archive exports at most one selected recap package. It preserves structured
 failure outcomes and successful intermediates, rejects an existing dated
 destination, and requires the selected path to stay under the project's
 `explainers/` directory with a `project-recap` manifest. Verification covers
-the exact retained bytes for the privacy-safe request, content approval, fact
-base JSON and Markdown, declared author results, authored content, resolved
-theme, and every built artifact. Canonical fact-base and theme hashes remain
-normalized-object identities; `manifest.immutableHashes` independently covers
-serialized file bytes. Missing, stale, or tampered coverage fails before the
-active project is deleted.
+the complete mode-aware package:
+
+- privacy-safe request and content approval;
+- fact-base JSON and Markdown;
+- the five immutable set-plan records and authored drafts;
+- declared author results and authored content;
+- resolved theme and every built artifact;
+- canonical mobile, tablet, and desktop screenshots;
+- paired `browser-evidence/v2` metrics with launched Chromium name, version,
+  and capture identity;
+- cohesion observations and each visual-review request/result; and
+- the bounded revision record when a correction occurred.
+
+Canonical object hashes identify normalized fact-base, theme, runtime, and
+capture objects; `manifest.immutableHashes` independently covers serialized file
+bytes. The archive requires one complete, internally consistent browser and
+review chain for a successful unattended recap. Missing, stale, forged,
+cross-record-mismatched, or tampered coverage fails before the active project is
+deleted.
+
+`built-needs-review` is a terminal review-gate outcome, not a non-durable
+success. Its partial evidence remains available for diagnosis, but it cannot be
+finalized, exported, attested, archived, or pushed. Review and rebuild the recap
+to a passing visual-review outcome first.
 
 Local-scope projects are not archived through this export path. Their explainer
 packages inherit the local project's untracked posture and remain

package/assets/docs/workflows/skills/explainer-kit-providers.md

@@ -0,0 +1,144 @@
+---
+title: Explainer Provider Integration
+description: 'Provider-neutral planner, author, browser-session, and visual-critic contracts for Explainer Kit integrators.'
+---
+
+# Explainer Provider Integration
+
+Explainer Kit keeps model and browser providers outside its retained request
+contracts. Integrators supply executable seams in process or through validated
+module exports; the core owns schemas, evidence binding, and terminal outcomes.
+
+For recipes, authoring behavior, themes, and lifecycle policy, start with
+[Explainer Kit](explainer-kit.md).
+
+## Provider boundaries
+
+Use exactly one form for each required role:
+
+| Role               | Direct input     | Module-path input          | Required export                     |
+| ------------------ | ---------------- | -------------------------- | ----------------------------------- |
+| Set planning       | `planSet`        | `planSetModulePath`        | `planSet` function                  |
+| Artifact authoring | `author`         | `authorModulePath`         | `author` function                   |
+| Browser evidence   | `browserSession` | `browserSessionModulePath` | branded `browserSession` descriptor |
+| Whole-set review   | `visualCritic`   | `visualCriticModulePath`   | `visualCritic` function             |
+
+`project-recap` requires all four roles. Other recipes require the author and
+use their recipe-specific planning behavior. Direct-plus-module conflicts,
+missing files, and invalid exports fail at the adapter boundary before core
+execution.
+
+Do not place browser or visual-review providers in `coreOptions`. Executable
+callbacks, descriptors, and module paths are transient and never enter
+`ExplainerRunRequestV1`, `run-request.json`, or immutable package hashes.
+
+## Set planner
+
+The provider-neutral `planSet` callback runs once after fact reconciliation and
+before any author callback. It returns the complete portfolio and one shared
+claim ledger.
+
+For a project recap, the portfolio must contain the required hub, architecture
+view, and deck. Optional entries must use a recipe-licensed profile, remain
+inside recipe and per-profile limits, and carry source-backed justification.
+Duplicate identities, undeclared sources, conflicting shared terms, and
+unjustified optionals fail validation.
+
+Every author request receives the immutable set context and its matching planned
+artifact. Authors cannot add, remove, replace, or rename portfolio entries.
+
+## Artifact author
+
+The core invokes `author` once per planned artifact with
+`explainer-kit.author-request/v2`. The request contains:
+
+- artifact identity, type, and authoring path;
+- the versioned brief and bundled medium-specific guidance;
+- reconciled facts and the shared set context;
+- the matching planned artifact;
+- the resolved theme; and
+- the bundled shell for artistic HTML.
+
+Return `explainer-kit.author-result/v2` with exactly one of
+`content.markdown` or `content.html` and non-secret provenance. The core
+validates source overlap, path ownership, script identity, and structural
+contracts after the callback returns.
+
+The author, fact critic, browser probe, and visual critic must have distinct
+callback identities. One provider implementation may back multiple roles, but
+the adapter still requires separate executable boundaries.
+
+## Trusted browser session
+
+Create a direct session with the compatible core:
+
+```js
+const browserSession = await core.createBrowserProbeSession();
+
+try {
+  await runOatExplainer(request, {
+    planSet,
+    author,
+    browserSession,
+    visualCritic,
+  });
+} finally {
+  await browserSession.close();
+}
+```
+
+The factory launches Chromium and derives the runtime name and version from the
+actual browser instance. A private in-memory brand prevents a plain object with
+caller-authored `{name, version}` metadata from impersonating a trusted
+session. Module providers export the already branded descriptor as
+`browserSession`, not a bare callback.
+
+For unattended project recaps, the core chooses 320, 768, and 1440 widths and
+requires default-scenario PNGs. It validates the PNG signature, decoded
+dimensions, and pixel payload, then writes paired
+`explainer-kit.browser-evidence/v2` metrics. Every record retains:
+
+- launched Chromium name and version;
+- fixed capture settings;
+- one derived capture identity;
+- viewport and scenario;
+- screenshot path and byte binding; and
+- measured overflow, clipping, readability, motion, keyboard, deck, and theme
+  behavior.
+
+All records in one review chain must carry the same runtime and capture
+identity. Deterministic fixture sessions are explicit test helpers and are
+rejected by unattended production recap paths.
+
+## Whole-set visual critic
+
+The `visualCritic` receives one
+`explainer-kit.visual-review-request/v1` plus a confined evidence reader. The
+request binds:
+
+- every rendered artifact and its exact content hash;
+- every viewport-matched screenshot and metrics hash;
+- cohesion observations from the shared ledger; and
+- the trusted browser runtime and capture identity.
+
+Return `explainer-kit.visual-review-result/v1` with the exact request identity,
+all reviewed artifact IDs, structured findings, and one disposition:
+
+- `pass` completes the review gate;
+- `correct` requests one bounded correction and one final review; or
+- `fail` terminates the gate.
+
+The critic must not mutate rendered files or evidence. The core revalidates all
+bound bytes after each callback.
+
+## Terminal behavior
+
+There is never a second correction or third review. Missing, malformed, forged,
+stale, cross-record-mismatched, or mutated evidence; a thrown callback; a
+`fail`; or an unresolved correction produces `built-needs-review`.
+
+That outcome retains available artifacts and review evidence for diagnosis, but
+invokes neither durability nor publication. It cannot be finalized, archived,
+attested, or pushed as a successful recap.
+
+See [Troubleshooting](../../reference/troubleshooting.md) for recovery steps.