explorbot 0.1.28 → 0.1.29

package/README.md

@@ -1,336 +1,178 @@
-# Explorbot
+<p align="center">
+  <img src="assets/explorbot-logo.png" alt="Explorbot" width="560">
+</p>
 
-**The vibe-testing agent for web applications.**
+<p align="center"><b>The vibe-testing agent for web applications.</b></p>
 
 ![Explorbot Terminal UI](https://github.com/testomatio/explorbot/blob/main/assets/screenshot.png)
 
-Explorbot explores your web app like a curious human would — clicking around, filling forms, finding bugs, and learning as it goes. No test scripts required. Just point it at your app and let it work.
+Explorbot is an AI agent that investigates your product like your most relentless QA engineer — clicking around, filling forms, and finding bugs. It turns every discovery into a test you can keep. No test scripts required. Just point it at your app and let it work.
 
 ```bash
 npx explorbot start https://your-app.com
 ```
 
-Explorbot is your first assitant in testing.
-It will do its best to use your application with no babysitting. It will use application and provide you valuable feedback.
+It runs with no babysitting and reports back what it finds. This is vibe-testing.
+
+New here? Read the [Getting Started guide](docs/getting-started.md).
 
 ## Use Cases
 
-* Autonomously test web application or its parts
+* Autonomously test a web application or parts of it
 * Discover test scenarios and get automated tests for them
-* Write manual test cases from exploring website
-* 24h/7d of monkey-testing for web application that can reveal hidden errors
+* Write manual test cases from exploring a website
+* 24/7 monkey-testing that reveals hidden errors
 * Quick-test for MVPs and prototypes
 
-Explorbot can start testing features which were not covered by unit tests or browser tests.
+Explorbot tests features that unit tests and scripted browser tests never reach.
 
 ## Demo
 
 ![Explorbot in action](https://github.com/testomatio/explorbot/blob/main/assets/demo.gif)
 
-## Requirements
-
-- NodeJS 24+ or **Bun**
-- **AI provider API key** — OpenRouter recommended; Groq, Cerebras, OpenAI, Anthropic, or others via [Vercel AI SDK](https://sdk.vercel.ai/providers)
-- **Modern terminal** — iTerm2, WARP, Kitty, Ghostty. WSL if running on Windows
-- **Compatible web app** — Check [docs/prerequisites.md](docs/prerequisites.md) to verify your app works with Explorbot
-
-## Quick Start
-
-**1. Install dependencies**
-
-```bash
-npm i explorbot --save
-npx playwright install
-```
-
-**2. Initialize config**
-
-```bash
-npx explorbot init
-```
-
-**3. Edit `explorbot.config.js`** — set your app URL and AI provider:
-
-> [!IMPORTANT]
-> **Explorbot uses three types of models:**
->
-> | Type | Config key | Purpose | Recommendation |
-> |------|-----------|---------|----------------|
-> | **model** | `ai.model` | Standard model for HTML/ARIA processing. Used by Tester, Navigator, Researcher. Should be fast and cheap — these agents are token-hungry. | e.g. `openai/gpt-oss-20b` |
-> | **visionModel** | `ai.visionModel` | Screenshot analysis. Used when agents need to visually inspect the page. | e.g. `meta-llama/llama-4-scout-17b-16e-instruct` |
-> | **agenticModel** | `ai.agenticModel` | Exceptional decision making. Used by Captain and Pilot — agents that read compact action logs and make high-level decisions. Benefits from a smarter model. | Strong agentic models but fast (MiniMax 2.5, Grok Fast, Qwen, …) |
->
-> See [OpenRouter](https://openrouter.ai/rankings#performance) for latency-focused model picks.
-
-This example uses **OpenRouter** (one API key, many providers). Any Vercel AI SDK provider works; see [docs/providers.md](docs/providers.md).
-
-```javascript
-import { createOpenRouter } from '@openrouter/ai-sdk-provider';
-
-const openrouter = createOpenRouter({
-  apiKey: process.env.OPENROUTER_API_KEY,
-});
-
-export default {
-  web: {
-    url: 'https://your-app.com',
-  },
-  ai: {
-    model: openrouter('openai/gpt-oss-20b'),
-    visionModel: openrouter('meta-llama/llama-4-scout-17b-16e-instruct'),
-    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
-  },
-};
-```
-
-> [!TIP]
-> Captain and Pilot barely use tokens (just action summaries), so a smarter `agenticModel` costs very little while significantly improving test quality. You can also override any agent's model individually via `ai.agents.<name>.model`.
-
-**4. Add knowledge** (optional but recommended)
-
-If your app requires authentication, tell Explorbot how to log in:
-
-```bash
-# Interactive mode
-npx explorbot learn
-
-# Or via CLI
-npx explorbot learn "/login" "Use credentials: admin@example.com / secret123"
-```
-
-> [!TIP]
-> Use `--session` to persist browser cookies and localStorage between runs. Log in once, and Explorbot will restore the session on next start:
-> ```bash
-> npx explorbot start /login --session          # saves to output/session.json
-> npx explorbot start /dashboard --session      # restores session, skips login
-> npx explorbot start /app --session auth.json  # custom session file
-> ```
-
-> [!NOTE]
-> Use `*` as URL pattern to add general knowledge that applies to all pages. See [docs/knowledge.md](docs/knowledge.md) for more.
-
-**5. Run**
-
-```bash
-npx explorbot start /admin/users
-```
-
-Start from a small functional area of your app (admin panel, settings, any CRUD section) so Explorbot can quickly understand its business purpose and context.
+## A new layer of testing
 
-Browser runs headless by default — use `--show` to see it:
+Unit tests check a function. End-to-end tests replay fixed user journeys. **Exploratory tests** investigate the app the way a curious tester would — taking new paths every run and catching what no one thought to script.
 
-```bash
-npx explorbot start /settings --show
-```
+Explorbot makes that third layer routine. It runs on your CI next to the other two, and everything stays local — no cloud service touches your app.
 
-Requires a modern terminal (iTerm2, WARP, Kitty, Ghostty, Windows Terminal). On Windows, use WSL.
+## How a session works
 
-## How It Works
+Give Explorbot a goal and a URL. A crew of agents takes it from there — no scripts, no human in the loop.
 
-Explorbot explores websites, analyzes their UI, and proposes tests — which it can then execute. It controls its own browser through CodeceptJS → Playwright (no MCP involved).
+1. **Research** — map the page into sections and index every element. No source or docs needed.
+2. **Plan** — draft test scenarios across normal, curious, and edge styles.
+3. **Execute** — drive the browser step by step, adapting as the app changes.
+4. **Verify** — confirm each outcome, cluster findings by root cause, and capture evidence.
+5. **Keep** — save passing flows as real tests, with reports and screencasts — and learn for next run.
 
 ![Explorbot Architecture](assets/architecture.png)
 
-Run `/explore` in TUI or use `explorbot explore` from CLI to watch the cycle: research → plan → test → repeat.
+## The crew
 
-**Supporting components:**
+Cheap, fast workers do the clicking and reading; smart managers make the calls — so a full session costs cents, not dollars.
 
-* **Pilot** — supervises Tester from a separate conversation: reviews action logs, detects stuck patterns, makes final pass/fail decisions. Uses `agenticModel` since it only processes compact summaries, not raw HTML
-* **Historian** — saves sessions as CodeceptJS code, learns from experience
-* **Quartermaster** — analyzes pages for A11y issues (axe-core + semantic)
-* **Reporter** — sends test results to Testomat.io
+| | | |
+|---|---|---|
+| [Researcher](docs/reference/agents.md) | [Planner](docs/reference/agents.md) | [Tester](docs/reference/agents.md) |
+| [Pilot](docs/reference/agents.md) | [Captain](docs/reference/agents.md) | [Navigator](docs/reference/agents.md) |
+| [Analyst](docs/reference/agents.md) | [Historian](docs/reference/agents.md) | [Fisherman](docs/reference/agents.md) |
 
-## Basic Usage
+See [Agents](docs/reference/agents.md) for what each one does.
 
-Once in the terminal UI:
+## Core Philosophy
 
-```
-/explore              # Full cycle: research → plan → test
-/research             # Analyze current page
-/plan                 # Generate test scenarios
-/test                 # Run next test
-/navigate /settings   # Go to a page
-```
+**Strategic decisions are deterministic** — the workflow (research → plan → test) is predictable and consistent.
 
-You can also run CodeceptJS commands directly:
+**Tactical decisions are AI-driven** — how to click a button, what to do when a modal appears, how to recover from an error.
 
-```
-I.click('Login')
-I.fillField('email', 'test@example.com')
-I.see('Welcome')
-```
+**Cheap workers, smart managers** — token-hungry agents run on a fast, cheap model. The decision-makers read only short action logs, so a smarter model there costs almost nothing.
 
-See [docs/commands.md](docs/commands.md) for all commands.
+**Explorbot learns from failure** — it reuses past experience with a page to make faster, better decisions next time.
 
-> [!NOTE]
-> Most TUI commands also have CLI equivalents that run headless and exit. For example, `explorbot research <url>` and `explorbot plan <path>` work without launching TUI. See [docs/commands.md](docs/commands.md) for the full mapping.
+**Explorbot needs your knowledge** — you guide it with plain-text notes and domain hints, loaded when the matching page opens.
 
-## What You Get
+When tuned, Explorbot **runs autonomously for hours**, trying new scenarios on its own. The more it runs, the more it learns.
 
-| Output | Location | Description |
-|--------|----------|-------------|
-| Test files | `output/tests/*.spec.ts` or `*.js` | Runnable Playwright or CodeceptJS tests |
-| Test plans | `output/plans/*.md` | Markdown documentation of scenarios |
-| Experience | `./experience/` | What Explorbot learned about your app |
+## What you get
 
-Every run is saved as a real Playwright or CodeceptJS test you can commit and run from CI. Configure the Historian to choose the output framework, record screencasts of every run, or both:
+Every run leaves behind:
 
-```js
-ai: {
-  agents: {
-    historian: {
-      framework: 'playwright',          // or 'codeceptjs' (default)
-      screencast: true,                 // record .webm video per scenario, chapters labelled with each step
-      // screencast: { size: { width: 1280, height: 720 }, quality: 95 }
-    },
-  },
-}
-```
+- **Runnable tests** — Playwright or CodeceptJS specs for every flow, ready to commit and run in CI.
+- **Reports** — a pass/fail breakdown with a written analysis, as HTML and Markdown, or in Testomat.io.
+- **Videos** — step-by-step screencasts of every run.
+- **Experience** — what Explorbot learned, reused to test smarter next time.
 
-Screencasts land in `output/screencasts/<plan>-<n>-<scenario>.webm` and are listed alongside generated tests at the end of every run.
+See [Automated Tests](docs/guides/automated-tests.md) for the test output and [Reporting](docs/guides/reporting.md) for reports.
 
-Playwright output uses the actual `page.locator(...)` calls executed during the run, with each action wrapped in `test.step` so failures land on a labelled step:
+## It works with your suite
 
-```ts
-test('Create a new manual plan', async ({ page }) => {
-  await test.step("Click the 'New plan' button in toolbar", async () => {
-    await page.getByRole('button', { name: 'New plan' }).first().click();
-  });
+Explorbot won't replace your regression tests — it covers what they can't. Your Playwright or CodeceptJS suites replay the same fixed steps every build. Explorbot re-explores the same pages new ways, clicking UI and paths your scripts never touch. Point it at a brand-new feature with zero coverage, and it works out the basic test cases and runs them right away.
 
-  await test.step('Select Manual plan type in modal', async () => {
-    await page.locator('#portal-container').getByRole('button', { name: 'Manual' }).click();
-  });
+## Requirements
 
-  await test.step('Verification', async () => {
-    await expect(page).toContainText('Test Plan UI Creation 001');
-  });
-});
-```
+- Node.js 24+ or **Bun**
+- An **AI provider key** — OpenRouter recommended; Groq, Cerebras, OpenAI, Anthropic, and others via the [Vercel AI SDK](https://sdk.vercel.ai/providers)
+- A **modern terminal** — iTerm2, WARP, Kitty, Ghostty, or Windows Terminal with WSL
+- A **compatible web app** — CRUD-heavy apps fit best. See [Prerequisites](docs/reference/prerequisites.md)
 
-See [Automated Tests](docs/automated-tests.md) for the CodeceptJS version and how failed or unfinished scenarios are handled.
+If your CI runs Playwright, it runs Explorbot. No GPUs, no special runners.
 
-## Two Ways to Run
+## Quick Start
 
-**Interactive mode** — Launch TUI, guide exploration, get real-time feedback:
+**1. Install dependencies**
 
 ```bash
-npx explorbot start https://your-app.com
+npm i explorbot --save
+npx playwright install
 ```
 
-**Autonomous mode** — Non-interactive testing and planning:
+**2. Initialize config**
 
 ```bash
-npx explorbot explore /admin/users
+npx explorbot init
 ```
 
-**Freesail mode** — Fully autonomous, continuous exploration across multiple pages:
-
-```bash
-npx explorbot freesail /admin              # explore and test pages indefinitely
-npx explorbot freesail /app --deep         # depth-first: explore nearby pages first
-npx explorbot freesail /app --shallow      # breadth-first: spread across many pages
-npx explorbot freesail /app --scope /admin # restrict to URLs under /admin
-```
+**3. Configure and run**
 
-Freesail navigates to a page, researches it, runs tests, then moves on to the next least-visited page — repeating until stopped. Also available as `/freesail` in TUI.
-
-## API Testing
-
-Explorbot also tests REST APIs. Add an `api` section to your config and point it at your API:
-
-```javascript
-export default {
-  web: {
-    url: 'http://localhost:3000',
-  },
-  ai: {
-    model: openrouter('openai/gpt-oss-20b'),
-    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>',
-    },
-  },
-};
-```
+Add your AI provider key to `.env`, set your app URL in `explorbot.config.js`, then point Explorbot at a focused page — an admin panel, settings, or any CRUD section:
 
 ```bash
-npx explorbot api explore /users          # full cycle: plan + test all styles
-npx explorbot api plan /users             # generate test plan only
-npx explorbot api test plans/users.md *   # run all tests from a plan
+npx explorbot start /admin/users
 ```
 
-The API tester uses two agents — **Chief** (plans test scenarios across styles: normal, curious, psycho, hacker) and **Curler** (executes HTTP requests and verifies responses). Both use `agenticModel` by default.
-
-See [docs/api-testing.md](docs/api-testing.md) for setup, authentication hooks, and full command reference.
+Type `/explore`, and Explorbot runs its loop on its own — research, plan, test, repeat — learning from every run.
 
-## Core Philosophy
-
-**Strategic decisions are deterministic** — The workflow (research → plan → test) is predictable and consistent.
-
-**Tactical decisions are AI-driven** — How to click that button, what to do when a modal appears, how to recover from errors.
-
-**Cheap workers, smart managers** — Tester, Navigator, and Researcher are token-hungry agents that chew through HTML and ARIA on every step. They run on the fast, cheap `model`. Captain and Pilot are the decision-makers — they read only compact action logs and make high-level choices. Set `agenticModel` to a smarter model for better results at negligible extra cost.
+That's the gist. The [**Getting Started guide**](docs/getting-started.md) walks through the full setup — choosing models, teaching Explorbot to log in, and picking the right feature to start on.
 
-**Explorbot learns from its failures** — It uses previous experience interacting with a web page for faster and better decisions on next runs.
+## Teaching Explorbot
 
-**Explorbot needs your knowledge** — You adjust Explorbot prompts by passing suggestions, UI explanations, and domain knowledge as text files, which are loaded when the corresponding page is opened.
+Explorbot gets better when you tell it about your app:
 
-When tuned, Explorbot **can run autonomously for hours** navigating a web application and trying different scenarios. You don't need to watch it. The more Explorbot runs, the more it learns and the more complex scenarios it can test.
+- **Knowledge** — credentials, form rules, navigation quirks. See [Knowledge](docs/guides/knowledge.md).
+- **Rules** — per-agent, per-page instructions. See [Configuration](docs/reference/configuration.md#rules).
+- **Experience** — learned automatically from what works.
 
+Handling logins, cookie banners, modals, and test data takes a few lines — see [Customization](docs/guides/customization.md).
 
-## Teaching Explorbot
+## It also tests REST APIs
 
-* **Knowledge** (`./knowledge/`) — Tell Explorbot about your app: credentials, form rules, navigation quirks. See [docs/knowledge.md](docs/knowledge.md).
-* **Rules** (`./rules/`) — Customize agent behavior with markdown files. Add page-specific instructions, override planning styles, or tune how agents work on different parts of your app. See [docs/configuration.md](docs/configuration.md#rules).
-* **Experience** (`./experience/`) — Explorbot learns automatically from successful interactions and saves what works.
+Point Explorbot at an OpenAPI spec and it plans and runs API tests too. See [API Testing](docs/guides/api-testing.md).
 
-## Further Reading
+## Keep going
 
-- [docs/prerequisites.md](docs/prerequisites.md) — Application compatibility checklist
-- [docs/commands.md](docs/commands.md) — Terminal command reference
-- [docs/api-testing.md](docs/api-testing.md) — API testing setup and commands
-- [docs/knowledge.md](docs/knowledge.md) — Knowledge system and URL patterns
-- [docs/providers.md](docs/providers.md) — AI provider configuration
-- [docs/agents.md](docs/agents.md) — Agent descriptions and capabilities
-- [docs/planner.md](docs/planner.md) — Planner agent: planning styles and customization
-- [docs/scripting.md](docs/scripting.md) — Building custom autonomous scripts
-- [docs/observability.md](docs/observability.md) — Langfuse tracing and debugging
-- [docs/page-interaction.md](docs/page-interaction.md) — How agents interact with pages
+When you're ready to go deeper, the [full documentation](docs/README.md) covers everything, starting with the [Getting Started guide](docs/getting-started.md).
 
 ## FAQ
 
-**Can I run it in Cursor? or Claude Code?**
-No, Explorbot is a separate application designed for constant testing. Cursor, Codex, or Claude Code are coding agents — not relevant here.
+**Can I run it in Cursor or Claude Code?**
+No, Explorbot is a separate application designed for constant testing. Cursor, Codex, and Claude Code are coding agents — not relevant here.
 
-> However, Explorbot can be used as subagent or terminal command which is controlled by coding agent.
+> However, Explorbot can be used as a subagent or terminal command controlled by a coding agent.
 
-**Can I bring Cursor or OpenAI Subscription?**
-No Cursor and OpenAI subscription can't be used. Mostly because their models are slow for Explorbot's usage. We recommend using pay-per-token via Groq and OpenRouter.
+**Can I bring a Cursor or OpenAI subscription?**
+No. Their models are too slow for the way Explorbot works. Use pay-per-token providers like Groq and OpenRouter.
 
 **I want to use Opus!!!**
-Opus is great for coding. But for testing we need a simpler model that can safely consume lots of HTML tokens. Opus must be used for sophisticated decision-making, while explorbot needs to collect knowledge from webpages and do it fast.
+Opus is great for coding. Testing needs a simpler model that can safely consume lots of HTML tokens, fast. Save the expensive models for sophisticated decision-making.
 
-**Is that expensive?**
+**Is it expensive?**
 No. With fast open models (e.g. `openai/gpt-oss-20b` on OpenRouter or Groq), expect roughly **~$1/hour of continuous run**, depending on provider and traffic.
 
 **Does Explorbot have MCP?**
 Not yet.
 
 **Can I build my own agents with it?**
-Yes, use the programmatic API. See [docs/scripting.md](docs/scripting.md).
+Yes, use the programmatic API. See [Scripting](docs/contributing/scripting.md).
 
-**Ok, but I can do the same in Cursor with Playwright MCP!**
+**Can I do the same in Cursor with Playwright MCP?**
 Good luck running it on CI!
 
 ## Development
 
 * Clone this repository
 * Use **Bun** to run TS and TSX with no building
-* Create a sample project under `example` directory:
+* Create a sample project under the `example` directory:
 
 ```
 ./bin/explorbot-cli.ts init --path example
@@ -351,7 +193,3 @@ Explorbot is licensed under the [Elastic License 2.0 (ELv2)](LICENSE).
 The only restriction: you may not offer Explorbot itself as a hosted/managed service (i.e., resell it as a product). This license is used by Elastic, Grafana, and other open-source companies.
 
 Explorbot is built by [Testomat.io](https://testomat.io).
-
----
-
-Explorbot learns as it explores. The more it tests your app, the better it gets at testing your app. That's vibe-testing.

package/bin/explorbot-cli.ts

@@ -338,6 +338,7 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
       const cmd = new TestCommand(explorBot);
       await cmd.execute(args);
 
+      await explorBot.printSessionAnalysis();
       await explorBot.stop();
       await showStatsAndExit(0);
     } catch (error) {

package/dist/bin/explorbot-cli.js

@@ -293,6 +293,7 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
         const { TestCommand } = await import('../src/commands/test-command.js');
         const cmd = new TestCommand(explorBot);
         await cmd.execute(args);
+        await explorBot.printSessionAnalysis();
         await explorBot.stop();
         await showStatsAndExit(0);
     }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -65,9 +65,10 @@
   },
   "author": "",
   "dependencies": {
-    "@ai-sdk/anthropic": "^3.0",
-    "@ai-sdk/groq": "^3.0",
-    "@ai-sdk/openai": "^3.0",
+    "@ai-sdk/anthropic": "^4.0",
+    "@ai-sdk/groq": "^4.0",
+    "@ai-sdk/openai": "^4.0",
+    "@ai-sdk/otel": "^1.0.2",
     "@axe-core/playwright": "^4.11.0",
     "@codeceptjs/reflection": "^0.5.2",
     "@faker-js/faker": "^10.4.0",
@@ -82,8 +83,8 @@
     "@opentelemetry/sdk-trace-base": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.38.0",
     "@scalar/openapi-parser": "^0.25.6",
-    "@testomatio/reporter": "^2.8.4",
-    "ai": "^6.0.6",
+    "@testomatio/reporter": "^2.9.1",
+    "ai": "^7.0.2",
     "axe-core": "^4.11.1",
     "bash-tool": "^1.3.15",
     "cli-highlight": "^2.1.11",
@@ -110,6 +111,7 @@
     "parse5": "^8.0.0",
     "playwright": "^1.60",
     "react": "^19.1.1",
+    "sambanova-ai-provider": "^1.2.2",
     "strip-ansi": "^7.1.2",
     "turndown": "^7.2.1",
     "unique-names-generator": "^4.7.1",

package/dist/rules/navigator/verification-actions.md

@@ -113,6 +113,8 @@ For input field values, ALWAYS use I.seeInField() — never check value via CSS
 Prefer text locators (label, name, placeholder) for form fields: I.seeInField('Search', 'value') over I.seeInField('input[name="search"]', 'value').
 Only use locators that exist in the provided HTML or ARIA snapshot.
 Verify exact conditions, not approximate matches.
+When the claim contains a concrete quoted value, generated assertion code MUST include that whole value. Do not shorten names, IDs, titles, emails, URLs, or other user-created values.
+For exact visible text, prefer a text assertion scoped to a specific container or an ARIA locator with the complete text. Partial text is not valid evidence for a claim about the full value.
 NEVER use `:has-text(...)` inside a seeElement/dontSeeElement locator. Checking text inside an element is the job of I.see(text, context) — the `:has-text()` form duplicates that capability with a fragile selector.
 NEVER emit two assertions that check the same fact with different shapes. `I.see(text, locator)` and `I.seeElement("<locator>:has-text('text')")` verify the same thing — pick one (prefer I.see). One claim, one assertion.
 </verification_rules>

package/dist/src/ai/fisherman.js

@@ -4,6 +4,7 @@ import { createDebug, tag } from "../utils/logger.js";
 const debugLog = createDebug('explorbot:fisherman');
 import { loop } from "../utils/loop.js";
 import { createFishermanTools } from "./fisherman-tools.js";
+import { dataProtectionRules } from "./rules.js";
 const MAX_ITERATIONS = 15;
 const MAX_TOOL_ROUNDTRIPS = 5;
 export class Fisherman {
@@ -65,7 +66,7 @@ export class Fisherman {
             spec: this.spec,
             baseEndpoint: this.baseEndpoint,
         });
-        const conversation = this.provider.startConversation(this.buildSystemPrompt(endpointList, scopeUrl), 'fisherman');
+        const conversation = this.provider.startConversation(this.buildSystemPrompt(endpointList, Object.keys(tools), scopeUrl), 'fisherman');
         conversation.addUserText(this.buildTaskPrompt(instructions));
         await loop(async ({ stop, iteration }) => {
             debugLog(`iteration ${iteration}`);
@@ -149,7 +150,7 @@ export class Fisherman {
         }
         return lines.join('\n');
     }
-    buildSystemPrompt(endpointList, scopeUrl) {
+    buildSystemPrompt(endpointList, toolNames, scopeUrl) {
         const scopeBlock = scopeUrl ? `\n\nSCOPE: You are operating within ${scopeUrl}.\nAll created items must belong to this scope.` : '';
         return dedent `
       You are Fisherman — a data preparation agent. You create test data by making API requests.
@@ -158,6 +159,11 @@ export class Fisherman {
       ${endpointList}
       ${scopeBlock}
 
+      AVAILABLE TOOLS:
+      ${toolNames.join(', ')}.
+      Use tool names exactly as listed. Do not invent aliases, combined names, or names with channel markers such as "commentary".
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
+
       WORKFLOW:
       1. Call getEndpointSpec to see the request body example for the endpoint
       2. Make requests — the response automatically extracts IDs, names, and status fields
@@ -169,6 +175,8 @@ export class Fisherman {
       - Chain requests logically — create parent resources before children
       - If a request fails, try once more with adjusted data before reporting failure
       - Use realistic but unique data for each item (vary names, titles)
+
+      ${dataProtectionRules}
     `;
     }
     buildTaskPrompt(instructions) {
@@ -177,7 +185,10 @@ export class Fisherman {
 
       ${instructions}
 
-      Execute the necessary API requests to create this data. When done, call finish with the summary.
+      ${dataProtectionRules}
+
+      If data preparation is allowed by these rules, execute the necessary API requests to create this data.
+      When done, call finish with the summary. If data preparation is forbidden, call stop with the reason.
     `;
     }
 }