explorbot 0.5.4 → 0.5.6

package/boat/prima/README.md

@@ -17,25 +17,20 @@ npm install -g prima-cli      # or install it
 
 Prima also ships inside [explorbot](https://www.npmjs.com/package/explorbot), so `npx explorbot prima <command>` runs the same tool if you already have it.
 
-Requires Node.js 24+. Playwright browsers come from `npx playwright install chromium`.
+Requires Node.js 22.13+. Playwright browsers come from `npx playwright install chromium`.
 
 ## Session
 
-Prima needs a browser to drive. Either attach to a `playwright-cli` session:
+Prima drives a browser opened by `playwright-cli` and never launches one itself:
 
 ```bash
 playwright-cli open https://app.example.com
+prima-cli browser
 prima-cli check "the settings page saves a changed theme"
 playwright-cli close
 ```
 
-Or let prima own the browser:
-
-```bash
-prima-cli browser start --url https://app.example.com
-prima-cli do "open the account menu" "choose the settings entry"
-prima-cli browser stop
-```
+`browser` checks that a `playwright-cli` session is open and fails with the command to open one when it is not.
 
 ## Commands
 
@@ -50,7 +45,7 @@ prima-cli browser stop
 | `pw <fn>` | Run a Playwright function expression against the open page |
 | `status <hash>` | Show the artifacts and page detail recorded for an earlier command |
 | `report` | Turn every command of a session into one html and markdown report |
-| `browser start\|stop\|status\|list` | Manage the browsers prima drives |
+| `browser` | Check that a playwright-cli session is open, and fail with the command to open one when it is not |
 | `config` | Show models, config file and paths used by this run |
 
 `check` takes an outcome rather than a click path. It runs on the page you are already on and never reloads it, so an open dialog survives the check. Each `--expected` outcome comes back as PASSED, FAILED, CONTRADICTION or not verified — settled against a screenshot of the whole page, because what a user can see is the proof.

package/boat/prima/package.json

@@ -15,6 +15,6 @@
     "directory": "boat/prima"
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=22.13.0"
   }
 }

package/boat/prima/src/cli.ts

@@ -1,5 +1,4 @@
 import { Command } from 'commander';
-import { keepServerRunning } from '../../../src/browser-server.ts';
 import { RecommendedModelsCommand } from '../../../src/commands/recommended-models-command.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { isVerboseMode, setQuietMode } from '../../../src/utils/logger.ts';
@@ -22,8 +21,6 @@ function buildOptions(subcommand: any): PrimaOptions {
     noVision: options.vision === false,
     url: options.url,
     baseUrl: options.baseUrl,
-    show: options.show,
-    headless: options.headless,
     endpoint: options.endpoint,
     pwSession: options.pwSession,
   };
@@ -89,18 +86,6 @@ async function runPrima(options: any, command: string, run: (prima: Prima) => Pr
   process.exit(envelope.ok ? 0 : 1);
 }
 
-async function runBrowser(options: any, run: (prima: Prima) => Promise<boolean>): Promise<void> {
-  let ok = false;
-  try {
-    ok = await run(primaFor(options));
-  } catch (error) {
-    console.error(browserErrorMessage(error));
-    process.exit(1);
-  }
-
-  process.exit(ok ? 0 : 1);
-}
-
 export function createPrimaCommands(name = 'prima'): Command {
   const cmd = new Command(name);
   cmd.description('Drives a web app through described behaviour, not locators');
@@ -179,41 +164,14 @@ export function createPrimaCommands(name = 'prima'): Command {
       process.exit(0);
     });
 
-  const browser = cmd.command('browser').description('Manage the browsers prima drives');
-
-  addBrowserOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
-    .option('-s, --show', 'Launch the browser in a visible window')
-    .option('--headless', 'Launch the browser without a window')
-    .action(async (options) => {
-      await runBrowser(options, async (prima) => {
-        await prima.browserStart();
-        console.log(await prima.browserStatus());
-        return keepServerRunning(() => prima.browserStop());
-      });
-    });
-
-  addBrowserOptions(browser.command('stop').description('Stop the browser of this instance'))
-    .option('--all', 'Stop every running instance')
-    .action(async (options) => {
-      await runBrowser(options, async (prima) => {
-        const stopped = await prima.browserStop(options.all);
-        console.log(await prima.browserStatus());
-        return stopped;
-      });
-    });
-
-  addBrowserOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
-    await runBrowser(options, async (prima) => {
-      console.log(await prima.browserStatus());
-      return true;
-    });
-  });
-
-  addBrowserOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
-    await runBrowser(options, async (prima) => {
-      console.log(await prima.browserList());
-      return true;
-    });
+  addBrowserOptions(cmd.command('browser').description('Check that a playwright-cli session is open for prima to drive')).action(async (options) => {
+    try {
+      console.log(await primaFor(options).browserCheck());
+    } catch (error) {
+      console.error(browserErrorMessage(error));
+      process.exit(1);
+    }
+    process.exit(0);
   });
 
   return cmd;

package/boat/prima/src/prima.ts

@@ -12,7 +12,7 @@ import { JUDGE_PAGE_CAP, UNDECIDED } from '../../../src/ai/judge.ts';
 import { getPreviousResearch } from '../../../src/ai/researcher/cache.ts';
 import { actionRule, locatorRule } from '../../../src/ai/rules.ts';
 import { createAgentTools, createCodeceptJSTools, createRefTools } from '../../../src/ai/tools.ts';
-import { getAliveEndpoint, launchServer, listInstances, stopServer } from '../../../src/browser-server.ts';
+import { getAliveEndpoint, listInstances } from '../../../src/browser-server.ts';
 import { ConfigCommand } from '../../../src/commands/config-command.ts';
 import { ConfigMissingError, ConfigParser, EXPLORBOT_ENV_VARS, type ExplorbotConfig, outputPath } from '../../../src/config.ts';
 import { ExplorBot } from '../../../src/explorbot.ts';
@@ -73,7 +73,6 @@ export class Prima {
   private artifactsDir?: string;
   private hash?: string;
   private sessionUrl?: string;
-  private server: { close: () => Promise<void> } | null = null;
   private attached: string | null = null;
   private session: SessionRun | null = null;
 
@@ -503,25 +502,12 @@ export class Prima {
     return envelope;
   }
 
-  async browserStart(): Promise<void> {
-    const config = await this.loadConfig();
-    let show = config.playwright.show || false;
-    if (this.options.show) show = true;
-    if (this.options.headless) show = false;
-    this.server = await this.launchOwnServer({ browser: config.playwright.browser, show }, this.instanceName());
-  }
-
-  async browserStop(all = false): Promise<boolean> {
+  async browserCheck(): Promise<string> {
     await this.loadConfig();
-    if (this.attached) return false;
-
-    if (!all) return this.stopInstance(this.instanceName());
-
-    let stopped = false;
-    for (const instance of listInstances()) {
-      if (await this.stopInstance(instance.name)) stopped = true;
-    }
-    return stopped;
+    const { match, candidates, browser } = await this.discover();
+    await browser?.close().catch(() => {});
+    if (!match) throw this.missingSessionError(candidates);
+    return `browser: ${this.attachmentLabel(match)} at ${match.endpoint}`;
   }
 
   async config(json?: boolean): Promise<string> {
@@ -572,37 +558,6 @@ export class Prima {
     ].join('\n');
   }
 
-  async browserStatus(): Promise<string> {
-    await this.loadConfig();
-    const info = await this.instanceInfo();
-    const endpoint = await getAliveEndpoint(info.name);
-    const others = info.others.map((other) => other.name).join(', ') || 'none';
-    const lines = [`instance: ${info.name} (${info.tabs} ${pluralize(info.tabs, 'tab')}) | other instances: ${others}`];
-    if (!endpoint) lines.push('browser: not running');
-    if (endpoint) lines.push(`browser: running at ${endpoint}`);
-    return lines.join('\n');
-  }
-
-  async browserList(): Promise<string> {
-    await this.loadConfig();
-
-    const lines: string[] = [];
-    for (const instance of listInstances()) {
-      const endpoint = await getAliveEndpoint(instance.name);
-      if (!endpoint) continue;
-      lines.push(`prima --instance ${instance.name}  ${endpoint}`);
-    }
-
-    const discovery = await this.discover();
-    await discovery.browser?.close().catch(() => {});
-    for (const descriptor of discovery.candidates) {
-      lines.push(`playwright-cli --pw-session ${descriptor.title}  ${descriptor.endpoint}`);
-    }
-
-    if (!lines.length) return 'no browser instances running';
-    return lines.join('\n');
-  }
-
   async instanceInfo(): Promise<InstanceInfo> {
     const name = this.instanceName();
     const others = listInstances()
@@ -666,22 +621,27 @@ export class Prima {
     const { match, candidates, browser } = discovered || (await this.discover());
     if (match && (await this.attachToEndpoint(match, browser))) return;
 
-    if (!match && candidates.length) {
+    if (!match && candidates.length) throw this.missingSessionError(candidates);
+
+    if (await this.connectOwnInstance()) return;
+
+    throw this.missingSessionError(candidates);
+  }
+
+  private missingSessionError(candidates: PwServerDescriptor[]): Error {
+    if (candidates.length) {
       const titles = candidates.map((candidate) => candidate.title).join(', ');
-      throw new Error(dedent`
+      return new Error(dedent`
         Several playwright-cli sessions are open: ${titles}
         Pick one with --pw-session <title>.
       `);
     }
 
-    if (await this.connectOwnInstance()) return;
-
-    throw new Error(dedent`
-      No browser to drive for instance "${this.instanceName()}".
-      Open one first:
-        playwright-cli open <url>   prima attaches to this workspace session by default
-        prima browser start         starts a prima-owned browser instead
-      Prima never launches a browser implicitly.
+    return new Error(dedent`
+      No playwright-cli session is open for prima to drive.
+      Start one first:
+        playwright-cli open ${this.options.url || '<url>'}
+      Prima attaches to this workspace session by default and never launches a browser itself.
     `);
   }
 
@@ -751,20 +711,6 @@ export class Prima {
     return true;
   }
 
-  private async launchOwnServer(opts: { browser?: string; show?: boolean }, instance: string): Promise<{ close: () => Promise<void> }> {
-    return launchServer(opts, instance);
-  }
-
-  private async stopInstance(instance: string): Promise<boolean> {
-    if (instance === this.instanceName()) {
-      const server = this.server;
-      this.server = null;
-      await server?.close();
-    }
-
-    return stopServer(instance);
-  }
-
   private isUrlTarget(target: string): boolean {
     const value = target.trim();
     if (value.startsWith('/')) return true;
@@ -1229,8 +1175,6 @@ export interface PrimaOptions {
   noVision?: boolean;
   url?: string;
   baseUrl?: string;
-  show?: boolean;
-  headless?: boolean;
   endpoint?: string;
   pwSession?: string;
 }

package/dist/boat/prima/src/cli.js

@@ -1,5 +1,4 @@
 import { Command } from 'commander';
-import { keepServerRunning } from "../../../src/browser-server.js";
 import { RecommendedModelsCommand } from "../../../src/commands/recommended-models-command.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { isVerboseMode, setQuietMode } from "../../../src/utils/logger.js";
@@ -20,8 +19,6 @@ function buildOptions(subcommand) {
         noVision: options.vision === false,
         url: options.url,
         baseUrl: options.baseUrl,
-        show: options.show,
-        headless: options.headless,
         endpoint: options.endpoint,
         pwSession: options.pwSession,
     };
@@ -87,17 +84,6 @@ async function runPrima(options, command, run, opts = {}) {
     await prima.stop().catch(() => { });
     process.exit(envelope.ok ? 0 : 1);
 }
-async function runBrowser(options, run) {
-    let ok = false;
-    try {
-        ok = await run(primaFor(options));
-    }
-    catch (error) {
-        console.error(browserErrorMessage(error));
-        process.exit(1);
-    }
-    process.exit(ok ? 0 : 1);
-}
 export function createPrimaCommands(name = 'prima') {
     const cmd = new Command(name);
     cmd.description('Drives a web app through described behaviour, not locators');
@@ -163,37 +149,15 @@ export function createPrimaCommands(name = 'prima') {
             .catch((error) => browserErrorMessage(error)));
         process.exit(0);
     });
-    const browser = cmd.command('browser').description('Manage the browsers prima drives');
-    addBrowserOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
-        .option('-s, --show', 'Launch the browser in a visible window')
-        .option('--headless', 'Launch the browser without a window')
-        .action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            await prima.browserStart();
-            console.log(await prima.browserStatus());
-            return keepServerRunning(() => prima.browserStop());
-        });
-    });
-    addBrowserOptions(browser.command('stop').description('Stop the browser of this instance'))
-        .option('--all', 'Stop every running instance')
-        .action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            const stopped = await prima.browserStop(options.all);
-            console.log(await prima.browserStatus());
-            return stopped;
-        });
-    });
-    addBrowserOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            console.log(await prima.browserStatus());
-            return true;
-        });
-    });
-    addBrowserOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            console.log(await prima.browserList());
-            return true;
-        });
+    addBrowserOptions(cmd.command('browser').description('Check that a playwright-cli session is open for prima to drive')).action(async (options) => {
+        try {
+            console.log(await primaFor(options).browserCheck());
+        }
+        catch (error) {
+            console.error(browserErrorMessage(error));
+            process.exit(1);
+        }
+        process.exit(0);
     });
     return cmd;
 }

package/dist/boat/prima/src/prima.js

@@ -11,7 +11,7 @@ import { JUDGE_PAGE_CAP, UNDECIDED } from "../../../src/ai/judge.js";
 import { getPreviousResearch } from "../../../src/ai/researcher/cache.js";
 import { actionRule, locatorRule } from "../../../src/ai/rules.js";
 import { createAgentTools, createCodeceptJSTools, createRefTools } from "../../../src/ai/tools.js";
-import { getAliveEndpoint, launchServer, listInstances, stopServer } from "../../../src/browser-server.js";
+import { getAliveEndpoint, listInstances } from "../../../src/browser-server.js";
 import { ConfigCommand } from "../../../src/commands/config-command.js";
 import { ConfigMissingError, ConfigParser, EXPLORBOT_ENV_VARS, outputPath } from "../../../src/config.js";
 import { ExplorBot } from "../../../src/explorbot.js";
@@ -67,7 +67,6 @@ export class Prima {
     artifactsDir;
     hash;
     sessionUrl;
-    server = null;
     attached = null;
     session = null;
     constructor(options = {}) {
@@ -460,27 +459,13 @@ export class Prima {
             envelope.page.redirectedFrom = target;
         return envelope;
     }
-    async browserStart() {
-        const config = await this.loadConfig();
-        let show = config.playwright.show || false;
-        if (this.options.show)
-            show = true;
-        if (this.options.headless)
-            show = false;
-        this.server = await this.launchOwnServer({ browser: config.playwright.browser, show }, this.instanceName());
-    }
-    async browserStop(all = false) {
+    async browserCheck() {
         await this.loadConfig();
-        if (this.attached)
-            return false;
-        if (!all)
-            return this.stopInstance(this.instanceName());
-        let stopped = false;
-        for (const instance of listInstances()) {
-            if (await this.stopInstance(instance.name))
-                stopped = true;
-        }
-        return stopped;
+        const { match, candidates, browser } = await this.discover();
+        await browser?.close().catch(() => { });
+        if (!match)
+            throw this.missingSessionError(candidates);
+        return `browser: ${this.attachmentLabel(match)} at ${match.endpoint}`;
     }
     async config(json) {
         const [site] = listSites();
@@ -529,36 +514,6 @@ export class Prima {
             `upload:   TESTOMATIO=<apiKey> npx @testomatio/reporter replay ${file}`,
         ].join('\n');
     }
-    async browserStatus() {
-        await this.loadConfig();
-        const info = await this.instanceInfo();
-        const endpoint = await getAliveEndpoint(info.name);
-        const others = info.others.map((other) => other.name).join(', ') || 'none';
-        const lines = [`instance: ${info.name} (${info.tabs} ${pluralize(info.tabs, 'tab')}) | other instances: ${others}`];
-        if (!endpoint)
-            lines.push('browser: not running');
-        if (endpoint)
-            lines.push(`browser: running at ${endpoint}`);
-        return lines.join('\n');
-    }
-    async browserList() {
-        await this.loadConfig();
-        const lines = [];
-        for (const instance of listInstances()) {
-            const endpoint = await getAliveEndpoint(instance.name);
-            if (!endpoint)
-                continue;
-            lines.push(`prima --instance ${instance.name}  ${endpoint}`);
-        }
-        const discovery = await this.discover();
-        await discovery.browser?.close().catch(() => { });
-        for (const descriptor of discovery.candidates) {
-            lines.push(`playwright-cli --pw-session ${descriptor.title}  ${descriptor.endpoint}`);
-        }
-        if (!lines.length)
-            return 'no browser instances running';
-        return lines.join('\n');
-    }
     async instanceInfo() {
         const name = this.instanceName();
         const others = listInstances()
@@ -621,21 +576,25 @@ export class Prima {
         const { match, candidates, browser } = discovered || (await this.discover());
         if (match && (await this.attachToEndpoint(match, browser)))
             return;
-        if (!match && candidates.length) {
+        if (!match && candidates.length)
+            throw this.missingSessionError(candidates);
+        if (await this.connectOwnInstance())
+            return;
+        throw this.missingSessionError(candidates);
+    }
+    missingSessionError(candidates) {
+        if (candidates.length) {
             const titles = candidates.map((candidate) => candidate.title).join(', ');
-            throw new Error(dedent `
+            return new Error(dedent `
         Several playwright-cli sessions are open: ${titles}
         Pick one with --pw-session <title>.
       `);
         }
-        if (await this.connectOwnInstance())
-            return;
-        throw new Error(dedent `
-      No browser to drive for instance "${this.instanceName()}".
-      Open one first:
-        playwright-cli open <url>   prima attaches to this workspace session by default
-        prima browser start         starts a prima-owned browser instead
-      Prima never launches a browser implicitly.
+        return new Error(dedent `
+      No playwright-cli session is open for prima to drive.
+      Start one first:
+        playwright-cli open ${this.options.url || '<url>'}
+      Prima attaches to this workspace session by default and never launches a browser itself.
     `);
     }
     async discover(descriptors = readDescriptors()) {
@@ -703,17 +662,6 @@ export class Prima {
         this.session = { key: this.instanceName(), endpoint, title: `prima instance "${this.instanceName()}"` };
         return true;
     }
-    async launchOwnServer(opts, instance) {
-        return launchServer(opts, instance);
-    }
-    async stopInstance(instance) {
-        if (instance === this.instanceName()) {
-            const server = this.server;
-            this.server = null;
-            await server?.close();
-        }
-        return stopServer(instance);
-    }
     isUrlTarget(target) {
         const value = target.trim();
         if (value.startsWith('/'))

package/dist/models.json

@@ -2,7 +2,8 @@
   "openrouter": {
     "model": "openai/gpt-oss-20b:nitro",
     "visionModel": "openai/gpt-5.6-luna",
-    "agenticModel": "openai/gpt-5.6-luna"
+    "agenticModel": "anthropic/claude-haiku-5.5",
+    "decisionModel": "typesafe/jev-latest"
   },
   "poolside": {
     "model": "poolside/laguna-xs-2.1"
@@ -14,13 +15,13 @@
   },
   "openai": {
     "model": "gpt-5-nano",
-    "visionModel": "gpt-5.6-luna",
-    "agenticModel": "gpt-5.6-luna"
+    "visionModel": "gpt-6-luna",
+    "agenticModel": "gpt-6-luna"
   },
   "anthropic": {
-    "model": "claude-haiku-4-5-20251001",
-    "visionModel": "claude-haiku-4-5-20251001",
-    "agenticModel": "claude-haiku-4-5-20251001"
+    "model": "claude-haiku-5-5",
+    "visionModel": "claude-haiku-5-5",
+    "agenticModel": "claude-haiku-5-5"
   },
   "mistral": {
     "model": "mistral-small-latest",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/dist/src/ai/navigator.js

@@ -7,6 +7,7 @@ import { normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { getCliName } from "../utils/cli-name.js";
 import { extractCodeBlocks } from '../utils/code-extractor.js';
+import { isLoginPage } from "../utils/error-page.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -15,7 +16,7 @@ import { normalizeInlineText } from "../utils/strings.js";
 import { extractStatePath, isSameHostFamily, matchesNavigationUrl } from '../utils/url-matcher.js';
 import { JUDGE_PAGE_CAP, UNDECIDED } from "./judge.js";
 import { Researcher } from "./researcher.js";
-import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
+import { actionRule, credentialsRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from "./tools.js";
 const debugLog = createDebug('explorbot:navigator');
@@ -46,7 +47,7 @@ class Navigator {
     NEVER use executeScript, executeAsyncScript, or any JS evaluation to change the URL, bypass redirects, or fake the page state.
     If the target URL redirects to an authentication/login page, DO NOT try to force the original URL. Instead:
       1. Look for credentials in the provided knowledge/hint context and perform a real login through the form.
-      2. If no credentials are available, ask the user for credentials or ask the user to log in manually.
+      2. If no credentials are available, stop and name the credentials that are missing. Never guess them.
     A redirect to /login, /sign_in, /auth, or similar is a signal that authentication is required — treat it as such, never as an obstacle to bypass.
   </constraints>
   `;
@@ -344,6 +345,9 @@ class Navigator {
         if (!experience && !actionResult.isInsideIframe) {
             experience = this.experienceTracker.renderExperienceFor(actionResult);
         }
+        let credentials = '';
+        if (isLoginPage(actionResult))
+            credentials = credentialsRule;
         return dedent `
       <message>
         ${message}
@@ -369,6 +373,8 @@ class Navigator {
 
       ${unexpectedPopupRule}
 
+      ${credentials}
+
       ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
 
       ${experience}

package/dist/src/ai/rules.d.ts

@@ -3,6 +3,7 @@ export declare const locatorRule: string;
 export declare const drillLocatorRule: string;
 export declare const fileUploadRule: string;
 export declare const formRequirementsRule: string;
+export declare const credentialsRule: string;
 export declare const protectionRule: string;
 export declare const dataProtectionRules: string;
 export declare const capabilityGroundingRule: string;

package/dist/src/ai/rules.js

@@ -138,6 +138,13 @@ export const formRequirementsRule = dedent `
   Before filling a form that persists data (create/update), read each control's requirements (required, type/format, length, placeholder/aria-describedby hints) from <page_aria> and page HTML — call context() if not visible — and enter values that satisfy them. Search/filter/sort forms that only change the view do not need this.
   </form_requirements>
 `;
+export const credentialsRule = dedent `
+  <credentials>
+  Sign in to an existing account only with credentials present in the provided context (message, knowledge, experience).
+  Never invent, guess, or try default, common, or placeholder credentials for an existing account.
+  If the required credentials are not provided, call stop() and name what is missing — do not submit the form.
+  </credentials>
+`;
 // in rage mode we do not protect from irreversible actions
 export const protectionRule = dedent `
   <important>

package/dist/src/commands/init-command.js

@@ -225,7 +225,10 @@ export function modelLines(provider, only) {
     let selected = roles;
     if (only)
         selected = roles.filter(([role]) => only.includes(role));
-    return selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+    const lines = selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`);
+    if (!only && recommended.decisionModel)
+        lines.push(`    // decision model judging ambiguous outcomes\n    decisionModel: { provider: '${provider}', model: '${recommended.decisionModel}' },`);
+    return lines.join('\n');
 }
 function globalConfigTemplate(provider) {
     const { envKey } = PROVIDERS[provider];

package/dist/src/commands/recommended-models-command.js

@@ -44,6 +44,8 @@ export class RecommendedModelsCommand extends BaseCommand {
                 if (!roles[role])
                     models.push([label, chalk.dim('not served, pair with another provider')]);
             }
+            if (roles.decisionModel)
+                models.push(['decisionModel (judge)', roles.decisionModel]);
             lines.push(...renderSection('models', models, 2));
             const envKey = PROVIDERS[provider]?.envKey;
             if (!envKey) {
@@ -61,6 +63,8 @@ export class RecommendedModelsCommand extends BaseCommand {
                 env.push([label, `${ROLES[role].env}=${provider}/${roles[role]}`]);
                 label = '';
             }
+            if (roles.decisionModel)
+                env.push(['decision', `EXPLORBOT_DECISION_MODEL=${provider}/${roles.decisionModel}`]);
             lines.push(...renderSection('env variables', env, 2));
         }
         const modelVars = ['EXPLORBOT_AI_PROVIDER', ...MODEL_ENV_VARS];

package/dist/src/config.js

@@ -137,6 +137,10 @@ export class ConfigParser {
                 sourcePath = join(outputRoot, 'explorbot.config.js');
                 log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
             }
+            const configuredUrl = loadedConfig?.playwright?.url || loadedConfig?.web?.url || '';
+            if (!this.runBase && resolvedPath && !isGlobalConfigPath(resolvedPath) && URL.canParse(configuredUrl)) {
+                this.runBase = parseRunBase(configuredUrl);
+            }
             let config = this.resolveConfig(loadedConfig);
             await resolveConfigModels(config.ai);
             this.site = null;
@@ -377,6 +381,8 @@ export class ConfigParser {
             ai.agenticModel = await resolveModel(agenticSpec, 'agenticModel');
         if (!agenticSpec && recommended.agenticModel)
             ai.agenticModel = await resolveModel(provider, 'agenticModel');
+        if (recommended.decisionModel)
+            ai.decisionModel = { provider: provider, model: recommended.decisionModel };
         const dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
         if (process.env.EXPLORBOT_OUTPUT)
             dirs.output = '.';

package/dist/src/utils/error-page.d.ts

@@ -3,6 +3,7 @@ import type { WebPageState } from '../state-manager.js';
 export type PageCondition = 'ok' | 'loading' | 'error';
 export declare function detectPageCondition(actionResult: ActionResult): PageCondition;
 export declare function isErrorPage(actionResult: ActionResult): boolean;
+export declare function isLoginPage(actionResult: ActionResult): boolean;
 export declare function getStateErrorPageError(state: WebPageState | null | undefined): ErrorPageError | null;
 export declare class ErrorPageError extends Error {
     readonly url: string;

package/dist/src/utils/error-page.js

@@ -1,8 +1,11 @@
 import { ActionResult } from '../action-result.js';
 import { isBodyEmpty } from './html.js';
+import { extractStatePath } from './url-matcher.js';
 const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
 const SMALL_PAGE_THRESHOLD = 500;
 const LOADING_WORD = /\bloading\b/i;
+const PASSWORD_INPUT = /<input\b[^>]*\btype\s*=\s*["']?password\b/i;
+const AUTH_PATH = /\b(log[-_]?in|sign[-_]?in|auth)\b/i;
 export function detectPageCondition(actionResult) {
     if (actionResult.httpStatus && actionResult.httpStatus >= 400)
         return 'error';
@@ -32,6 +35,11 @@ export function detectPageCondition(actionResult) {
 export function isErrorPage(actionResult) {
     return detectPageCondition(actionResult) === 'error';
 }
+export function isLoginPage(actionResult) {
+    if (PASSWORD_INPUT.test(actionResult.html || ''))
+        return true;
+    return AUTH_PATH.test(extractStatePath(actionResult.url || '').split('?')[0]);
+}
 export function getStateErrorPageError(state) {
     if (!state)
         return null;

package/dist/src/utils/mdq/query.d.ts

@@ -57,6 +57,8 @@ export declare class MarkdownQuery {
     sectionsOf(candidates: MatchedRange[], segment: QuerySegment): MatchedRange[];
     itemsOf(candidates: MatchedRange[]): MatchedRange[];
     expandSections(matches: MatchedRange[]): MatchedRange[];
+    evaluate(candidates: MatchedRange[], expression: QueryExpression): MatchedRange[];
+    union(results: MatchedRange[][]): MatchedRange[];
     narrow(matches: MatchedRange[], segment: QuerySegment): MatchedRange[];
     filterByText(matches: MatchedRange[], segment: QuerySegment): MatchedRange[];
     matchText(text: string, matcher: TextMatcher): boolean;
@@ -77,7 +79,7 @@ export declare class MdqOperationError extends MdqError {
     constructor(message: string);
 }
 export declare function mdq(source: Markdown): MarkdownQuery;
-export declare function parseQuery(input: string): QuerySegment[];
+export declare function parseQuery(input: string): QueryExpression;
 export declare function buildTokenIndex(source: string): MatchedRange[];
 export type Markdown = string | MarkdownQuery;
 export type Matcher = string | RegExp | ((text: string) => boolean);
@@ -92,6 +94,7 @@ export interface TextMatcher {
     flags?: string;
     predicate?: (text: string) => boolean;
 }
+export type QueryExpression = QuerySegment[][][];
 export interface QuerySegment {
     selector: SelectorType;
     textMatch?: TextMatcher;

package/dist/src/utils/mdq/query.js

@@ -9,10 +9,13 @@ export class MarkdownQuery {
         this.matches = matches || buildTokenIndex(source);
     }
     query(selector, matcher) {
-        const segments = parseQuery(selector);
-        if (matcher !== undefined && segments.length > 0)
-            segments[segments.length - 1].textMatch = this.valueMatcher(matcher);
-        return new MarkdownQuery(this.source, this.run(this.expandSections(this.matches), segments));
+        const expression = parseQuery(selector);
+        for (const chain of expression.flat()) {
+            const last = chain.at(-1);
+            if (matcher !== undefined && last)
+                last.textMatch = this.valueMatcher(matcher);
+        }
+        return new MarkdownQuery(this.source, this.evaluate(this.expandSections(this.matches), expression));
     }
     section(matcher, options) {
         return this.query(`section${options?.depth || ''}`, matcher);
@@ -299,6 +302,27 @@ export class MarkdownQuery {
         }
         return expanded;
     }
+    evaluate(candidates, expression) {
+        const results = [];
+        for (const operands of expression) {
+            const matched = operands.map((chain) => this.run(candidates, chain));
+            if (matched.some((ranges) => ranges.length === 0))
+                continue;
+            results.push(...matched);
+        }
+        return this.union(results);
+    }
+    union(results) {
+        if (results.length === 1)
+            return results[0];
+        const unique = new Map();
+        for (const range of results.flat()) {
+            const key = `${range.start}:${range.length}:${Boolean(range.innerTokens)}`;
+            if (!unique.has(key))
+                unique.set(key, range);
+        }
+        return [...unique.values()].sort((a, b) => a.start - b.start || b.length - a.length);
+    }
     narrow(matches, segment) {
         if (segment.index !== null) {
             let index = segment.index;
@@ -390,10 +414,24 @@ export function mdq(source) {
     return new MarkdownQuery(String(source));
 }
 export function parseQuery(input) {
-    const segments = [];
+    const expression = [[[]]];
+    let chain = expression[0][0];
     SEGMENT.lastIndex = 0;
     while (SEGMENT.lastIndex < input.length) {
         const at = SEGMENT.lastIndex;
+        OPERATOR.lastIndex = at;
+        const operator = OPERATOR.exec(input);
+        if (operator) {
+            if (chain.length === 0)
+                throw new MdqSelectorError(`Empty selector before ${operator[1]}`, at);
+            chain = [];
+            if (operator[1] === '||')
+                expression.push([chain]);
+            if (operator[1] === '&&')
+                expression[expression.length - 1].push(chain);
+            SEGMENT.lastIndex = OPERATOR.lastIndex;
+            continue;
+        }
         const match = SEGMENT.exec(input);
         if (!match)
             throw new MdqSelectorError(`Unexpected character "${input[at]}" in selector`, at);
@@ -424,9 +462,11 @@ export function parseQuery(input) {
             if (to)
                 segment.slice.to = Number.parseInt(to, 10);
         }
-        segments.push(segment);
+        chain.push(segment);
     }
-    return segments;
+    if (expression.flat().length > 1 && chain.length === 0)
+        throw new MdqSelectorError('Empty selector after operator', input.length);
+    return expression;
 }
 export function buildTokenIndex(source) {
     const { body, offset } = MarkdownEditor.splitFrontmatter(source);
@@ -449,3 +489,4 @@ export function buildTokenIndex(source) {
 const SELECTOR_NAMES = new Set(['section', 'heading', 'paragraph', 'table', 'list', 'item', 'code', 'blockquote', 'hr', 'html', 'comment']);
 const TOKEN_ALIASES = { item: 'list_item' };
 const SEGMENT = /(\s*\.?)([A-Za-z]\w*)(?:\((!?)(~?)(?:"((?:[^"\\]|\\.)*)"|\/((?:[^/\\]|\\.)*)\/([a-z]*))\))?((?:\[[^\]]*\])*)\s*/y;
+const OPERATOR = /\s*(&&|\|\|)\s*/y;

package/docs/basics/getting-started.md

@@ -39,7 +39,8 @@ export default {
   ai: {
     model: 'openrouter/openai/gpt-oss-20b:nitro',
     visionModel: 'openrouter/openai/gpt-5.6-luna',
-    agenticModel: 'openrouter/openai/gpt-5.6-luna',
+    agenticModel: 'openrouter/anthropic/claude-haiku-5.5',
+    decisionModel: { provider: 'openrouter', model: 'typesafe/jev-latest' },
   },
 };
 ```

package/docs/basics/providers.md

@@ -56,7 +56,8 @@ export default {
   ai: {
     model: openrouter('openai/gpt-oss-20b:nitro'),
     visionModel: openrouter('openai/gpt-5.6-luna'),
-    agenticModel: openrouter('openai/gpt-5.6-luna'),
+    agenticModel: openrouter('anthropic/claude-haiku-5.5'),
+    decisionModel: { provider: 'openrouter', model: 'typesafe/jev-latest' },
   },
 };
 ```
@@ -123,8 +124,8 @@ Set the recommended models in the exported config:
 export default {
   ai: {
     model: openai('gpt-5-nano'),
-    visionModel: openai('gpt-5.6-luna'),
-    agenticModel: openai('gpt-5.6-luna'),
+    visionModel: openai('gpt-6-luna'),
+    agenticModel: openai('gpt-6-luna'),
   },
 };
 ```
@@ -156,9 +157,9 @@ Set the recommended model in the exported config:
 ```javascript
 export default {
   ai: {
-    model: anthropic('claude-haiku-4-5-20251001'),
-    visionModel: anthropic('claude-haiku-4-5-20251001'),
-    agenticModel: anthropic('claude-haiku-4-5-20251001'),
+    model: anthropic('claude-haiku-5-5'),
+    visionModel: anthropic('claude-haiku-5-5'),
+    agenticModel: anthropic('claude-haiku-5-5'),
   },
 };
 ```

package/docs/reference/commands.md

@@ -733,16 +733,16 @@ html: /home/you/.explorbot/sites/app.example.com/output/prima/2026-08-04T10-04-2
 
 ### Browsers and sessions
 
-Prima never launches a browser implicitly. Open one first:
+Prima never launches a browser. Open a playwright-cli session first, and check prima sees it:
 
 ```bash
 playwright-cli open https://app.example.com   # the session prima attaches to by default
-npx explorbot prima browser start             # a prima-owned browser instead
+npx explorbot prima browser                   # prints the session, or fails with the command to open one
 ```
 
-By default prima attaches to the playwright-cli browser of the current workspace and works on the tabs it already has open — driving the same session from both tools is the intended usage. Stopping prima disconnects from an attached browser; it never closes it. `prima browser list` shows both kinds of browser, and the `### Instance` block names the one you are on.
+By default prima attaches to the playwright-cli browser of the current workspace and works on the tabs it already has open — driving the same session from both tools is the intended usage. Stopping prima disconnects from an attached browser; it never closes it. The `### Instance` block names the browser you are on.
 
-Prima reaches every browser over a Playwright browser-server endpoint — a playwright-cli session, an `--endpoint`, or a `prima browser start` instance — and that client needs the Node build, which is what `npx explorbot prima` and the published `prima` bin run on. Driving a browser by running the CLI from source under Bun does not connect.
+Prima reaches every browser over a Playwright browser-server endpoint — a playwright-cli session, an `--endpoint`, or an `explorbot browser start` instance — and that client needs the Node build, which is what `npx explorbot prima` and the published `prima` bin run on. Driving a browser by running the CLI from source under Bun does not connect.
 
 Every command takes these:
 
@@ -769,8 +769,6 @@ A few commands add their own:
 | `research` | `--data` | Include data extraction in the map |
 | `research` | `--deep` | Expand hidden elements for a deeper map |
 | `research` | `--fresh` | Ignore the cached map and research the page again |
-| `browser start` | `-s, --show` / `--headless` | Launch the browser with or without a window |
-| `browser stop` | `--all` | Stop every running instance |
 
 Prima carries no logging flags of its own. `DEBUG` in front of a command prints everything the run does — config and browser attachment, every step as it executes, and the debug stream of the agents behind it:
 

package/docs/workflow/agentic-usage.md

@@ -103,7 +103,7 @@ On its own, without a provider, `EXPLORBOT_AI_MODEL` must carry the provider as
 ```
 openrouter/openai/gpt-oss-120b:nitro   → openrouter, model "openai/gpt-oss-120b:nitro"
 groq/openai/gpt-oss-20b                → groq, model "openai/gpt-oss-20b"
-anthropic/claude-haiku-4-5-20251001    → anthropic, model "claude-haiku-4-5-20251001"
+anthropic/claude-haiku-5-5             → anthropic, model "claude-haiku-5-5"
 ```
 
 `EXPLORBOT_VISION_MODEL` and `EXPLORBOT_AGENTIC_MODEL` override those roles the same way — a provider name for its recommendation, or `provider/model-id` to pin one. Mix the forms to take a provider's recommendations and override one role:

package/models.json

@@ -2,7 +2,8 @@
   "openrouter": {
     "model": "openai/gpt-oss-20b:nitro",
     "visionModel": "openai/gpt-5.6-luna",
-    "agenticModel": "openai/gpt-5.6-luna"
+    "agenticModel": "anthropic/claude-haiku-5.5",
+    "decisionModel": "typesafe/jev-latest"
   },
   "poolside": {
     "model": "poolside/laguna-xs-2.1"
@@ -14,13 +15,13 @@
   },
   "openai": {
     "model": "gpt-5-nano",
-    "visionModel": "gpt-5.6-luna",
-    "agenticModel": "gpt-5.6-luna"
+    "visionModel": "gpt-6-luna",
+    "agenticModel": "gpt-6-luna"
   },
   "anthropic": {
-    "model": "claude-haiku-4-5-20251001",
-    "visionModel": "claude-haiku-4-5-20251001",
-    "agenticModel": "claude-haiku-4-5-20251001"
+    "model": "claude-haiku-5-5",
+    "visionModel": "claude-haiku-5-5",
+    "agenticModel": "claude-haiku-5-5"
   },
   "mistral": {
     "model": "mistral-small-latest",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/src/ai/navigator.ts

@@ -13,6 +13,7 @@ import { type StateManager, normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
+import { isLoginPage } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -24,7 +25,7 @@ import type { Conversation } from './conversation.js';
 import { type Decision, JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
 import type { Provider } from './provider.js';
 import { Researcher } from './researcher.ts';
-import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
+import { actionRule, credentialsRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from './tools.ts';
 
@@ -59,7 +60,7 @@ class Navigator implements Agent {
     NEVER use executeScript, executeAsyncScript, or any JS evaluation to change the URL, bypass redirects, or fake the page state.
     If the target URL redirects to an authentication/login page, DO NOT try to force the original URL. Instead:
       1. Look for credentials in the provided knowledge/hint context and perform a real login through the form.
-      2. If no credentials are available, ask the user for credentials or ask the user to log in manually.
+      2. If no credentials are available, stop and name the credentials that are missing. Never guess them.
     A redirect to /login, /sign_in, /auth, or similar is a signal that authentication is required — treat it as such, never as an obstacle to bypass.
   </constraints>
   `;
@@ -381,6 +382,9 @@ class Navigator implements Agent {
       experience = this.experienceTracker.renderExperienceFor(actionResult);
     }
 
+    let credentials = '';
+    if (isLoginPage(actionResult)) credentials = credentialsRule;
+
     return dedent`
       <message>
         ${message}
@@ -406,6 +410,8 @@ class Navigator implements Agent {
 
       ${unexpectedPopupRule}
 
+      ${credentials}
+
       ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
 
       ${experience}

package/src/ai/rules.ts

@@ -147,6 +147,14 @@ export const formRequirementsRule = dedent`
   </form_requirements>
 `;
 
+export const credentialsRule = dedent`
+  <credentials>
+  Sign in to an existing account only with credentials present in the provided context (message, knowledge, experience).
+  Never invent, guess, or try default, common, or placeholder credentials for an existing account.
+  If the required credentials are not provided, call stop() and name what is missing — do not submit the form.
+  </credentials>
+`;
+
 // in rage mode we do not protect from irreversible actions
 export const protectionRule = dedent`
   <important>

package/src/commands/init-command.ts

@@ -260,7 +260,9 @@ export function modelLines(provider: string, only?: ModelRole[]): string {
   let selected = roles;
   if (only) selected = roles.filter(([role]) => only.includes(role));
 
-  return selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+  const lines = selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`);
+  if (!only && recommended.decisionModel) lines.push(`    // decision model judging ambiguous outcomes\n    decisionModel: { provider: '${provider}', model: '${recommended.decisionModel}' },`);
+  return lines.join('\n');
 }
 
 function globalConfigTemplate(provider: string): string {

package/src/commands/recommended-models-command.ts

@@ -52,6 +52,7 @@ export class RecommendedModelsCommand extends BaseCommand {
         if (roles[role]) models.push([label, roles[role]]);
         if (!roles[role]) models.push([label, chalk.dim('not served, pair with another provider')]);
       }
+      if (roles.decisionModel) models.push(['decisionModel (judge)', roles.decisionModel]);
       lines.push(...renderSection('models', models, 2));
 
       const envKey = PROVIDERS[provider]?.envKey;
@@ -70,6 +71,7 @@ export class RecommendedModelsCommand extends BaseCommand {
         env.push([label, `${ROLES[role].env}=${provider}/${roles[role]}`]);
         label = '';
       }
+      if (roles.decisionModel) env.push(['decision', `EXPLORBOT_DECISION_MODEL=${provider}/${roles.decisionModel}`]);
       lines.push(...renderSection('env variables', env, 2));
     }
 

package/src/config.ts

@@ -420,6 +420,11 @@ export class ConfigParser {
         log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
       }
 
+      const configuredUrl = loadedConfig?.playwright?.url || loadedConfig?.web?.url || '';
+      if (!this.runBase && resolvedPath && !isGlobalConfigPath(resolvedPath) && URL.canParse(configuredUrl)) {
+        this.runBase = parseRunBase(configuredUrl);
+      }
+
       let config = this.resolveConfig(loadedConfig as ExplorbotConfig);
       await resolveConfigModels(config.ai);
       this.site = null;
@@ -675,6 +680,8 @@ export class ConfigParser {
     if (agenticSpec) ai.agenticModel = await resolveModel(agenticSpec, 'agenticModel');
     if (!agenticSpec && recommended.agenticModel) ai.agenticModel = await resolveModel(provider!, 'agenticModel');
 
+    if (recommended.decisionModel) ai.decisionModel = { provider: provider!, model: recommended.decisionModel };
+
     const dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
     if (process.env.EXPLORBOT_OUTPUT) dirs.output = '.';
 

package/src/utils/error-page.ts

@@ -1,11 +1,14 @@
 import { ActionResult } from '../action-result.js';
 import type { WebPageState } from '../state-manager.js';
 import { isBodyEmpty } from './html.js';
+import { extractStatePath } from './url-matcher.js';
 
 const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
 
 const SMALL_PAGE_THRESHOLD = 500;
 const LOADING_WORD = /\bloading\b/i;
+const PASSWORD_INPUT = /<input\b[^>]*\btype\s*=\s*["']?password\b/i;
+const AUTH_PATH = /\b(log[-_]?in|sign[-_]?in|auth)\b/i;
 
 export type PageCondition = 'ok' | 'loading' | 'error';
 
@@ -40,6 +43,11 @@ export function isErrorPage(actionResult: ActionResult): boolean {
   return detectPageCondition(actionResult) === 'error';
 }
 
+export function isLoginPage(actionResult: ActionResult): boolean {
+  if (PASSWORD_INPUT.test(actionResult.html || '')) return true;
+  return AUTH_PATH.test(extractStatePath(actionResult.url || '').split('?')[0]);
+}
+
 export function getStateErrorPageError(state: WebPageState | null | undefined): ErrorPageError | null {
   if (!state) return null;
   const actionResult = ActionResult.fromState(state);

package/src/utils/mdq/query.ts

@@ -13,9 +13,12 @@ export class MarkdownQuery {
   }
 
   query(selector: string, matcher?: Matcher): MarkdownQuery {
-    const segments = parseQuery(selector);
-    if (matcher !== undefined && segments.length > 0) segments[segments.length - 1].textMatch = this.valueMatcher(matcher);
-    return new MarkdownQuery(this.source, this.run(this.expandSections(this.matches), segments));
+    const expression = parseQuery(selector);
+    for (const chain of expression.flat()) {
+      const last = chain.at(-1);
+      if (matcher !== undefined && last) last.textMatch = this.valueMatcher(matcher);
+    }
+    return new MarkdownQuery(this.source, this.evaluate(this.expandSections(this.matches), expression));
   }
 
   section(matcher?: Matcher, options?: SelectorOptions): MarkdownQuery {
@@ -364,6 +367,27 @@ export class MarkdownQuery {
     return expanded;
   }
 
+  private evaluate(candidates: MatchedRange[], expression: QueryExpression): MatchedRange[] {
+    const results: MatchedRange[][] = [];
+    for (const operands of expression) {
+      const matched = operands.map((chain) => this.run(candidates, chain));
+      if (matched.some((ranges) => ranges.length === 0)) continue;
+      results.push(...matched);
+    }
+    return this.union(results);
+  }
+
+  private union(results: MatchedRange[][]): MatchedRange[] {
+    if (results.length === 1) return results[0];
+
+    const unique = new Map<string, MatchedRange>();
+    for (const range of results.flat()) {
+      const key = `${range.start}:${range.length}:${Boolean(range.innerTokens)}`;
+      if (!unique.has(key)) unique.set(key, range);
+    }
+    return [...unique.values()].sort((a, b) => a.start - b.start || b.length - a.length);
+  }
+
   private narrow(matches: MatchedRange[], segment: QuerySegment): MatchedRange[] {
     if (segment.index !== null) {
       let index = segment.index;
@@ -449,12 +473,24 @@ export function mdq(source: Markdown): MarkdownQuery {
   return new MarkdownQuery(String(source));
 }
 
-export function parseQuery(input: string): QuerySegment[] {
-  const segments: QuerySegment[] = [];
+export function parseQuery(input: string): QueryExpression {
+  const expression: QueryExpression = [[[]]];
+  let chain = expression[0][0];
   SEGMENT.lastIndex = 0;
 
   while (SEGMENT.lastIndex < input.length) {
     const at = SEGMENT.lastIndex;
+    OPERATOR.lastIndex = at;
+    const operator = OPERATOR.exec(input);
+    if (operator) {
+      if (chain.length === 0) throw new MdqSelectorError(`Empty selector before ${operator[1]}`, at);
+      chain = [];
+      if (operator[1] === '||') expression.push([chain]);
+      if (operator[1] === '&&') expression[expression.length - 1].push(chain);
+      SEGMENT.lastIndex = OPERATOR.lastIndex;
+      continue;
+    }
+
     const match = SEGMENT.exec(input);
     if (!match) throw new MdqSelectorError(`Unexpected character "${input[at]}" in selector`, at);
 
@@ -484,10 +520,11 @@ export function parseQuery(input: string): QuerySegment[] {
       if (to) segment.slice.to = Number.parseInt(to, 10);
     }
 
-    segments.push(segment);
+    chain.push(segment);
   }
 
-  return segments;
+  if (expression.flat().length > 1 && chain.length === 0) throw new MdqSelectorError('Empty selector after operator', input.length);
+  return expression;
 }
 
 export function buildTokenIndex(source: string): MatchedRange[] {
@@ -516,6 +553,8 @@ const TOKEN_ALIASES: Record<string, string> = { item: 'list_item' };
 
 const SEGMENT = /(\s*\.?)([A-Za-z]\w*)(?:\((!?)(~?)(?:"((?:[^"\\]|\\.)*)"|\/((?:[^/\\]|\\.)*)\/([a-z]*))\))?((?:\[[^\]]*\])*)\s*/y;
 
+const OPERATOR = /\s*(&&|\|\|)\s*/y;
+
 export type Markdown = string | MarkdownQuery;
 
 export type Matcher = string | RegExp | ((text: string) => boolean);
@@ -534,6 +573,8 @@ export interface TextMatcher {
   predicate?: (text: string) => boolean;
 }
 
+export type QueryExpression = QuerySegment[][][];
+
 export interface QuerySegment {
   selector: SelectorType;
   textMatch?: TextMatcher;