explorbot 0.2.3 → 0.2.5

package/docs/basics/providers.md

@@ -0,0 +1,362 @@
+# AI Provider Configuration
+
+Explorbot connects to AI providers through the [Vercel AI SDK](https://sdk.vercel.ai/). Use any supported provider, and mix providers across different models.
+
+> The `export default` config block inside each `<!-- START/END provider -->` marker is generated from [`models.json`](../../models.json). After editing that file, run `bunosh docs:sync`. Everything else — including the import blocks — is hand-written.
+
+## Requirements
+
+Your model must support:
+- Structured output (JSON mode)
+- Tool use (function calling)
+
+To analyze screenshots, you also need a vision-capable model.
+
+Explorbot uses three roles: 
+
+- `model` for token-heavy page reading of ARIA & HTMLs (cheap & fast).
+- `visionModel` for screenshot analysis
+- `agenticModel` as advisor and planner. 
+
+Pick a fast, cheap model for the first two and a stronger one for the third. When a provider has no recommended model for one of these roles, combine it with another provider for that role.
+
+### OpenRouter
+
+Start with OpenRouter. One key reaches [many providers and models](https://openrouter.ai/models).
+Openrouter is an optimal solution as you can balance the models and provider for best price and speed.
+So if your goal is to optimize costs, choose Openrouter.
+
+> Openrouter is recommended to start as it serves best models 
+
+Install the provider package:
+
+```bash
+npm i @openrouter/ai-sdk-provider
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:openrouter -->
+```javascript
+export default {
+  ai: {
+    model: openrouter('openai/gpt-oss-20b:nitro'),
+    visionModel: openrouter('google/gemma-4-31b-it:nitro'),
+    agenticModel: openrouter('google/gemma-4-31b-it:nitro'),
+  },
+};
+```
+<!-- END provider:openrouter -->
+
+Pick model IDs from [OpenRouter](https://openrouter.ai/) that support structured output and tools. The `:nitro` variants route to the fastest available host.
+
+### Groq
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/groq
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createGroq } from '@ai-sdk/groq';
+
+const groq = createGroq({
+  apiKey: process.env.GROQ_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:groq -->
+```javascript
+export default {
+  ai: {
+    model: groq('openai/gpt-oss-20b'),
+    visionModel: groq('qwen/qwen3.6-27b'),
+    agenticModel: groq('qwen/qwen3.6-27b'),
+  },
+};
+```
+<!-- END provider:groq -->
+
+The gpt-oss models are fast and cheap; the larger 120B handles the agenticModel role.
+
+### OpenAI
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/openai
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createOpenAI } from '@ai-sdk/openai';
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:openai -->
+```javascript
+export default {
+  ai: {
+    model: openai('gpt-5.4-nano'),
+    visionModel: openai('gpt-5.4-nano'),
+    agenticModel: openai('gpt-5.6-luna'),
+  },
+};
+```
+<!-- END provider:openai -->
+
+### Anthropic
+
+Claude Haiku is the only Anthropic model suited to Explorbot, and even it is too costly per token for the token-heavy roles, so we recommend it only for the low-volume agenticModel. Use a cheaper provider for `model` and `visionModel` (see [Multi-Provider Configuration](#multi-provider-configuration)).
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/anthropic
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createAnthropic } from '@ai-sdk/anthropic';
+
+const anthropic = createAnthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+```
+
+Set the recommended model in the exported config:
+
+<!-- START provider:anthropic -->
+```javascript
+export default {
+  ai: {
+    agenticModel: anthropic('claude-haiku-4-5-20251001'),
+  },
+};
+```
+
+> [!NOTE]
+> This provider currently doesn't serve `model` and `visionModel`, which is required for Explorbot to run at optimal cost and speed.
+> It is recommended to pair it with another AI provider.
+<!-- END provider:anthropic -->
+
+### Azure OpenAI
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/azure
+```
+
+Import it inside `explorbot.config.ts` and create the client from your resource name and API key:
+
+```javascript
+import { createAzure } from '@ai-sdk/azure';
+
+const azure = createAzure({
+  resourceName: process.env.AZURE_RESOURCE_NAME,
+  apiKey: process.env.AZURE_API_KEY,
+});
+```
+
+Set the models in the exported config, using the deployment names you created in your resource:
+
+```javascript
+export default {
+  ai: {
+    model: azure('your-deployment-name'),
+    visionModel: azure('your-deployment-name'),
+    agenticModel: azure('your-deployment-name'),
+  },
+};
+```
+
+Azure addresses models by the deployment names you create in your resource, not by public model IDs. Use separate deployments if chat and vision run on different endpoints.
+
+### Google (Gemini)
+
+An API key from [Google AI Studio](https://aistudio.google.com/apikey) already has the Gemini API enabled. A key from the Google Cloud console may need the API enabled first, and service-account (Vertex Express) keys use a different API surface than the one this provider targets.
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/google
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+
+const google = createGoogleGenerativeAI({
+  apiKey: process.env.GOOGLE_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:google -->
+```javascript
+export default {
+  ai: {
+    model: google('gemini-3.1-flash-lite'),
+    visionModel: google('gemini-3.1-flash-lite'),
+    agenticModel: google('gemini-3.5-flash'),
+  },
+};
+```
+<!-- END provider:google -->
+
+The flash-lite tier is the cheapest current option for the token-heavy `model` and `visionModel` roles; the full flash is stronger for the low-volume `agenticModel`.
+
+On a free (no-billing) key the `agenticModel` is heavily rate-limited and will fail with quota errors mid-session — keep every role on the flash-lite model or enable billing. Google also retires older models for new accounts: `gemini-2.5-flash` and `gemini-2.5-flash-lite` return a 404 for keys created after their cutoff, and enabling billing does not bring them back.
+
+Note: Gemini models are slower than hosted OSS models on Groq or Cerebras. Everything works, sessions just take more wall-clock time.
+
+### Mistral
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/mistral
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createMistral } from '@ai-sdk/mistral';
+
+const mistral = createMistral({
+  apiKey: process.env.MISTRAL_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:mistral -->
+```javascript
+export default {
+  ai: {
+    model: mistral('mistral-small-latest'),
+    visionModel: mistral('mistral-small-latest'),
+    agenticModel: mistral('mistral-large-latest'),
+  },
+};
+```
+<!-- END provider:mistral -->
+
+Mistral Small covers the token-heavy `model` and `visionModel` roles — it accepts image input, so it can read screenshots. Mistral Large, the larger multimodal flagship, handles the low-volume `agenticModel`. The `-latest` aliases track Mistral's newest release of each, so recommendations keep up as models ship.
+
+### Poolside
+
+Poolside serves an OpenAI-compatible endpoint, so it uses the OpenAI provider package with a custom `baseURL`:
+
+```bash
+npm i @ai-sdk/openai
+```
+
+Import it inside `explorbot.config.ts` and point the client at the poolside endpoint:
+
+```javascript
+import { createOpenAI } from '@ai-sdk/openai';
+
+const poolside = createOpenAI({
+  apiKey: process.env.POOLSIDE_API_KEY,
+  baseURL: 'https://inference.poolside.ai/v1',
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:poolside -->
+```javascript
+export default {
+  ai: {
+    model: poolside('poolside/laguna-xs-2.1'),
+  },
+};
+```
+
+> [!NOTE]
+> This provider currently doesn't serve `visionModel` and `agenticModel`, which is required for Explorbot to run at optimal cost and speed.
+> It is recommended to pair it with another AI provider.
+<!-- END provider:poolside -->
+
+Laguna XS is an agentic coding model — fast, cheap, and reliable at tool calling, which makes it a good fit for the token-heavy `model` role that reads page HTML and drives the browser.
+
+Keep `agenticModel` on another provider. Poolside's endpoint accepts `response_format: json_schema` but does not enforce it, so structured-output calls depend on the model volunteering valid JSON. Laguna XS usually does; Laguna S answers in prose instead, which makes it unusable for the Planner, Pilot, and Captain. Laguna S is also slow enough under page-sized prompts to hit Explorbot's request timeouts, so it is not a substitute for Laguna XS in the `model` role either.
+
+## Multi-Provider Configuration
+
+Mix clients the same way you assign `model`, `visionModel`, and `agenticModel`. Each field can use a different provider instance — a fast provider does the token-heavy reading while a stronger one makes the decisions:
+
+```javascript
+import { createGroq } from '@ai-sdk/groq';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+
+const groq = createGroq({ apiKey: process.env.GROQ_API_KEY });
+const openrouter = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
+
+export default {
+  ai: {
+    model: groq('openai/gpt-oss-20b'),
+    visionModel: groq('meta-llama/llama-4-scout-17b-16e-instruct'),
+    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+  },
+};
+```
+
+## Per-Agent Model Configuration
+
+Any agent can override the defaults. Add an `agents` block and set per-agent options — a different `model` (using any client shown above) or a `reasoning` level:
+
+```javascript
+export default {
+  ai: {
+    // ...your model, visionModel, agenticModel...
+    agents: {
+      researcher: { reasoning: 'low' },
+      planner: { reasoning: 'none' },
+      tester: { reasoning: 'none' },
+    },
+  },
+};
+```
+
+See [Configuration](../reference/configuration.md) for every per-agent option.
+
+## Environment Variables
+
+Set your API key as an environment variable, or use a `.env` file in your project root:
+
+```bash
+export OPENROUTER_API_KEY=your-key-here
+export GROQ_API_KEY=your-key-here
+export CEREBRAS_API_KEY=your-key-here
+export OPENAI_API_KEY=your-key-here
+export ANTHROPIC_API_KEY=your-key-here
+export GOOGLE_API_KEY=your-key-here
+export MISTRAL_API_KEY=your-key-here
+```

package/docs/basics/running.md

@@ -0,0 +1,78 @@
+# Running Explorbot: TUI and CLI
+
+There are two ways to run Explorbot: an interactive terminal UI where you watch and steer, and plain CLI commands that do one job and exit. Same engine, same config, same artifacts — the difference is whether you are in the loop.
+
+| Use | Choose it when | Start with |
+|-----|----------------|------------|
+| **TUI** | You are learning, steering, or debugging interactively | `npx explorbot start /path` |
+| **CLI** | You want one repeatable task that prints a result and exits | `npx explorbot explore /path` |
+| **Persistent browser** | You run several local commands and want to avoid starting a new browser process each time | `npx explorbot browser start --show` |
+| **CI** | You need unattended, scheduled, or pipeline runs with saved reports | `npx explorbot explore /path --max-tests 10` |
+
+Persistent browser is an optimization for local TUI or CLI work, while CI uses CLI commands. Each command still creates a fresh browser context; use `--session` when cookies and login state must carry over. See [Persistent Browser](../reference/commands.md#persistent-browser) and [Continuous Integration](../workflow/ci.md) for setup details.
+
+## TUI mode
+
+`npx explorbot start` opens the interactive terminal UI. Pass a path to start on a specific page:
+
+```bash
+npx explorbot start /admin/projects
+```
+
+The screen splits into a log pane, where everything Explorbot does is printed as it happens, and an input line at the bottom. Type slash-commands to drive it:
+
+```
+/explore     # full loop: research, plan, test, repeat
+/research    # analyze the current page
+/plan        # propose test scenarios
+/test        # run the next test
+```
+
+You can also type raw CodeceptJS commands — `I.click('Save')`, `I.amOnPage('/login')` — and they execute in the browser immediately. In interactive mode the bot asks you for help when it gets stuck, instead of giving up.
+
+Use the TUI for:
+
+- **First runs.** You see every step and every mistake as it happens.
+- **Teaching Explorbot your app.** Watch it fail, add a knowledge file, retry — the tight loop is what the TUI is for.
+- **Debugging a failing scenario.** Replay it step by step with slash-commands and raw `I.*` commands.
+
+The TUI needs a modern terminal — iTerm2, WARP, Kitty, Ghostty, or Windows Terminal with WSL; see [Prerequisites](./prerequisites.md) for the compatibility notes.
+
+## CLI mode
+
+Every other command runs without the TUI: it launches a browser (headless by default), does its job, prints the result, and exits.
+
+| Command | What it does | Docs |
+|---------|--------------|------|
+| `explore <path>` | Research a page, plan tests, run them, move to sub-pages | [Web Testing Basics](../web-testing/basics.md) |
+| `plan <path>` | Generate a test plan as markdown and exit | [Test Plans](../workflow/test-plans.md) |
+| `test <planfile> [index]` | Run tests from a saved plan | [Test Plans](../workflow/test-plans.md) |
+| `rerun <file>` | Re-run generated tests with AI healing | [Rerun](../web-testing/rerun.md) |
+| `docs collect <url>` | Crawl pages and generate documentation | [Doc Collection](../doc-collection/basics.md) |
+| `api plan` / `api test` / `api explore` | Plan and run API tests | [API Testing](../api-testing/basics.md) |
+
+The full list, with every option, is in the [Commands reference](../reference/commands.md).
+
+### Exit codes
+
+CLI commands follow one rule: exit `0` when the run completed, `1` when the run itself failed — a config error, an unreachable start page, a provider that won't respond. Before exiting, the CLI shows a short session summary if anything happened during the run.
+
+For `explore` and `test`, a failing test does **not** change the exit code. The run completed; the failure is a result, printed in the console summary and recorded in the reports. So `npx explorbot explore / || echo broken` catches crashes, not bugs. To gate a pipeline on test results, read the reports — see [Continuous Integration](../workflow/ci.md).
+
+A few commands have sharper semantics you can script against:
+
+- `plan` exits `1` when no test scenarios could be generated.
+- `navigate <url>` exits `0` when the page was reached, `1` when not — a cheap "is the app up and can we log in" probe.
+- `api test` and `api explore` exit `1` when any test failed.
+
+## Flags that matter in both modes
+
+The browser runs headless by default; `--show` opens a visible window and `--headless` forces it hidden. `--session [file]` saves and restores the browser session (cookies, localStorage) — the default file is `output/session.json` — so login happens once and later runs skip it. `--incognito` runs without recording experience, useful for throwaway runs. `--verbose` prints debug logs. See the [Commands reference](../reference/commands.md) for the rest.
+
+## Driving Explorbot from other tools
+
+CLI mode makes Explorbot scriptable by anything that can run a shell command — including coding agents like Claude Code. Every input and output is plain markdown: plans land in `output/plans/`, reports in `output/reports/`, and hints live in `knowledge/`. An agent can run `explorbot plan /checkout`, read the generated plan, edit or extend it, run `explorbot test` on it, read the report, then write a knowledge file to fix what confused the bot — and iterate. No API or SDK needed; the files are the interface.
+
+## Running in CI
+
+Because CLI commands exit cleanly and keep their learning in cacheable directories, Explorbot fits scheduled pipelines: run `explore` nightly with a test budget, cache `experience/` and `output/` between runs, and upload the reports. See [Continuous Integration](../workflow/ci.md) for worked examples.

package/docs/contributing/ai-integration-tests.md

@@ -0,0 +1,57 @@
+# AI Agent Integration Tests
+
+We test AI agents with [`@copilotkit/aimock`](https://github.com/CopilotKit/aimock), an HTTP mock server that speaks LLM provider protocols. Unlike in-process model stubs, it runs the real `Provider` class and lets you inspect the HTTP requests through its Journal.
+
+Reference implementation: `tests/integration/planner.test.ts`.
+
+## Principles
+
+### What we mock
+
+- **The AI provider** — via the aimock HTTP server. Point the Vercel AI SDK at `mock.url/v1` with `createOpenAI({ compatibility: 'compatible' })` and `openai.chat('model-name')`. The `compatibility: 'compatible'` option keeps the mock on the Chat Completions API; without it, the SDK defaults to the Responses API, which aimock does not fully implement.
+- **Explorer, StateManager, Researcher, ExperienceTracker** — duck-typed mocks with only the methods the agent under test calls. Each agent runs in isolation; downstream agents (such as Researcher when testing Planner) return canned output.
+- **`withPage`** — resolves with a fake page object for agents that validate locators, since no browser runs in these tests.
+
+### What we don't mock
+
+- The real `Provider` class, so tests exercise serialization, retry, and telemetry paths.
+- Parsers, result objects, and markdown processing — the real pipeline runs.
+- `ActionResult.fromState()`, which works without the filesystem when `state.html` is inline.
+
+### What we test
+
+- **Output correctness**: the plan or research markdown the agent returns matches the canned AI response.
+- **Prompt construction** (via Journal): `mock.getLastRequest()` returns the messages sent to the AI, so you assert on what the agent prompted, not just what it returned. This is the main reason to use aimock.
+- **Control flow**: cache hits, dedup, retries, error paths, and style or feature injection. Inspect the request count and prompt content.
+
+### Fixture types
+
+- Text response (for `chat()` / `invokeConversation()`): `mock.on({}, { content: 'text' })`
+- Structured output (for `generateObject()`): `mock.on({}, { content: JSON.stringify(obj) })` — the SDK parses it back via `response_format: json_schema`
+- Sequential responses: `mock.on({ sequenceIndex: 0 }, ...)`, `sequenceIndex: 1`, ...
+- Errors: `mock.on({}, { error: {...}, status: 500 })`
+- See aimock docs for matching by user message, tool name, regex, or predicate.
+
+### Test data
+
+- Canned UI maps live in `test-data/ui-maps/`.
+- Use fictional applications (Task Tracker, and so on). Never use real product data or user names.
+- Two formats exist, depending on the agent under test:
+  - **Planner-input** (`task-board.md`): Element and Type columns only — what the Planner sees after its own table-column filtering.
+  - **Researcher-output** (`task-board-research.md`): full Element, Type, ARIA, CSS, and Coordinates columns — the raw Researcher AI output format.
+
+### Module-level caches
+
+Many agents hold module-level state: plan registry, session dedup, style cache, research cache. Each module that caches across calls must export a `clearXxx()` function for use in `beforeEach`. See the existing exports:
+
+- `src/ai/planner/subpages.ts` — `clearPlanRegistry()`
+- `src/ai/planner/session-dedup.ts` — `clearSessionDedup()`
+- `src/ai/planner/styles.ts` — `clearStyleCache()`
+- `src/ai/researcher/cache.ts` — `clearResearchCache()`
+
+## Running
+
+```bash
+bun test tests/integration/planner.test.ts
+bun test tests/integration/
+```

package/docs/contributing/contributing.md

@@ -0,0 +1,90 @@
+# Contributing to Explorbot
+
+## Project Philosophy
+
+Explorbot is general-purpose. It works with any web application, with no site-specific code. Keep this in mind when you contribute:
+
+- Solutions must work across different websites.
+- Don't hardcode locators or site-specific selectors.
+- Prefer universal patterns: ARIA, semantic HTML, common UI conventions.
+- A fix that only helps one site is probably the wrong approach.
+
+## Before You Start
+
+Discuss first, code second. Open an issue to propose your idea before you send a PR. This saves wasted effort and aligns on the approach.
+
+If Explorbot struggles on your site, try the built-in extension points first:
+
+- Knowledge files teach Explorbot about your pages (credentials, wait conditions, hints).
+- Rules add agent-specific guidance for navigation, research, and planning.
+- Hooks run custom logic before and after actions.
+- Configuration adjusts models, timeouts, and browser settings.
+
+See the [knowledge](../workflow/knowledge.md), [hooks](../web-testing/hooks.md), and [configuration](../reference/configuration.md) docs.
+
+## Pull Requests
+
+We accept PRs that help a variety of users. Here is what gets merged.
+
+### Tiny PRs get merged first
+
+Small, focused changes are reviewed and merged quickly. Examples:
+
+- Fix a typo in a prompt.
+- Add a missing ARIA selector pattern.
+- Improve an error message.
+- Fix a bug with a clear reproduction.
+
+### PRs that change agent logic require manual testing
+
+Changes to agents (tester, navigator, researcher, pilot, and others) affect how Explorbot interacts with every website. These PRs must be:
+
+- Polished — clean code, no leftover debug artifacts.
+- Tested by a person on real websites.
+- Described clearly: what changed and why.
+
+### PRs that change prompts require execution traces
+
+If you change internal AI prompts or rules, you must provide a [Langfuse](https://langfuse.com) execution trace that shows the change improved behavior. "It should work better" is not evidence. Show the before and after.
+
+### We accept agentic PRs
+
+AI-generated contributions are welcome if they follow the rules above: small, focused, tested, with clear explanations.
+
+### What NOT to send
+
+- PRs that reformat code differently. We use [Biome](https://biomejs.dev/) for formatting. Run `bun run format` before submitting.
+- Large refactoring PRs without prior discussion.
+- Site-specific fixes that only help one website.
+- Changes that break existing tests.
+
+## Development Setup
+
+```bash
+bun install
+bunx playwright install
+```
+
+## Code Style
+
+- Biome for formatting and linting. Run `bun run format` after every change.
+- No comments unless explicitly needed.
+- Early returns instead of nested if/else.
+- KISS/YAGNI — make the smallest change possible.
+- No code duplication. Check if it already exists.
+- Use dedent for formatting prompts.
+- No ternary operators.
+
+See `CLAUDE.md` for the full guidelines.
+
+## Testing
+
+Run `bun run format`, `bun run lint`, `bun run test:unit`, and `bun run test:node` before you submit a PR — all checks must pass. See the [testing guide](testing.md) for details, [AI integration tests](ai-integration-tests.md) for mocked-LLM agent tests, and [regression tests](regression-tests.md) for the real-AI end-to-end harness.
+
+## Using Claude Code
+
+This project includes Claude Code skills to help with development. See the `.claude/skills/` directory: changelog, demo-video, explorbot-debug, explorbot-fix-session, image-processing, prompt-audit, xpath-testing.
+
+## Questions?
+
+Open an issue on GitHub for questions or discussion.

package/docs/contributing/demo-videos.md

@@ -0,0 +1,36 @@
+# Demo Videos
+
+Explorbot sessions can be turned into demo videos for social media and presentations. The generator composites the browser screencast of a test with a simulated terminal that replays the session's real log lines at their original pace, over an abstract background with window chrome and shadows. Everything shown is real recorded data: no more than 1.25x speedup, successful runs only.
+
+Implementation lives in `.claude/skills/demo-video/` (`demo-video.ts` exports `analyzeDemoCandidates` and `createDemoVideo`; the Bunoshfile wraps them as commands).
+
+## Prerequisites
+
+- `vhs` and `ttyd` — render the terminal simulation (`go install github.com/charmbracelet/vhs@latest`)
+- `ffmpeg` and ImageMagick
+- IBM Plex Mono font (optional — VHS falls back to its default mono font)
+- A session recorded with screencasts: enable `ai.agents.historian.screencast` in `explorbot.config.js` so `output/screencasts/*.webm` exist alongside `output/explorbot.log`
+
+## Usage
+
+```bash
+bunx bunosh demo:analyze output/explorbot.log --screencasts output/screencasts
+bunx bunosh demo:video --size landscape --app-title "My App"
+bunx bunosh demo:video "upload a file" --size vertical --terminal-theme light
+```
+
+`demo:analyze` lists candidate segments ranked by how well they will read on video. `demo:video` renders the best one, or the test whose scenario name matches the first argument. Key options: `--duration` (target seconds, default 30), `--size` (`landscape`, `square`, `vertical`, or `WxH`), `--app-title` (browser window title, defaults to the tested app's host), `--terminal-theme` (`dark` or `light`), `--bg-image` (`auto` fetches a random abstract photo from Unsplash, `gradient` generates one offline, or pass a file/URL). Run `bunx bunosh demo:video --help` for the full list.
+
+The renderer verifies its output and writes three check frames (`*-frame-first/mid/last.png`) next to the video — review them before publishing.
+
+## How segments are picked
+
+Only successful tests with an existing screencast qualify. Within a test, the scorer prefers windows that:
+
+- are dense in visible actions (click, fill, type, navigate) rather than thinking or verification steps
+- have no dead air — inter-step gaps stay under 10 seconds
+- show forward progress — windows dominated by repeated retry steps are rejected
+- were executed live — batch-logged step bursts cannot sync with the video and are rejected
+- do not end on a failure note or mid-navigation on a blank page
+
+The log's `Saved screencast:` line joins a test to its `.webm`; video time is calibrated from that timestamp minus the video duration. If a screencast file was overwritten by a run outside the log, it is skipped.