explorbot 0.2.2 → 0.2.4

package/dist/src/utils/aria.js

@@ -78,8 +78,7 @@ const parseLabel = (label) => {
         rest = rest.slice(nameMatch[0].length);
     }
     const attributes = {};
-    const attrMatch = rest.match(/\[([^\]]*)\]/);
-    if (attrMatch) {
+    for (const attrMatch of rest.matchAll(/\[([^\]]*)\]/g)) {
         for (const tok of attrMatch[1].split(/[\s,]+/).filter(Boolean)) {
             const eq = tok.indexOf('=');
             if (eq === -1) {
@@ -189,7 +188,8 @@ const dropEmpty = (nodes, opts = {}) => nodes.flatMap((node) => {
 // STEP 3 · Render: AriaNode[] → text or flat entries
 // ─────────────────────────────────────────────────────────────────
 // One-line representation of a node. Stable attr order so diff comparisons are deterministic.
-const formatNode = (node) => {
+const MAX_INLINE_VALUE = 400;
+const formatNode = (node, offload) => {
     let line = node.role;
     if (node.name?.trim())
         line += ` "${node.name.trim()}"`;
@@ -209,11 +209,20 @@ const formatNode = (node) => {
         line += ` [${attrStr}]`;
     if (node.value !== undefined && node.value !== null) {
         const text = String(node.value).trim();
-        if (text)
+        if (text && text.length <= MAX_INLINE_VALUE)
             line += `: ${text}`;
+        if (text && text.length > MAX_INLINE_VALUE)
+            line += `: ${offloadValue(text, offload)}`;
     }
     return line;
 };
+const offloadValue = (text, offload) => {
+    const head = `${text.slice(0, MAX_INLINE_VALUE)}…`;
+    const reference = offload?.(text);
+    if (!reference)
+        return `${head} (${text.length} chars, truncated)`;
+    return `${head} (${text.length} chars) [Full Text: ${reference}]`;
+};
 // Group consecutive same-role siblings.  [a,a,b,a,a,a] → [[a,a],[b],[a,a,a]]
 const groupByConsecutiveRole = (nodes) => nodes.reduce((groups, node) => {
     const last = groups[groups.length - 1];
@@ -236,16 +245,16 @@ const collapseGroup = (group, depth) => {
 };
 const collapseSiblingGroups = (nodes, depth) => groupByConsecutiveRole(nodes).flatMap((group) => collapseGroup(group, depth));
 // Tree → indented YAML text.
-const renderTree = (nodes, depth = 0) => collapseSiblingGroups(nodes, depth)
+const renderTree = (nodes, depth = 0, offload) => collapseSiblingGroups(nodes, depth)
     .map((entry) => {
     if ('placeholder' in entry)
         return entry.placeholder;
     const { node } = entry;
     const indent = '  '.repeat(depth);
-    const head = `${indent}- ${formatNode(node)}`;
+    const head = `${indent}- ${formatNode(node, offload)}`;
     if (node.children.length === 0)
         return head;
-    return `${head}:\n${renderTree(node.children, depth + 1)}`;
+    return `${head}:\n${renderTree(node.children, depth + 1, offload)}`;
 })
     .join('\n');
 // Build the structured "entry" object for an interactive node, or null if not worth keeping.
@@ -384,6 +393,42 @@ const detectToggles = (prev, curr) => {
     }
     return { toggled, togglePaths };
 };
+const detectValueChanges = (prev, curr) => {
+    const typed = [];
+    const typedPaths = new Set();
+    const currByPath = new Map(curr.map((e) => [e.path, e]));
+    for (const before of prev) {
+        const after = currByPath.get(before.path);
+        if (!after)
+            continue;
+        if (before.entry.role !== after.entry.role)
+            continue;
+        if (before.entry.name !== after.entry.name)
+            continue;
+        const was = valueWord(before.entry.value);
+        const now = valueWord(after.entry.value);
+        if (was === now)
+            continue;
+        typedPaths.add(before.path);
+        let label = String(after.entry.role);
+        const name = after.entry.name;
+        if (typeof name === 'string' && name.trim())
+            label += ` "${name.trim()}"`;
+        typed.push(`${label}: ${was} -> ${now}`);
+    }
+    return { typed, typedPaths };
+};
+const VALUE_EXCERPT = 60;
+const valueWord = (value) => {
+    if (value === undefined || value === null)
+        return 'empty';
+    const text = String(value).trim();
+    if (!text)
+        return 'empty';
+    if (text.length <= VALUE_EXCERPT)
+        return JSON.stringify(text);
+    return `${JSON.stringify(text.slice(0, VALUE_EXCERPT))}… (${text.length} chars)`;
+};
 const TOP_DIFF_ITEMS = 10;
 const formatDiffSection = (label, items) => {
     const summary = countBy(items);
@@ -407,10 +452,15 @@ const formatDiffSection = (label, items) => {
     }
     return lines;
 };
-const formatDiff = (added, removed, toggled) => {
-    if (added.length === 0 && removed.length === 0 && toggled.length === 0)
+const formatDiff = (added, removed, toggled, typed = []) => {
+    if (added.length === 0 && removed.length === 0 && toggled.length === 0 && typed.length === 0)
         return null;
     const sections = ['ariaDiff:'];
+    if (typed.length > 0) {
+        sections.push('  typed:');
+        for (const line of typed)
+            sections.push(`    - ${line}`);
+    }
     if (toggled.length > 0) {
         sections.push('  toggled:');
         for (const line of toggled)
@@ -461,17 +511,14 @@ const findDialogOrModal = (nodes) => {
     }
     return null;
 };
-// ─────────────────────────────────────────────────────────────────
-// Public API — pipelines composed visibly, top-to-bottom
-// ─────────────────────────────────────────────────────────────────
-export const compactAriaSnapshot = (snapshot, keepNamed = false) => {
+export const compactAriaSnapshot = (snapshot, keepNamed = false, offload) => {
     if (!snapshot)
         return '';
     let tree = parseSnapshot(snapshot);
     tree = unwrapIgnored(tree);
     tree = nameIconButtons(tree);
     tree = dropEmpty(tree, { keepNamed });
-    return renderTree(tree);
+    return renderTree(tree, 0, offload);
 };
 export const diffAriaSnapshots = (previous, current) => {
     const flat = (snap) => {
@@ -484,15 +531,17 @@ export const diffAriaSnapshots = (previous, current) => {
     const prevAll = flat(previous);
     const currAll = flat(current);
     const { toggled, togglePaths } = detectToggles(prevAll, currAll);
-    const prev = prevAll.filter((e) => !togglePaths.has(e.path));
-    const curr = currAll.filter((e) => !togglePaths.has(e.path));
+    const { typed, typedPaths } = detectValueChanges(prevAll, currAll);
+    const skip = (entry) => togglePaths.has(entry.path) || typedPaths.has(entry.path);
+    const prev = prevAll.filter((e) => !skip(e));
+    const curr = currAll.filter((e) => !skip(e));
     const prevTotals = countBy(prev.map((e) => e.summary));
     const currTotals = countBy(curr.map((e) => e.summary));
     const byCount = diffByCount(prevTotals, currTotals);
     const renames = detectRenames(prev, curr, prevTotals, currTotals);
     const added = [...byCount.added, ...renames.added];
     const removed = [...byCount.removed, ...renames.removed];
-    return { text: formatDiff(added, removed, toggled), count: added.length + removed.length + toggled.length };
+    return { text: formatDiff(added, removed, toggled, typed), count: added.length + removed.length + toggled.length + typed.length };
 };
 export const detectFocusArea = (snapshot) => {
     let tree = parseSnapshot(snapshot);
@@ -513,29 +562,9 @@ export const collectInteractiveNodes = (snapshot) => {
     tree = dropEmpty(tree);
     return flatten(tree).map((e) => e.entry);
 };
-export function extractFocusedElement(ariaSnapshot) {
-    if (!ariaSnapshot)
-        return null;
-    const focusedMatch = ariaSnapshot.match(/-\s*(\w+)\s+"([^"]*)"([^:\n]*)\[focused\](?::\s*(.*))?/);
-    if (!focusedMatch)
-        return null;
-    const [, role, name, attributesStr, value] = focusedMatch;
-    const attributes = [];
-    if (attributesStr) {
-        const attrMatches = attributesStr.matchAll(/\[([^\]]+)\]/g);
-        for (const match of attrMatches) {
-            if (match[1] !== 'focused') {
-                attributes.push(match[1]);
-            }
-        }
-    }
-    const result = { role, name };
-    if (value)
-        result.value = value.trim();
-    if (attributes.length > 0)
-        result.attributes = attributes;
-    return result;
-}
+// ─────────────────────────────────────────────────────────────────
+// Standalone helpers (regex on raw strings — not part of the pipeline)
+// ─────────────────────────────────────────────────────────────────
 export function parseAriaLocator(ariaStr) {
     const trimmed = ariaStr.trim();
     if (trimmed === '-' || trimmed === '' || trimmed === '"-"')

package/dist/src/utils/cli-name.js

@@ -8,8 +8,12 @@ export function getCliName() {
         cached = 'bunx explorbot';
     else if (ua.includes('npm'))
         cached = 'npx explorbot';
-    else if (process.argv[1]?.endsWith('.ts'))
-        cached = `bun ${path.relative(process.cwd(), process.argv[1])}`;
+    else if (process.argv[1]?.endsWith('.ts')) {
+        let script = path.relative(process.cwd(), process.argv[1]);
+        if (script.startsWith('..'))
+            script = process.argv[1];
+        cached = `bun ${script}`;
+    }
     else
         cached = 'explorbot';
     return cached;

package/dist/src/utils/html.js

@@ -1376,6 +1376,7 @@ function cleanElement(element) {
             attr.value = attr.value
                 .split(/\s+/)
                 .filter((className) => !/\d/.test(className))
+                .filter((className) => !className.includes(':'))
                 .filter((className) => !TAILWIND_CLASS_PATTERNS.some((pattern) => pattern.test(className)))
                 .join(' ');
             if (!attr.value) {

package/dist/src/utils/logger.d.ts

@@ -9,6 +9,10 @@ export interface TaggedLogEntry {
     maxLines?: number;
 }
 type LogEntry = TaggedLogEntry;
+export interface LogDestination {
+    isEnabled(): boolean;
+    write(entry: TaggedLogEntry): void;
+}
 export declare const tag: (type: LogType) => {
     log: (...args: any[]) => void;
 };
@@ -23,9 +27,11 @@ export declare const startLogCapture: () => void;
 export declare const stopLogCapture: () => string[];
 export declare const setVerboseMode: (enabled: boolean) => void;
 export declare const setPreserveConsoleLogs: (enabled: boolean) => void;
+export declare const setQuietMode: (enabled: boolean) => void;
 export declare const isVerboseMode: () => boolean;
 export declare const setDebugMode: (enabled: boolean) => void;
 export declare const isDebugMode: () => boolean;
+export declare const addDestination: (destination: LogDestination) => void;
 export declare const registerLogPane: (addLog: (entry: LogEntry) => void) => void;
 export declare const unregisterLogPane: (addLog: (entry: LogEntry) => void) => void;
 export declare const addTruncateTag: (tagName: string) => void;

package/dist/src/utils/logger.js

@@ -52,13 +52,19 @@ const debugFilter = new DebugFilter();
 class ConsoleDestination {
     verboseMode = false;
     forceEnabled = false;
+    quiet = false;
     recentSteps = new RecentStepFilter();
     isEnabled() {
+        if (this.quiet)
+            return false;
         return this.forceEnabled || !process.env.INK_RUNNING;
     }
     forceEnable(enabled) {
         this.forceEnabled = enabled;
     }
+    setQuiet(enabled) {
+        this.quiet = enabled;
+    }
     setVerboseMode(enabled) {
         this.verboseMode = enabled;
     }
@@ -113,6 +119,9 @@ class DebugDestination {
     }
     setVerboseMode(enabled) {
         this.verboseMode = enabled;
+        // the debug package reads DEBUG when it loads, so a namespace turned on later needs enabling by hand
+        if (enabled)
+            debug.enable(process.env.DEBUG || 'explorbot:*');
     }
     write(namespace, ...args) {
         if (!this.isNamespaceEnabled(namespace))
@@ -296,6 +305,7 @@ class Logger {
     span = new SpanDestination();
     react = new ReactDestination();
     captain = new CaptainDestination();
+    extra = [];
     truncateTags = ['page_html'];
     constructor() { }
     static getInstance() {
@@ -317,9 +327,17 @@ class Logger {
     setPreserveConsoleLogs(enabled) {
         this.console.forceEnable(enabled);
     }
+    setQuietMode(enabled) {
+        this.console.setQuiet(enabled);
+    }
     isVerboseMode() {
         return this.debugDestination.isEnabled();
     }
+    addDestination(destination) {
+        if (this.extra.includes(destination))
+            return;
+        this.extra.push(destination);
+    }
     registerLogPane(addLog) {
         this.react.registerLogPane(addLog);
     }
@@ -406,6 +424,10 @@ class Logger {
             this.span.write(entry);
         if (this.captain.isEnabled())
             this.captain.write(entry);
+        for (const destination of this.extra) {
+            if (destination.isEnabled())
+                destination.write(entry);
+        }
         if (process.env.INK_RUNNING) {
             this.react.write(entry);
         }
@@ -475,9 +497,11 @@ export const startLogCapture = () => logger.captain.startCapture();
 export const stopLogCapture = () => logger.captain.stopCapture();
 export const setVerboseMode = (enabled) => logger.setVerboseMode(enabled);
 export const setPreserveConsoleLogs = (enabled) => logger.setPreserveConsoleLogs(enabled);
+export const setQuietMode = (enabled) => logger.setQuietMode(enabled);
 export const isVerboseMode = () => logger.isVerboseMode();
 export const setDebugMode = (enabled) => logger.setDebugMode(enabled);
 export const isDebugMode = () => logger.isDebugMode();
+export const addDestination = (destination) => logger.addDestination(destination);
 export const registerLogPane = (addLog) => logger.registerLogPane(addLog);
 export const unregisterLogPane = (addLog) => logger.unregisterLogPane(addLog);
 export const addTruncateTag = (tagName) => logger.addTruncateTag(tagName);

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

@@ -3,9 +3,26 @@ export async function waitForPageReadiness(page, options = {}) {
         return;
     const timeout = options.timeout ?? 6000;
     await page.waitForLoadState?.('domcontentloaded', { timeout })?.catch(() => { });
-    await Promise.race([waitForNetworkIdle(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => { });
+    await Promise.race([waitForNetworkIdle(page, timeout), waitForDomQuiet(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => { });
     await waitForPageBodyContent(page, timeout);
 }
+const DOM_QUIET_MS = 350;
+function waitForDomQuiet(page, timeout) {
+    if (!page?.waitForFunction)
+        return new Promise(() => { });
+    return page
+        .waitForFunction((quiet) => {
+        const store = window;
+        if (!store.__explorbotDomQuiet) {
+            store.__explorbotDomQuiet = { last: Date.now() };
+            new MutationObserver(() => {
+                store.__explorbotDomQuiet.last = Date.now();
+            }).observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+        }
+        return Date.now() - store.__explorbotDomQuiet.last >= quiet;
+    }, DOM_QUIET_MS, { timeout, polling: 100 })
+        .catch(() => { });
+}
 function waitForNetworkIdle(page, timeout) {
     if (!page?.waitForLoadState)
         return Promise.resolve();

package/dist/src/utils/test-files.js

@@ -57,8 +57,7 @@ export async function dryRunTestFile(filePath) {
         return;
     }
     const config = ConfigParser.getInstance().getConfig();
-    const configPath = ConfigParser.getInstance().getConfigPath();
-    const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
+    const projectRoot = ConfigParser.getInstance().getProjectRoot();
     const codeceptConfig = {
         helpers: {
             Playwright: { browser: config.playwright.browser, url: config.playwright.url },

package/dist/src/utils/url-matcher.d.ts

@@ -4,3 +4,4 @@ export declare function generalizeSegment(segment: string): string;
 export declare function generalizeUrl(url: string): string;
 export declare function matchesUrl(pattern: string, path: string): boolean;
 export declare function extractStatePath(url: string): string;
+export declare function matchesNavigationUrl(expected: string, current: string): boolean;

package/dist/src/utils/url-matcher.js

@@ -102,3 +102,15 @@ export function extractStatePath(url) {
         return url;
     }
 }
+export function matchesNavigationUrl(expected, current) {
+    const expectedPath = extractStatePath(expected);
+    let currentPath = extractStatePath(current);
+    if (!expectedPath.includes('#')) {
+        currentPath = currentPath.split('#')[0];
+    }
+    if (!expectedPath.includes('?')) {
+        currentPath = currentPath.split('?')[0];
+    }
+    const normalize = (value) => value.replace(/^\/+|\/+$/g, '').toLowerCase();
+    return normalize(expectedPath) === normalize(currentPath);
+}

package/dist/src/utils/web-element.d.ts

@@ -36,6 +36,8 @@ export declare class WebElement {
     static fromXPathMatch(m: XPathMatch): WebElement;
     static fromPlaywrightLocator(locator: any): Promise<WebElement | null>;
     static fromEidx(page: any, eidx: string): Promise<WebElement | null>;
+    static isAriaRef(ref: string): boolean;
+    static fromAriaRef(page: any, ref: string): Promise<WebElement | null>;
     static fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]>;
     static commonAncestor(page: any, eidxList: string[]): Promise<WebElement | null>;
     static findByXPath(html: string, xpath: string): Promise<{

package/dist/src/utils/web-element.js

@@ -111,6 +111,14 @@ export class WebElement {
     static async fromEidx(page, eidx) {
         return WebElement.fromPlaywrightLocator(page.locator(`[${EXPLORBOT_ATTRS.eidx}="${eidx}"]`));
     }
+    static isAriaRef(ref) {
+        return /^(f\d+)?e\d+$/i.test(ref);
+    }
+    static async fromAriaRef(page, ref) {
+        if (!WebElement.isAriaRef(ref))
+            return null;
+        return WebElement.fromPlaywrightLocator(page.locator(`aria-ref=${ref}`));
+    }
     static async fromEidxList(page, eidxList) {
         const validEidxList = eidxList.filter((eidx) => /^e\d+$/i.test(eidx));
         if (validEidxList.length === 0)

package/dist/src/utils/web-sandbox.d.ts

@@ -1,4 +1,4 @@
 export declare function sanitizeCodeBlock(code: string): string;
 export declare function hasPlaywrightCommands(code: string): boolean;
 export declare function playwrightSandbox(page: any, code: string): Promise<any>;
-export declare function codeceptJSSandbox(actor: any, codeOrFn: string | ((...args: any[]) => void)): void;
+export declare function codeceptJSSandbox(actor: any, codeOrFn: string | ((...args: any[]) => void)): any;

package/dist/src/utils/web-sandbox.js

@@ -25,11 +25,10 @@ export function playwrightSandbox(page, code) {
 }
 export function codeceptJSSandbox(actor, codeOrFn) {
     if (typeof codeOrFn === 'function') {
-        codeOrFn(actor, tryTo, retryTo, within, hopeThat, step, faker);
-        return;
+        return codeOrFn(actor, tryTo, retryTo, within, hopeThat, step, faker);
     }
     const run = createSandbox(CODECEPT_ARG_NAMES, codeOrFn);
-    run(actor, tryTo, retryTo, within, hopeThat, step, faker);
+    return run(actor, tryTo, retryTo, within, hopeThat, step, faker);
 }
 function createSandbox(argNames, body) {
     const fn = new Function(...argNames, ...SHADOWED_GLOBALS, `'use strict';\n${body}`);

package/docs/api-testing/basics.md

@@ -0,0 +1,90 @@
+# API Testing Basics
+
+Explorbot tests REST APIs the same way it tests web apps: it plans scenarios, runs them, and reports results — no test scripts. Two AI agents do the work.
+
+**Chief** reads your endpoint, its OpenAPI spec, and any [knowledge](../workflow/knowledge.md) you've written, then plans test scenarios: what to send, and what a correct response looks like.
+
+**Curler** takes each scenario and executes it as real HTTP requests, checking the responses with assertions.
+
+The plans Chief writes are ordinary Explorbot [test plans](../workflow/test-plans.md) — plain markdown you can read, edit, and commit. The web and API sides share the same plan format and the same [reporting](../workflow/reporting.md).
+
+## Configure
+
+Point Explorbot at your API by adding an `api` key to your `explorbot.config.js`:
+
+```javascript
+export default {
+  ai: {
+    model: openrouter('openai/gpt-oss-20b:nitro'),
+    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+  },
+  api: {
+    baseEndpoint: 'http://localhost:3000/api/v1',
+    spec: ['http://localhost:3000/api/openapi.json'],
+    headers: {
+      Authorization: 'Bearer <token>',
+    },
+  },
+};
+```
+
+- **`baseEndpoint`** (required) — the base URL prepended to every request. Test steps use relative paths like `/users`; Curler adds the base for you.
+- **`spec`** (required) — one or more OpenAPI specs, given as HTTP(S) URLs or local file paths, in YAML or JSON. Chief uses the spec to plan; Curler uses it to look up schemas. Both agents refuse to run without one.
+- **`headers`** — sent with every request. This is where API keys and auth tokens go.
+
+See the [full configuration reference](../reference/configuration.md) for every option and [providers](../basics/providers.md) for choosing an AI model.
+
+### Authenticating
+
+If a static token in `headers` is enough, you're done. If you need to log in and fetch a token first, use the `bootstrap` hook — it runs once before any tests, and whatever headers it returns merge into every later request:
+
+```javascript
+api: {
+  baseEndpoint: 'http://localhost:3000/api/v1',
+  spec: ['http://localhost:3000/api/openapi.json'],
+  bootstrap: async ({ baseEndpoint }) => {
+    const res = await fetch(`${baseEndpoint}/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'admin@test.com', password: 'secret' }),
+    });
+    const { token } = await res.json();
+    return { Authorization: `Bearer ${token}` };
+  },
+},
+```
+
+A matching `teardown` hook runs after all tests finish — use it to clean up data.
+
+### 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.*`.
+
+## Your first run
+
+The minimal loop is plan, then test. Point Chief at an endpoint:
+
+```bash
+npx explorbot api plan /users
+```
+
+On startup Explorbot does a health check — a `GET /` against your base endpoint — so a bad URL or token fails immediately. Then Chief fetches sample data, reads the spec, and writes scenarios to `output/plans/users.md`. Hand that file to Curler:
+
+```bash
+npx explorbot api test output/plans/users.md
+```
+
+Curler runs the scenarios and prints how many passed and failed.
+
+## Output files
+
+| Output | Location | What it is |
+|--------|----------|------------|
+| Test plans | `output/plans/*.md` | Chief's scenarios — priorities, steps, expected outcomes |
+| Request logs | `output/requests/*.request.yaml` | Every HTTP request and response, for debugging |
+| Reports | via the shared [reporter](../workflow/reporting.md) | Pass/fail results, optionally sent to Testomat.io |
+
+## Next steps
+
+- [Planning API tests](./planning.md) — give Chief context and steer what it tests.
+- [Running API tests](./running-tests.md) — execute plans, read request logs, and run the full autonomous cycle.

package/docs/api-testing/planning.md

@@ -0,0 +1,57 @@
+# Planning API Tests
+
+Chief plans the scenarios; how good they are depends on the context you give it. Start by feeding it what it needs, then choose how aggressively it should probe.
+
+## Give Chief context
+
+**The API spec.** Chief reads the OpenAPI spec from your `spec` config to learn paths, methods, and request/response schemas. It also fetches live sample data from the endpoint — real IDs, enum values, field names — so the scenarios it writes reference data that actually exists instead of guessing. A good spec is the single biggest lever on plan quality.
+
+**Endpoint knowledge.** The spec says what an endpoint accepts, not how your business rules work. Add that with `know`:
+
+```bash
+npx explorbot api know /users "CRUD for users. Admin role required for writes. IDs are UUIDs."
+```
+
+This writes a markdown file under `knowledge/` with `endpoint:` frontmatter:
+
+```markdown
+---
+endpoint: "/users"
+---
+CRUD for users. Admin role required for writes. IDs are UUIDs.
+```
+
+Chief loads knowledge matching the endpoint it's planning. Running `know` again on the same endpoint appends to the file. See [knowledge](../workflow/knowledge.md) for how matching and files work.
+
+## Choose a planning style
+
+A style tells Chief what kind of tests to prioritize. Four ship by default:
+
+| Style | Focus |
+|-------|-------|
+| `normal` | Standard CRUD and happy paths — create, read, update, delete, verify status codes and schemas |
+| `curious` | Maximum coverage — every field, every enum value, arrays, defaults |
+| `psycho` | Malformed and extreme input — missing fields, injection payloads, wrong content types, boundary values |
+| `hacker` | Security probing — infers hidden endpoints and undocumented fields from responses, then tries privilege escalation, IDOR, and auth-bypass against them |
+
+Pick one with `--style`:
+
+```bash
+npx explorbot api plan /users --style hacker
+```
+
+Without `--style`, Chief uses `normal`. Styles are markdown files in `rules/chief/styles/`, so you can edit them or drop in your own. The cycling and customization mechanism is shared with web planning — see [planning styles](../workflow/planning-styles.md).
+
+## Replan from scratch or add to a plan
+
+By default a `plan` run generates a fresh set of scenarios. When a plan already exists in the same run, Chief compares against it and adds only new, non-duplicate scenarios — it won't re-propose behavior it already covered, even under a different style. Pass `--fresh` to discard the in-progress plan and start clean:
+
+```bash
+npx explorbot api plan /users --fresh
+```
+
+This is what [`explore`](./running-tests.md) uses to give each style its own clean plan.
+
+## Where plans land
+
+Chief saves each plan to `output/plans/`, named after the endpoint (for example `output/plans/users.md`). The file is a standard Explorbot [test plan](../workflow/test-plans.md): a suite of scenarios, each with steps, expected outcomes, and a priority. Read it, edit it, or commit it — then run it as described in [Running API tests](./running-tests.md).

package/docs/api-testing/running-tests.md

@@ -0,0 +1,55 @@
+# Running API Tests
+
+Once Chief has written a plan, Curler runs it. Curler reads each scenario and drives it to a pass or fail by making real HTTP requests and asserting on the responses.
+
+## Run a plan
+
+Point Curler at a plan file:
+
+```bash
+npx explorbot api test output/plans/users.md
+```
+
+With no index, Curler runs every pending test. Add an index to run a subset:
+
+```bash
+npx explorbot api test output/plans/users.md 1      # the first test
+npx explorbot api test output/plans/users.md 1-3    # tests 1 through 3
+npx explorbot api test output/plans/users.md 1,3,5  # specific tests
+npx explorbot api test output/plans/users.md *      # all pending tests
+```
+
+Curler prints a running log of requests and, at the end, how many tests passed and failed.
+
+## What Curler can do
+
+Curler works through AI tool calls. Its toolset:
+
+- **`request`** — make an HTTP request (any method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) with a body, headers, or query params. Returns status, timing, and a preview of the response; the full body is saved to disk. This is how Curler chains requests — it reads an ID from one response and feeds it into the next.
+- **`verifyStructure`** — check the response shape against a Zod schema. On success it reports the actual structure, which Curler uses to write correct value assertions.
+- **`verifyData`** — assert specific values with `expect()` (`toBe`, `toHaveProperty`, `toHaveLength`, and so on).
+- **`schemaFor`** — search the OpenAPI spec for related endpoints when a test needs to set up prerequisite data or discover a dependency.
+- **`record`** — note a finding or observation as the test runs.
+- **`finish`** / **`stop`** — mark the test complete, or abandon it when the scenario is impossible.
+
+Curler favors verification over trust: for writes, it follows up with a `GET` to confirm the data actually persisted rather than believing the write response alone.
+
+## Debugging with request logs
+
+Every request Curler makes is saved to `output/requests/` as a `.request.yaml` file — full URL, headers, body, status, and response. When a test fails and the log isn't enough, open these to see exactly what went over the wire, including a reproducible curl command.
+
+## Explore an endpoint end to end
+
+`explore` runs the whole cycle autonomously across every planning style:
+
+```bash
+npx explorbot api explore /users
+```
+
+For each style — `normal`, `curious`, `psycho`, `hacker` — it plans a fresh set of scenarios, runs them with Curler, and saves one plan file per style (`users_normal.md`, `users_hacker.md`, and so on). Scenarios are de-duplicated across styles, so the same test won't run twice. When every style is done, it prints the combined totals.
+
+Use `explore` to hammer an endpoint from every angle in one command; use `plan` plus `test` when you want to review or edit scenarios before running them.
+
+## Results and reporting
+
+Pass/fail results flow through Explorbot's shared reporter — the same one the web side uses. See [reporting](../workflow/reporting.md) for local reports and sending runs to Testomat.io.