explorbot 0.5.0 → 0.5.1

package/bin/explorbot-cli.ts

@@ -12,7 +12,7 @@ import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
+import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
@@ -33,6 +33,7 @@ const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version as stri
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 wsOption.register(program);
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 
 process.on('uncaughtException', async (error) => {
   tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);

package/boat/prima/README.md

@@ -61,22 +61,49 @@ prima-cli browser stop
 
 Prima needs a model, and takes it from the environment. There is no `init` to run and nothing is written for you.
 
+The setup we recommend runs everything through OpenRouter with one key: GPT-OSS 120B served by Groq as the main model, and TypeSafe's Jev as the [decision model](https://github.com/testomatio/explorbot/blob/main/docs/web-testing/decisions.md), which answers narrow yes/no and pick-one questions so the main model is called less often.
+
 ```bash
-export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b
-export OPENROUTER_API_KEY=your-key
+PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b:nitro
+PRIMA_CLI_DECISION_MODEL=openrouter/typesafe/jev-1.13
+OPENROUTER_API_KEY=your-key
 ```
 
-The provider comes from the model name, so that is the whole setup. Fish uses `set -gx` instead of `export`. Since prima is usually run by a coding agent, the better home is the agent's own config — in `~/.claude/settings.json`, an `env` block reaches every command the agent runs:
+The provider comes from each model name, and `:nitro` asks OpenRouter for its fastest host, which is Groq for this model. Jev is optional: leave `PRIMA_CLI_DECISION_MODEL` unset and prima never calls it, or pass `--decision-model` for a single run.
+
+Prima is usually run by a coding agent, so the best home for these variables is the agent's own config, where they reach every command the agent runs.
+
+Claude Code, in `~/.claude/settings.json`:
 
 ```json
 {
   "env": {
-    "PRIMA_CLI_AI_MODEL": "openrouter/openai/gpt-oss-120b",
+    "PRIMA_CLI_AI_MODEL": "openrouter/openai/gpt-oss-120b:nitro",
+    "PRIMA_CLI_DECISION_MODEL": "openrouter/typesafe/jev-1.13",
     "OPENROUTER_API_KEY": "your-key"
   }
 }
 ```
 
+Codex, in `~/.codex/config.toml`:
+
+```toml
+[shell_environment_policy]
+set = { PRIMA_CLI_AI_MODEL = "openrouter/openai/gpt-oss-120b:nitro", PRIMA_CLI_DECISION_MODEL = "openrouter/typesafe/jev-1.13", OPENROUTER_API_KEY = "your-key" }
+```
+
+`set` is applied after Codex filters the inherited environment, so the key survives even where names containing `KEY` are stripped.
+
+To run prima yourself, or from any agent that inherits your shell, export them in `~/.bashrc` or `~/.zshrc`:
+
+```bash
+export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b:nitro
+export PRIMA_CLI_DECISION_MODEL=openrouter/typesafe/jev-1.13
+export OPENROUTER_API_KEY=your-key
+```
+
+Fish uses `set -gx` in `~/.config/fish/config.fish` instead of `export`.
+
 Screenshot analysis needs its own model — one is never guessed from the main model. Set `PRIMA_CLI_VISION_MODEL`, or pass `--vision-model` for a single run, as `--model` does for the main one. Without it prima still runs, but settles `check` outcomes from the run log rather than from the page as seen.
 
 Every `PRIMA_CLI_*` variable mirrors the `EXPLORBOT_*` one of the same name and wins over it, so prima can be pointed at a different provider, model or URL without disturbing an explorbot setup on the same machine. `PRIMA_CLI_AI_MODEL`, `PRIMA_CLI_URL`, `PRIMA_CLI_VISION_MODEL` and the rest all work this way.

package/boat/prima/bin/prima-cli.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
-import { knowledgeOption } from '../../../src/commands/options/index.ts';
+import { decisionModelOption, knowledgeOption } from '../../../src/commands/options/index.ts';
 import { createPrimaCommands } from '../src/cli.ts';
 
 const program = createPrimaCommands('prima');
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 program.parse();

package/dist/bin/explorbot-cli.js

@@ -12,7 +12,7 @@ import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
+import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
@@ -30,6 +30,7 @@ const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 wsOption.register(program);
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 process.on('uncaughtException', async (error) => {
     tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);
     await flushTelemetry();

package/dist/boat/prima/bin/prima-cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { knowledgeOption } from "../../../src/commands/options/index.js";
+import { decisionModelOption, knowledgeOption } from "../../../src/commands/options/index.js";
 import { createPrimaCommands } from "../src/cli.js";
 const program = createPrimaCommands('prima');
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 program.parse();

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -102,7 +102,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "^4.2.0-beta.3",
+    "codeceptjs": "^4.2.0",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",

package/dist/src/ai/provider.js

@@ -615,7 +615,7 @@ export class Provider {
         if (!this.config.visionModel) {
             throw new Error(`Vision model not configured. Set ai.visionModel in your config; ${getCliName()} recommended-models lists the providers that serve one`);
         }
-        setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');
+        setActivity(`🤖 Processing image with ${getModelName(this.config.visionModel)}`, 'ai');
         const messages = [
             {
                 role: 'user',

package/dist/src/ai/rules.js

@@ -480,6 +480,19 @@ export const actionRule = dedent `
 
   After hovering, use see() or context() to check what appeared.
 
+  ### I.seeInClipboard / I.seeClipboardEquals / I.clearClipboard
+
+  Check what a copy control put into the system clipboard. Run via form(), not click().
+  I.seeInClipboard asserts the clipboard contains the text, I.seeClipboardEquals asserts an exact match,
+  I.clearClipboard empties it — call it before copying so a stale value can't pass the check.
+
+  <example>
+    I.clearClipboard();
+    I.click({ role: 'button', text: 'Copy link' });
+    I.seeInClipboard('/invite/');
+    I.seeClipboardEquals('ABC-123');
+  </example>
+
   [DO NEVER USE OTHER CODECEPTJS COMMANDS THAN PROPOSED HERE]
   [INTERACT ONLY WITH ELEMENTS THAT ARE ON THE PAGE HTML]
   [DO NOT USE WAIT FUNCTIONS]

package/dist/src/commands/options/decision-model-option.d.ts

@@ -0,0 +1,6 @@
+import { BaseOption } from './base-option.js';
+export declare class DecisionModelOption extends BaseOption {
+    flags: string;
+    description: string;
+    apply(options: Record<string, any>): void;
+}

package/dist/src/commands/options/decision-model-option.js

@@ -0,0 +1,10 @@
+import { BaseOption } from './base-option.js';
+export class DecisionModelOption extends BaseOption {
+    flags = '--decision-model <model>';
+    description = 'Turn on the decision model for this run, as provider/model-id (e.g. openrouter/typesafe/jev-1.13)';
+    apply(options) {
+        if (!options.decisionModel)
+            return;
+        process.env.EXPLORBOT_DECISION_MODEL = options.decisionModel;
+    }
+}

package/dist/src/commands/options/index.d.ts

@@ -1,5 +1,7 @@
+import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 export { BaseOption } from './base-option.js';
+export declare const decisionModelOption: DecisionModelOption;
 export declare const knowledgeOption: KnowledgeOption;
 export declare const wsOption: WsOption;

package/dist/src/commands/options/index.js

@@ -1,5 +1,7 @@
+import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 export { BaseOption } from './base-option.js';
+export const decisionModelOption = new DecisionModelOption();
 export const knowledgeOption = new KnowledgeOption();
 export const wsOption = new WsOption();

package/dist/src/config.d.ts

@@ -270,6 +270,7 @@ export declare class ConfigParser {
     static cleanupAllTestDirectories(): void;
     enterGlobalMode(config: ExplorbotConfig, target: string | null): Promise<ExplorbotConfig>;
     applyEnvSpec(config: ExplorbotConfig): void;
+    applyEnvDecisionModel(config: ExplorbotConfig): void;
     buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
     loadConfigModule(configPath: string): Promise<any>;

package/dist/src/config.js

@@ -45,6 +45,7 @@ export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_URL', required: true, description: 'Base URL to test; the API boat reads it as the base endpoint' },
     { name: 'EXPLORBOT_VISION_MODEL', description: 'Screenshot analysis; overrides the provider recommendation' },
     { name: 'EXPLORBOT_AGENTIC_MODEL', description: 'Captain and Pilot decisions; overrides the provider recommendation' },
+    { name: 'EXPLORBOT_DECISION_MODEL', description: 'Turns on the decision model, as provider/model-id (openrouter/typesafe/jev-1.13 or typesafe/jev-latest); overrides ai.decisionModel' },
     { name: 'EXPLORBOT_OUTPUT', description: 'Output root for states, plans, research, and reports. Defaults to the site dir under ~/.explorbot/sites' },
     { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
     { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
@@ -138,6 +139,7 @@ export class ConfigParser {
             this.runtimeTarget = target;
             this.configPath = sourcePath;
             this.applyEnvSpec(this.config);
+            this.applyEnvDecisionModel(this.config);
             // Restore original directory after successful config load
             if (options?.path && originalCwd !== process.cwd()) {
                 process.chdir(originalCwd);
@@ -300,6 +302,15 @@ export class ConfigParser {
             config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
         config.dirs.spec = spec;
     }
+    applyEnvDecisionModel(config) {
+        const spec = process.env.EXPLORBOT_DECISION_MODEL;
+        if (!spec)
+            return;
+        const separator = spec.indexOf('/');
+        if (separator < 1)
+            throw new Error('EXPLORBOT_DECISION_MODEL must be written as "provider/model-id", e.g. openrouter/typesafe/jev-1.13');
+        config.ai.decisionModel = { ...config.ai.decisionModel, provider: spec.slice(0, separator), model: spec.slice(separator + 1) };
+    }
     async buildEnvConfig(baseUrl, outputRoot) {
         const provider = process.env.EXPLORBOT_AI_PROVIDER;
         const modelSpec = process.env.EXPLORBOT_AI_MODEL;

package/docs/basics/providers.md

@@ -22,6 +22,8 @@ Explorbot uses three roles:
 
 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.
 
+An optional [decision model](#decision-model) can answer narrow yes/no and pick-one questions so the other models are called less often.
+
 ### OpenRouter
 
 Start with OpenRouter. One key reaches [many providers and models](https://openrouter.ai/models).
@@ -308,6 +310,40 @@ Laguna XS is an agentic coding model — fast, cheap, and reliable at tool calli
 
 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.
 
+## Decision Model
+
+A decision model is an optional fourth role. It does not generate text or call tools. It receives the current state and one closed question, and returns an answer with a probability. Explorbot uses it for narrow choices that would otherwise take a call to a larger model or a guess.
+
+Explorbot supports TypeSafe's Jev, reached through OpenRouter or through TypeSafe's API directly:
+
+```javascript
+export default {
+  ai: {
+    // ...your model, visionModel, agenticModel...
+    decisionModel: { provider: 'openrouter', model: 'typesafe/jev-1.13' },
+    // or: decisionModel: { provider: 'typesafe', model: 'jev-latest' },
+  },
+};
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `provider` | `'openrouter' \| 'typesafe'` | Authenticates with `OPENROUTER_API_KEY` or `TYPESAFE_API_KEY` |
+| `model` | `string` | Model ID at that provider |
+| `tool` | `boolean` | Give Tester and Pilot a `judge` tool to ask their own questions. Default: `true` |
+| `direct` | `boolean` | Consult the model at Explorbot's built-in decision points. Default: `true` |
+
+Without a config file, or to turn it on for one run, set `EXPLORBOT_DECISION_MODEL` or pass `--decision-model` as `provider/model-id`. It overrides `provider` and `model` in the config and keeps `tool` and `direct`:
+
+```bash
+EXPLORBOT_DECISION_MODEL=openrouter/typesafe/jev-1.13 npx explorbot explore
+npx prima-cli go "Settings" --decision-model typesafe/jev-latest
+```
+
+Leave `decisionModel` unset and Explorbot never calls it. An unknown provider or a missing API key stops Explorbot at startup.
+
+Explorbot acts on an answer only when it is more than 70% sure, and otherwise does what it would have done without the decision model. See [Decisions](../web-testing/decisions.md) for where it is consulted, the `judge` tool, and what happens when an answer is rejected.
+
 ## 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:
@@ -359,4 +395,5 @@ 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
+export TYPESAFE_API_KEY=your-key-here
 ```

package/docs/index.json

@@ -22,6 +22,7 @@
         { "title": "Planner", "file": "web-testing/planner.md", "description": "Tune what gets tested" },
         { "title": "Researcher", "file": "web-testing/researcher.md", "description": "How pages are analyzed, and how to tune it" },
         { "title": "Page interaction", "file": "web-testing/page-interaction.md", "description": "How agents read and act on a page" },
+        { "title": "Decisions", "file": "web-testing/decisions.md", "description": "The optional decision model: built-in decision points, the judge tool, fallbacks" },
         { "title": "Automated tests", "file": "web-testing/automated-tests.md", "description": "The runnable test files you keep" },
         { "title": "Rerun", "file": "web-testing/rerun.md", "description": "Re-run generated tests with AI healing" },
         { "title": "Agents", "file": "web-testing/agents.md", "description": "What each agent does under the hood" },

package/docs/reference/commands.md

@@ -112,6 +112,7 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 | `EXPLORBOT_URL` | Base URL to test; the API boat reads it as the base endpoint |
 | `EXPLORBOT_VISION_MODEL` | Screenshot analysis; overrides the provider recommendation |
 | `EXPLORBOT_AGENTIC_MODEL` | Captain and Pilot decisions; overrides the provider recommendation |
+| `EXPLORBOT_DECISION_MODEL` | Turns on the decision model, as provider/model-id (openrouter/typesafe/jev-1.13 or typesafe/jev-latest); overrides ai.decisionModel |
 | `EXPLORBOT_OUTPUT` | Output root for states, plans, research, and reports. Defaults to the site dir under ~/.explorbot/sites |
 | `EXPLORBOT_EPHEMERAL` | Keep no state between runs — output goes to a fresh temp directory instead of the site dir |
 | `EXPLORBOT_KNOWLEDGE` | Inline knowledge text, applied to every page |

package/docs/reference/configuration.md

@@ -537,6 +537,7 @@ export default {
   ai: {
     model: groq('openai/gpt-oss-20b'),   // Default model instance (required)
     visionModel: groq('meta-llama/llama-4-scout-17b-16e-instruct'),  // Model for screenshot analysis; setting it enables vision features
+    decisionModel: { provider: 'openrouter', model: 'typesafe/jev-1.13' }, // Optional; see providers docs
     config: {},                    // Additional provider config
     langfuse: {                    // Observability settings
       enabled: true,
@@ -624,6 +625,7 @@ export default {
 
 - [API testing](../api-testing/basics.md) — API testing setup and commands
 - [AI providers](../basics/providers.md) — provider setup examples
+- [Decisions](../web-testing/decisions.md) — the optional decision model and its fallbacks
 - [Agents](../web-testing/agents.md) — agent descriptions and workflows
 - [Agent hooks](../web-testing/hooks.md) — custom code before and after an agent runs
 - [Researcher agent](../web-testing/researcher.md) — Researcher configuration and usage

package/docs/web-testing/decisions.md

@@ -0,0 +1,108 @@
+# Decisions
+
+A decision model answers one closed question about the current state: a yes/no statement, or a pick from a list of options. It returns the answer together with its probability. Explorbot uses it to settle narrow choices quickly and cheaply that would otherwise need a call to a larger model or a guess.
+
+The decision model is optional. Without it Explorbot behaves exactly as described elsewhere in these docs. Setup is covered in [AI providers](../basics/providers.md#decision-model).
+
+## Decision rules
+
+Every question has one of two shapes:
+
+| Shape | Asked as | Answer |
+|---|---|---|
+| **Statement** | "The page shows that this claim is true." | Probability that the statement holds |
+| **Choice** | "Which listed element does the intent name?" plus numbered options | The chosen option and its probability |
+
+A choice always includes an extra *undecided* option, so the model can say that none of the options fits.
+
+Explorbot acts on an answer only when it is **approved**:
+
+- a statement's probability is above **70%**, or
+- a choice picked a real option, not *undecided*, with a probability above **70%**.
+
+Anything else counts as **rejected**, including:
+
+- a confident "no", or any probability of 70% or lower
+- *undecided*
+- a choice offered with fewer than two options
+- a request timeout (15 seconds) or a failed request
+- `direct: false` in the config, for built-in decision points
+
+A rejected answer never means "confidently no". It means Explorbot has no usable answer, so it takes its usual path. Every question is worded so that approving it lets Explorbot take a shortcut and rejecting it keeps the usual path. A wrong or unsure answer can therefore cost a shortcut, but never a check.
+
+## Built-in decision points
+
+These are fixed places in the code where Explorbot asks the decision model before doing the usual, more expensive work. Setting `direct: false` turns them off.
+
+### Tester: locator matches several elements
+
+When a click or fill fails because the locator matched more than one element, Explorbot lists the matches and asks which one the step meant.
+
+- **Approved:** the Tester is told which element to use and how to target it with `elementIndex`.
+- **Fallback:** the Tester receives the numbered list of matches and picks one itself, narrows the locator, or uses a visual click.
+
+### Pilot: progress review
+
+Every few steps, Pilot reviews the Tester's recent actions with the `agenticModel`. First it asks whether the run is moving toward its goal and can continue unsupervised for now.
+
+- **Approved:** the review is skipped and the Tester continues. This saves one `agenticModel` call.
+- **Fallback:** Pilot runs its full review as usual.
+
+### Navigator: claim already verified
+
+Before Navigator writes assertions for a claim, it asks whether a claim it has already verified on this page means the same thing, even if it is worded differently.
+
+- **Approved:** the claim counts as verified and no assertions are generated or run.
+- **Fallback:** Navigator verifies the claim with assertions as usual.
+
+The new claim is not added to the page's verified claims. Only a claim backed by assertions that actually ran is recorded as verified.
+
+### Navigator: claim no assertion can express
+
+Some claims cannot be turned into an assertion. When that happens, Navigator asks whether the page shows the claim is true.
+
+- **Approved:** `verify` reports that the page appears to confirm the claim. The result is marked as a judgement, kept apart from assertions that ran, and the Tester is asked to restate the claim so it can be asserted.
+- **Fallback:** `verify` reports that no assertion could express the claim, and suggests restating it or checking it with `see`.
+
+In both cases `verify` returns a failure, because nothing ran in the browser.
+
+### Prima: `go` to a described page
+
+When `prima go` gets a description of a page instead of a URL, it asks which control on the current page leads there.
+
+- **Approved:** Prima clicks that control. It then asks a second question: whether the new page shows the target. Only when that is approved too does Prima report success.
+- **Fallback:** if the choice is rejected, or the click fails, or the page doesn't change, or arrival is not confirmed, Prima hands off to the Navigator as usual.
+
+### Prima: `check` expected outcomes
+
+When `prima check` settles the expected outcomes of a finished run without a screenshot, it asks what the run established about each outcome: that it happened, or that it did not.
+
+- **Approved:** that outcome is settled as passed or failed without calling the `agenticModel`.
+- **Fallback:** the remaining outcomes are settled by the `agenticModel` as usual. When a screenshot is available, all outcomes go to the vision model and the decision model is not asked.
+
+## The `judge` tool
+
+With `tool: true`, Tester and Pilot get a `judge` tool. They use it when a step depends on reading the page rather than running a command. The tool takes:
+
+| Argument | Description |
+|---|---|
+| `question` | A statement to confirm, or the question a list of options answers |
+| `options` | Possible answers. Leave it out to confirm a statement |
+| `context` | Anything the page itself doesn't show |
+
+The model supplies only the question. The tool gathers the rest of the state itself: the current scenario, the compact ARIA snapshot of the page (up to 12,000 characters), and the last eight test steps.
+
+- **Approved:** the tool returns the answer and its confidence.
+- **Rejected:** the tool returns "Not confirmed" and tells the agent to gather more context or try another route. "Not confirmed" means the page doesn't settle the question. It does not mean the statement is false.
+
+`tool` and `direct` are independent. For example, `tool: false` keeps the built-in decision points but stops the agents from asking questions of their own.
+
+## Where it is not used
+
+- **Pilot's verdict on a test.** Whether a scenario passed, failed or was impossible is always decided by the `agenticModel`.
+- **Filtering experience.** One question per stored experience block, on every prompt, would cost more than it saves.
+- **Generation, screenshots and tool calling.** The decision model reads text and answers questions. It does not write, look at images or act on the page.
+
+## Tracing
+
+Each question is recorded as a `judge.decide` span with the question, the answer and its confidence. A failed request also records the reason. The TUI shows `⚖️ Asking judge...` while a question is in flight. See [Observability](../contributing/observability.md) for setting up tracing.

package/docs/workflow/agentic-usage.md

@@ -52,6 +52,7 @@ No `init`, no config file, no project directory, no model IDs to look up. These
 | `EXPLORBOT_URL` | yes | Base URL to test; the API boat reads it as the base endpoint |
 | `EXPLORBOT_VISION_MODEL` | no | Screenshot analysis; overrides the provider recommendation |
 | `EXPLORBOT_AGENTIC_MODEL` | no | Captain and Pilot decisions; overrides the provider recommendation |
+| `EXPLORBOT_DECISION_MODEL` | no | Turns on the decision model, as provider/model-id (openrouter/typesafe/jev-1.13 or typesafe/jev-latest); overrides ai.decisionModel |
 | `EXPLORBOT_OUTPUT` | no | Output root for states, plans, research, and reports. Defaults to the site dir under ~/.explorbot/sites |
 | `EXPLORBOT_EPHEMERAL` | no | Keep no state between runs — output goes to a fresh temp directory instead of the site dir |
 | `EXPLORBOT_KNOWLEDGE` | no | Inline knowledge text, applied to every page |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -102,7 +102,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "^4.2.0-beta.3",
+    "codeceptjs": "^4.2.0",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",

package/src/ai/provider.ts

@@ -683,7 +683,7 @@ export class Provider {
       throw new Error(`Vision model not configured. Set ai.visionModel in your config; ${getCliName()} recommended-models lists the providers that serve one`);
     }
 
-    setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');
+    setActivity(`🤖 Processing image with ${getModelName(this.config.visionModel)}`, 'ai');
 
     const messages: ModelMessage[] = [
       {

package/src/ai/rules.ts

@@ -497,6 +497,19 @@ export const actionRule = dedent`
 
   After hovering, use see() or context() to check what appeared.
 
+  ### I.seeInClipboard / I.seeClipboardEquals / I.clearClipboard
+
+  Check what a copy control put into the system clipboard. Run via form(), not click().
+  I.seeInClipboard asserts the clipboard contains the text, I.seeClipboardEquals asserts an exact match,
+  I.clearClipboard empties it — call it before copying so a stale value can't pass the check.
+
+  <example>
+    I.clearClipboard();
+    I.click({ role: 'button', text: 'Copy link' });
+    I.seeInClipboard('/invite/');
+    I.seeClipboardEquals('ABC-123');
+  </example>
+
   [DO NEVER USE OTHER CODECEPTJS COMMANDS THAN PROPOSED HERE]
   [INTERACT ONLY WITH ELEMENTS THAT ARE ON THE PAGE HTML]
   [DO NOT USE WAIT FUNCTIONS]

package/src/commands/options/decision-model-option.ts

@@ -0,0 +1,11 @@
+import { BaseOption } from './base-option.js';
+
+export class DecisionModelOption extends BaseOption {
+  flags = '--decision-model <model>';
+  description = 'Turn on the decision model for this run, as provider/model-id (e.g. openrouter/typesafe/jev-1.13)';
+
+  protected apply(options: Record<string, any>): void {
+    if (!options.decisionModel) return;
+    process.env.EXPLORBOT_DECISION_MODEL = options.decisionModel;
+  }
+}

package/src/commands/options/index.ts

@@ -1,7 +1,9 @@
+import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 
 export { BaseOption } from './base-option.js';
 
+export const decisionModelOption = new DecisionModelOption();
 export const knowledgeOption = new KnowledgeOption();
 export const wsOption = new WsOption();

package/src/config.ts

@@ -278,6 +278,7 @@ export const EXPLORBOT_ENV_VARS: EnvVar[] = [
   { name: 'EXPLORBOT_URL', required: true, description: 'Base URL to test; the API boat reads it as the base endpoint' },
   { name: 'EXPLORBOT_VISION_MODEL', description: 'Screenshot analysis; overrides the provider recommendation' },
   { name: 'EXPLORBOT_AGENTIC_MODEL', description: 'Captain and Pilot decisions; overrides the provider recommendation' },
+  { name: 'EXPLORBOT_DECISION_MODEL', description: 'Turns on the decision model, as provider/model-id (openrouter/typesafe/jev-1.13 or typesafe/jev-latest); overrides ai.decisionModel' },
   { name: 'EXPLORBOT_OUTPUT', description: 'Output root for states, plans, research, and reports. Defaults to the site dir under ~/.explorbot/sites' },
   { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
   { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
@@ -423,6 +424,7 @@ export class ConfigParser {
       this.runtimeTarget = target;
       this.configPath = sourcePath;
       this.applyEnvSpec(this.config);
+      this.applyEnvDecisionModel(this.config);
 
       // Restore original directory after successful config load
       if (options?.path && originalCwd !== process.cwd()) {
@@ -600,6 +602,14 @@ export class ConfigParser {
     config.dirs.spec = spec;
   }
 
+  private applyEnvDecisionModel(config: ExplorbotConfig): void {
+    const spec = process.env.EXPLORBOT_DECISION_MODEL;
+    if (!spec) return;
+    const separator = spec.indexOf('/');
+    if (separator < 1) throw new Error('EXPLORBOT_DECISION_MODEL must be written as "provider/model-id", e.g. openrouter/typesafe/jev-1.13');
+    config.ai.decisionModel = { ...config.ai.decisionModel, provider: spec.slice(0, separator), model: spec.slice(separator + 1) };
+  }
+
   private async buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig> {
     const provider = process.env.EXPLORBOT_AI_PROVIDER;
     const modelSpec = process.env.EXPLORBOT_AI_MODEL;