explorbot 0.4.5 → 0.4.6

package/dist/boat/api-tester/src/commands/know-command.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { tag } from "../../../../src/utils/logger.js";
+import { ApiCommand } from "./api-command.js";
+export class KnowCommand extends ApiCommand {
+    name = 'know';
+    aliases = ['add-knowledge'];
+    description = 'Add API knowledge for an endpoint';
+    knowledge = '';
+    async execute(endpoint) {
+        if (!this.knowledge) {
+            throw new Error('Description is required.');
+        }
+        const knowledgeDir = await this.resolveKnowledgeDir();
+        fs.mkdirSync(knowledgeDir, { recursive: true });
+        const filename = endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_') || 'general';
+        const filePath = path.join(knowledgeDir, `${filename}.md`);
+        if (fs.existsSync(filePath)) {
+            fs.appendFileSync(filePath, `\n---\n${this.knowledge}\n`, 'utf8');
+            tag('success').log(`Updated: ${filePath}`);
+            return;
+        }
+        fs.writeFileSync(filePath, `---\nendpoint: "${endpoint}"\n---\n${this.knowledge}\n`, 'utf8');
+        tag('success').log(`Created: ${filePath}`);
+    }
+    async resolveKnowledgeDir() {
+        const parser = this.bot.getConfigParser();
+        const options = this.bot.getOptions();
+        try {
+            await parser.loadConfig(options);
+            return parser.getKnowledgeDir();
+        }
+        catch {
+            if (options.path)
+                return path.join(path.resolve(options.path), 'knowledge');
+            return 'knowledge';
+        }
+    }
+}

package/dist/boat/api-tester/src/commands/plan-command.js

@@ -0,0 +1,37 @@
+import { tag } from "../../../../src/utils/logger.js";
+import { printNextSteps, relativeToCwd } from "../../../../src/utils/next-steps.js";
+import { ApiCommand } from "./api-command.js";
+export class PlanCommand extends ApiCommand {
+    name = 'plan';
+    description = 'Generate a test plan for an API endpoint';
+    style;
+    fresh = false;
+    async execute(endpoint) {
+        await this.bot.plan(endpoint, { style: this.style, fresh: this.fresh });
+        const plan = this.bot.getCurrentPlan();
+        if (!plan?.tests.length) {
+            throw new Error('No test scenarios generated.');
+        }
+        const lines = [`Plan: ${plan.title} (${plan.tests.length} tests)`];
+        for (const [i, test] of plan.tests.entries()) {
+            lines.push(`  ${String(i + 1).padStart(2)}. [${test.priority}] ${test.scenario}`);
+        }
+        tag('multiline').log(lines.join('\n'), { maxLines: 24 });
+        const savedPath = this.bot.savePlan();
+        if (!savedPath)
+            return;
+        const relative = relativeToCwd(savedPath);
+        const sections = [
+            {
+                label: 'Plan',
+                path: savedPath,
+                commands: [
+                    { label: 'Run first', command: `${this.prefix} test ${relative} 1` },
+                    { label: 'Run all', command: `${this.prefix} test ${relative} *` },
+                    { label: 'Run range', command: `${this.prefix} test ${relative} 1-3` },
+                ],
+            },
+        ];
+        printNextSteps(sections);
+    }
+}

package/dist/boat/api-tester/src/commands/test-command.js

@@ -0,0 +1,45 @@
+import figureSet from 'figures';
+import { tag } from "../../../../src/utils/logger.js";
+import { ApiCommand } from "./api-command.js";
+export class TestCommand extends ApiCommand {
+    name = 'test';
+    description = 'Execute tests from a plan file. Index: 1, 1-3, *';
+    index;
+    failed = 0;
+    async execute(planfile) {
+        const plan = this.bot.loadPlan(planfile);
+        tag('info').log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests)`);
+        const tests = selectTests(plan.tests, this.index);
+        tag('info').log(`Running ${tests.length} test(s)`);
+        let passed = 0;
+        for (const test of tests) {
+            const result = await this.bot.runTest(test);
+            if (result.success)
+                passed++;
+            else
+                this.failed++;
+        }
+        this.bot.savePlan();
+        tag('info').log(`${figureSet.tick} ${tests.length} tests completed: ${passed} passed, ${this.failed} failed`);
+    }
+}
+export function selectTests(tests, index) {
+    if (!index || index === '*' || index === 'all') {
+        return tests.filter((t) => t.status === 'pending');
+    }
+    const rangeMatch = index.match(/^(\d+)-(\d+)$/);
+    if (rangeMatch) {
+        const start = Number.parseInt(rangeMatch[1]) - 1;
+        const end = Number.parseInt(rangeMatch[2]);
+        return tests.slice(start, end);
+    }
+    if (index.includes(',')) {
+        const indices = index.split(',').map((i) => Number.parseInt(i.trim()) - 1);
+        return indices.map((i) => tests[i]).filter(Boolean);
+    }
+    const num = Number.parseInt(index);
+    if (!Number.isNaN(num) && tests[num - 1]) {
+        return [tests[num - 1]];
+    }
+    return tests.filter((t) => t.status === 'pending');
+}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -101,7 +101,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "4.0.0-rc.16",
+    "codeceptjs": "4.2.0-beta.2",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",
@@ -123,8 +123,8 @@
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.62",
-    "playwright-core": "^1.62",
+    "playwright": "^1.63",
+    "playwright-core": "^1.63",
     "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",

package/dist/src/ai/researcher/deep-analysis.d.ts

@@ -38,7 +38,7 @@ export declare function WithDeepAnalysis<T extends Constructor>(Base: T): {
         }>): Promise<void>;
         _executeAndAnalyze(commands: string[], description: string, state: WebPageState, originalAria: string, alreadyExpanded: string[]): Promise<ExpansionOutcome>;
         _restorePageState(url: string, originalAria: string): Promise<void>;
-        _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[]): Promise<string | null>;
+        _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[], containerCss?: string | null): Promise<string | null>;
         _deduplicateExpandedSections(sections: string[]): string[];
         _summarizeExpanded(expandedSections: string[]): string[];
         _sectionFingerprint(sectionMarkdown: string): string | null;

package/dist/src/ai/researcher/deep-analysis.js

@@ -85,7 +85,7 @@ export function WithDeepAnalysis(Base) {
                 .filter((s) => s.elements.length > 0)
                 .map((s) => s.rawMarkdown));
             tag('substep').log(`Researching overlay: ${region.name}`);
-            const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
+            const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded, region.root);
             if (!sectionMarkdown) {
                 debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
                 return null;
@@ -367,9 +367,9 @@ export function WithDeepAnalysis(Base) {
             }
             await new Promise((r) => setTimeout(r, 500));
             let diff;
+            let currAR;
             try {
-                await this.explorer.capture();
-                const currAR = ActionResult.fromState(this.stateManager.getCurrentState());
+                currAR = await this.explorer.capture();
                 diff = await currAR.diff(previousState);
             }
             catch (err) {
@@ -388,7 +388,7 @@ export function WithDeepAnalysis(Base) {
                 debugLog(`No changes from: ${description.slice(0, 80)}`);
                 return { status: 'none', code: clickCode };
             }
-            const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded);
+            const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded, currAR.overlay.root);
             await this._restorePageState(state.url, originalAria);
             if (!sectionMarkdown)
                 return { status: 'none', code: clickCode };
@@ -413,7 +413,7 @@ export function WithDeepAnalysis(Base) {
                 tag('warning').log(`navigateTo failed during restore: ${err instanceof Error ? err.message : err}`);
             }
         }
-        async _analyzeExpandedAction(code, description, diff, alreadyExpanded) {
+        async _analyzeExpandedAction(code, description, diff, alreadyExpanded, containerCss = null) {
             const alreadyHint = alreadyExpanded.length > 0 ? `\nAlready expanded sections:\n${alreadyExpanded.join('\n')}` : '';
             let intro;
             if (code) {
@@ -473,7 +473,15 @@ export function WithDeepAnalysis(Base) {
             const sections = parseResearchSections(text);
             if (sections.length === 0)
                 return null;
-            return sections[0].rawMarkdown;
+            const sectionMarkdown = sections[0].rawMarkdown;
+            if (!containerCss)
+                return sectionMarkdown;
+            let heading = mdq(sectionMarkdown).query('h3[0]');
+            if (heading.count() === 0)
+                heading = mdq(sectionMarkdown).query('h2[0]');
+            if (heading.count() === 0)
+                return sectionMarkdown;
+            return heading.replace(`${heading.text().trimEnd()}\n\n> Container: '${containerCss}'\n\n`);
         }
         _deduplicateExpandedSections(sections) {
             const seen = new Set();

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

@@ -1,5 +1,5 @@
-import type { ExecutedStep } from '../action.js';
 import { ActionResult, type PageDiff } from '../action-result.js';
+import type { ExecutedStep } from '../action.js';
 import { type ExperienceTracker } from '../experience-tracker.js';
 import { type Task } from '../test-plan.js';
 import type { ToolDeps } from './agent.js';

package/dist/src/ai/tools.js

@@ -5,13 +5,13 @@ import { ActionResult } from "../action-result.js";
 import { renderExperienceRecipes } from "../experience-tracker.js";
 import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
+import { ariaRefSelector, describeRef, refIsGone } from "../utils/aria-ref.js";
 import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
-import { ariaRefSelector, describeRef, refIsGone } from "../utils/aria-ref.js";
+import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
@@ -109,7 +109,13 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                             });
                         }
                         await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-                        return successToolResult('click', { ...toolResult, attempts, code: command }, action);
+                        const data = { ...toolResult, attempts, code: command };
+                        const notExecuted = commands.slice(i + 1);
+                        if (notExecuted.length) {
+                            data.notExecuted = notExecuted;
+                            data.suggestion = `SKIPPED: ${notExecuted.join('; ')}`;
+                        }
+                        return successToolResult('click', data, action);
                     }
                 }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
@@ -1109,7 +1115,7 @@ export async function failedToolResult(action, message, data, error) {
     const errorTexts = [message, ...(data?.attempts?.map((a) => a.error || '') || [])];
     if (errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
         const matched = await extractWebElements(error);
-        result.suggestion = getMultipleElementsSuggestion(matched);
+        result.suggestion = getMultipleElementsSuggestion();
         result.multipleElementsDetected = true;
         result.elements = formatElementList(matched);
         return result;
@@ -1121,16 +1127,12 @@ export async function failedToolResult(action, message, data, error) {
     }
     return result;
 }
-function getMultipleElementsSuggestion(matched) {
-    const visible = (matched || []).filter((element) => element.visible !== false);
-    let onlyVisible = '';
-    if (matched && visible.length === 1)
-        onlyVisible = `\nOnly element ${matched.indexOf(visible[0]) + 1} is on screen, so that is the one to act on.`;
+function getMultipleElementsSuggestion() {
     return dedent `
     Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
     Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
-    A match reported as not visible can never be acted on — pick one that is.${onlyVisible}
+    A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
@@ -1197,6 +1199,9 @@ function formatElementList(matched) {
         const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
         if (el.visible !== undefined)
             lines.push(`Visible: ${el.visible}`);
+        const wrapped = matched.map((_, j) => j).filter((j) => j !== i && matched[j].xpath.startsWith(`${el.xpath}/`));
+        if (wrapped.length)
+            lines.push(`Wraps: element ${wrapped.map((j) => j + 1).join(', ')}`);
         lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
         return lines.join('\n');
     })

package/dist/src/api/spec-reader.d.ts

@@ -1,5 +1,6 @@
 export declare function validateSpecs(specs?: string[]): void;
 export declare function loadSpec(specPaths: string[], outputDir: string): Promise<any>;
 export declare function extractEndpointDefinition(schema: any, endpoint: string, baseEndpoint?: string): string;
+export declare function resolveEndpoints(schema: any, pattern: string, baseEndpoint?: string): string[];
 export declare function searchEndpoints(schema: any, query: string, baseEndpoint?: string): string;
 export declare function listAllEndpoints(schema: any, baseEndpoint?: string): string;

package/dist/src/api/spec-reader.js

@@ -42,13 +42,35 @@ export function extractEndpointDefinition(schema, endpoint, baseEndpoint) {
         throw new Error('OpenAPI spec has no paths defined');
     }
     const basePath = toBasePath(baseEndpoint);
-    const matched = collectMatchingPaths(schema, basePath, (normalized) => matchesEndpoint(normalized, endpoint));
+    const matched = collectEndpointPaths(schema, basePath, endpoint);
     if (!Object.keys(matched).length) {
         const available = listNormalizedPaths(schema, basePath);
         throw new Error(`Endpoint "${endpoint}" not found in spec. Available: ${available}`);
     }
     return safeStringify(matched);
 }
+export function resolveEndpoints(schema, pattern, baseEndpoint) {
+    if (!schema?.paths) {
+        throw new Error('OpenAPI spec has no paths defined');
+    }
+    const basePath = toBasePath(baseEndpoint);
+    const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+    const matched = normalized.filter((specPath) => matchesPattern(specPath, pattern));
+    if (!matched.length) {
+        throw new Error(`Endpoint "${pattern}" not found in spec. Available: ${listNormalizedPaths(schema, basePath)}`);
+    }
+    const roots = matched.map((specPath) => toCollection(specPath, normalized, pattern));
+    const resolved = [...new Set(roots.map((root) => fillParameters(root, pattern)))];
+    const endpoints = resolved.filter((specPath) => !specPath.includes('{'));
+    if (!endpoints.length) {
+        throw new Error(`Endpoint "${pattern}" leaves ${listParameters(resolved)} unresolved. Give the value in the endpoint or in the base endpoint.`);
+    }
+    const skipped = resolved.filter((specPath) => specPath.includes('{'));
+    if (skipped.length) {
+        tag('warning').log(`Skipped, no value for their parameters: ${skipped.join(', ')}`);
+    }
+    return endpoints;
+}
 export function searchEndpoints(schema, query, baseEndpoint) {
     if (!schema?.paths)
         return 'No endpoints available';
@@ -136,6 +158,76 @@ function stripBasePath(specPath, basePath) {
     }
     return `/${specSegments.slice(i).join('/')}`;
 }
+function collectEndpointPaths(schema, basePath, endpoint) {
+    const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+    const roots = resolveEndpoint(normalized, endpoint);
+    if (!roots.length)
+        return collectMatchingPaths(schema, basePath, (path) => matchesEndpoint(path, endpoint));
+    return collectMatchingPaths(schema, basePath, (path) => roots.some((root) => path === root || path.startsWith(`${root}/`)));
+}
+function resolveEndpoint(specPaths, endpoint) {
+    const wanted = toSegments(endpoint);
+    if (!wanted.length)
+        return [];
+    const matched = specPaths.filter((specPath) => {
+        const segments = toSegments(specPath);
+        if (segments.length !== wanted.length)
+            return false;
+        return segmentsMatch(segments, wanted);
+    });
+    const literals = matched.map((specPath) => toSegments(specPath).filter((segment, i) => segment === wanted[i]).length);
+    const best = Math.max(0, ...literals);
+    return matched.filter((_, i) => literals[i] === best);
+}
+function matchesPattern(specPath, pattern) {
+    const wanted = toSegments(pattern);
+    const segments = toSegments(specPath);
+    if (segments.length < wanted.length)
+        return false;
+    return segmentsMatch(segments, wanted);
+}
+function segmentsMatch(segments, wanted) {
+    return wanted.every((want, i) => want === '*' || segments[i] === want || segments[i].startsWith('{'));
+}
+function toCollection(specPath, specPaths, pattern) {
+    const segments = toSegments(specPath);
+    const filled = toSegments(fillParameters(specPath, pattern));
+    let deepest = segments.length;
+    const unfilled = filled.findIndex((segment) => segment.startsWith('{'));
+    if (unfilled >= 0)
+        deepest = unfilled;
+    for (let i = Math.max(1, Math.min(toSegments(pattern).length, deepest)); i <= deepest; i++) {
+        const prefix = `/${segments.slice(0, i).join('/')}`;
+        if (specPaths.includes(prefix))
+            return prefix;
+    }
+    return specPath;
+}
+function fillParameters(specPath, pattern) {
+    const wanted = toSegments(pattern);
+    const segments = toSegments(specPath);
+    for (let i = 0; i < wanted.length && i < segments.length; i++) {
+        if (wanted[i] === '*')
+            continue;
+        if (!segments[i].startsWith('{'))
+            continue;
+        segments[i] = wanted[i];
+    }
+    return `/${segments.join('/')}`;
+}
+function listParameters(specPaths) {
+    const found = new Set();
+    for (const specPath of specPaths) {
+        for (const segment of toSegments(specPath)) {
+            if (segment.startsWith('{'))
+                found.add(segment);
+        }
+    }
+    return [...found].join(', ');
+}
+function toSegments(path) {
+    return path.split('/').filter(Boolean);
+}
 function matchesEndpoint(specPath, endpoint) {
     if (specPath === endpoint)
         return true;

package/dist/src/commands/base-command.d.ts

@@ -7,15 +7,15 @@ export interface Suggestion {
     command?: string;
     hint: string;
 }
-export declare abstract class BaseCommand {
+export declare abstract class BaseCommand<T = ExplorBot> {
     abstract name: string;
     abstract description: string;
     aliases: string[];
     options: CommandOption[];
     tuiEnabled: boolean;
     suggestions: Suggestion[];
-    explorBot: ExplorBot;
-    constructor(explorBot: ExplorBot);
+    explorBot: T;
+    constructor(explorBot: T);
     abstract execute(args: string): Promise<void>;
     matches(commandName: string): boolean;
     printSuggestions(): void;

package/dist/src/commands/init-command.d.ts

@@ -1,6 +1,9 @@
+import { type ModelRole } from '../config.js';
+export declare function envTemplate(provider: string): string;
 export declare function runInit(options: InitCommandOptions): Promise<void>;
 export declare function writeGlobalConfig(provider: string, apiKey?: string): void;
 export declare function runInitCommand(options: InitCommandOptions): void;
+export declare function modelLines(provider: string, only?: ModelRole[]): string;
 type InitCommandOptions = {
     configPath?: string;
     force?: boolean;

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

@@ -37,7 +37,7 @@ ${modelLines(provider)}
 ${moduleExport}
 `;
 }
-function envTemplate(provider) {
+export function envTemplate(provider) {
     const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
         if (name === provider)
             return `${envKey}=`;
@@ -219,14 +219,17 @@ async function renderLocalProviderWizard() {
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
-function modelLines(provider) {
+export function modelLines(provider, only) {
     const recommended = ConfigParser.recommendedModels()[provider] || {};
     const roles = [
         ['model', 'fast model with tool calling capabilities'],
         ['visionModel', 'vision model for screenshot analysis'],
         ['agenticModel', 'agentic model for decision making'],
     ];
-    return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+    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');
 }
 function globalConfigTemplate(provider) {
     const { envKey } = PROVIDERS[provider];

package/dist/src/explorer.d.ts

@@ -39,7 +39,7 @@ declare class Explorer {
     testPageErrorHandler: ((error: Error) => void) | null;
     testConsoleHandler: ((message: any) => void) | null;
     testDialogHandler: ((dialog: any) => void) | null;
-    eventDispatcher: any;
+    eventDispatcher: NodeJS.EventEmitter<[never]>;
     constructor(config: ExplorbotConfig, options: ExplorerOptions | undefined, deps: ExplorerDeps);
     get actor(): CodeceptJS.I;
     get page(): Page | null;

package/dist/src/explorer.js

@@ -208,7 +208,7 @@ class Explorer {
         codeceptjs.container.create(this.convertToCodeceptConfig(this.config), {});
     }
     convertToCodeceptConfig(config) {
-        const playwrightConfig = { ...config.playwright };
+        const playwrightConfig = { visibleLocator: true, ...config.playwright };
         if (this.options?.show !== undefined) {
             playwrightConfig.show = this.options.show;
         }

package/dist/src/utils/html-diff.js

@@ -4,7 +4,7 @@ import { isDynamicId, isGenericClass } from "./xpath.js";
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
 const SHELL_RATIO = 0.8;
 const ROOT_CONTENT_RATIO = 0.8;
-const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
+const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log', 'tooltip']);
 const TEXT_LINE_PREFIX = 'TEXT:';
 const MESSAGE_MAX_LENGTH = 200;
 const MESSAGE_LIMIT = 8;
@@ -447,6 +447,9 @@ function semanticSelectorFor(element, allElements) {
         const selector = buildContainerSelector(current, allElements);
         if (selector)
             return selector;
+        const classAttr = (current.attrs ?? []).find((a) => a.name === 'class')?.value;
+        if (classAttr && filterContainerClasses(classAttr.split(/\s+/).filter(Boolean)).length > 0)
+            return undefined;
         current = dominantChild(current);
     }
     return undefined;

package/docs/api-testing/basics.md

@@ -66,7 +66,7 @@ npx explorbot api explore https://api.example.com/v1 \
   -H "Authorization: Bearer $TOKEN"
 ```
 
-`api explore` takes the base endpoint as its argument, so one line covers the whole run: it plans in every style, executes each plan, and reports the totals. The other commands take a path within the API and read the base from `--endpoint`:
+`api explore` takes an endpoint or a pattern as its argument, so one line covers the whole run: it plans, executes each plan, and reports the totals. Passing the base endpoint covers every collection the spec describes. The other commands take a path within the API and read the base from `--endpoint`:
 
 ```bash
 npx explorbot api plan /users \
@@ -81,7 +81,7 @@ The base endpoint keeps its path prefix: given `https://api.example.com/v1`, ste
 
 ### A dedicated API project
 
-If you don't have a web `explorbot.config.js`, run `npx explorbot api init`. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone `apibot.config.ts` (with an `ai` and `api` section) plus `output/` and `knowledge/` directories. When both files exist, `apibot.config.*` takes precedence over `explorbot.config.*`.
+If you don't have a web `explorbot.config.js`, run `npx explorbot api init`. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone `apibot.config.js` (with an `ai` and `api` section) plus `output/` and `knowledge/` directories. When both files exist, `apibot.config.*` takes precedence over `explorbot.config.*`.
 
 ## Your first run
 
@@ -99,6 +99,30 @@ npx explorbot api test output/plans/users.md
 
 Curler runs the scenarios and prints how many passed and failed.
 
+### Covering many endpoints
+
+`api explore` runs the whole loop for you: plan, test, re-plan. Given one endpoint it plans in every style.
+
+```bash
+npx explorbot api explore /users
+```
+
+The endpoint may be a pattern. `*` stands for one path segment, and a pattern also covers the paths below it, so `/users` and `/users/*` both cover `/users/{id}`. Quote it, or your shell will try to expand it first.
+
+```bash
+npx explorbot api explore '/projects/acme/*'
+```
+
+Explorbot explores collections, not raw paths: `/users/{id}` and `/users/{id}/posts` fold into `/users`, whose spec lookup brings them along anyway. When a pattern matches several collections the planning styles spread across them, one style per collection, so covering a whole API stays one plan per collection rather than one per style.
+
+Pass `/` to take every collection in the spec. The path parameters have to come from somewhere, so put them in the base endpoint.
+
+```bash
+npx explorbot api explore / --endpoint https://api.example.com/v2/acme
+```
+
+If a parameter is left with no value the run stops and names it, rather than sending requests to a literal `{project_id}`. Collections whose own parameters no pattern can fill, like `/analytics/stats/{kind}`, are listed and skipped.
+
 ## Output files
 
 | Output | Location | What it is |