explorbot 0.4.0 → 0.4.1

package/dist/src/remote.js

@@ -26,15 +26,6 @@ export class Remote {
     asks = new Map();
     askCounter = 0;
     lastActivity = null;
-    registerOption(program) {
-        program.option('--ws <url>', 'Stream this run to a remote UI over WebSocket');
-        program.hook('preAction', (_thisCommand, actionCommand) => {
-            const url = actionCommand.optsWithGlobals().ws || process.env.EXPLORBOT_WS_URL;
-            if (!url)
-                return;
-            this.attach(String(url), this.commandPath(actionCommand));
-        });
-    }
     attach(url, command) {
         if (this.url)
             return;
@@ -222,14 +213,5 @@ export class Remote {
             return failure.message;
         return undefined;
     }
-    commandPath(command) {
-        const parts = [];
-        let node = command;
-        while (node) {
-            parts.unshift(node.name());
-            node = node.parent;
-        }
-        return parts.slice(1).join(' ') || parts.join(' ');
-    }
 }
 export const remote = new Remote();

package/docs/api-testing/basics.md

@@ -56,6 +56,21 @@ api: {
 
 A matching `teardown` hook runs after all tests finish — use it to clean up data.
 
+### Without a config file
+
+Chief and Curler need three things: where the API is, what its spec says, and how to authenticate. Pass all three on the command line and no config file is needed:
+
+```bash
+npx explorbot api plan /users \
+  --endpoint https://api.example.com/v1 \
+  --spec ./openapi.yaml \
+  --knowledge 'Send X-Api-Key: ${env.API_KEY} on every request'
+```
+
+`--endpoint` and `--spec` each have an environment twin — `EXPLORBOT_URL` and `EXPLORBOT_API_SPEC` — and the flag wins when both are set. `--knowledge` adds to the facts `EXPLORBOT_KNOWLEDGE` and `EXPLORBOT_KNOWLEDGE_FILE` bring in rather than replacing them. Configure your models once with `npx explorbot init --global` and every run stores its plans and requests per host under `~/.explorbot/sites/<host>/`, so a later `api test` against the same API picks up where the last one left off. Knowledge given on the command line lasts for the run; `api know` is what writes it down.
+
+`--endpoint` keeps its path prefix: given `https://api.example.com/v1`, steps stay relative (`/users`) and Curler sends them to `https://api.example.com/v1/users`. `api test`, which takes a plan file rather than an endpoint, reads it from the flag or the variable.
+
 ### 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.*`.

package/docs/api-testing/planning.md

@@ -21,7 +21,16 @@ 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.
+Chief loads knowledge matching the endpoint it's planning, and Curler loads it again for the endpoint it's testing, so auth headers and payload rules reach the requests themselves. Running `know` again on the same endpoint appends to the file. See [knowledge](../workflow/knowledge.md) for how matching and files work.
+
+For a fact that should not be stored — a token, a one-off fixture — pass `--knowledge` instead. It applies to the run only:
+
+```bash
+npx explorbot api explore /users --knowledge '---
+endpoint: /users/*
+---
+Send X-Api-Key: ${env.API_KEY} on every request'
+```
 
 ## Choose a planning style
 

package/docs/reference/commands.md

@@ -33,7 +33,7 @@ Inside the TUI, use the matching slash command: `/explore`, `/research`, `/plan`
 | Generate test plan | `npx explorbot plan <path>` | `/plan [--focus <feature>]` | Writes plan markdown |
 | List saved plans | `npx explorbot plans [plan]` | `/plans [plan]` | Show plans and their tests |
 | Navigate to a URL | `npx explorbot navigate <url>` | `/navigate <target>` | Reachability probe + session capture |
-| Drill page components | `npx explorbot drill <url>` | `/drill [--knowledge <path>] [--max-components <n>]` | Learn interactions |
+| Drill page components | `npx explorbot drill <url>` | `/drill [--save-knowledge <path>] [--max-components <n>]` | Learn interactions |
 | Execute plan tests | `npx explorbot test <planfile> [index]` | `/test [scenario\|number\|*]` | Run scenarios |
 | Re-run generated tests | `npx explorbot rerun <file> [index]` | `/rerun <file> [index]` | With AI auto-healing |
 | List generated tests | `npx explorbot runs [file]` | `/runs [file]` | Index + dry-run |
@@ -69,6 +69,16 @@ Every CLI command that drives a browser accepts these options (`start`, `explore
 | `--incognito` | Run without recording experiences |
 | `--session [file]` | Save/restore browser session (cookies, localStorage) from file |
 
+### `--knowledge`
+
+Passes facts to the run without creating a file in `knowledge/`. Plain text applies everywhere; add frontmatter to scope it to a page or an API endpoint. Repeat the flag for several facts. See [Knowledge](../workflow/knowledge.md#per-session-knowledge).
+
+```bash
+npx explorbot explore /pay --knowledge 'Test card 4111 1111 1111 1111, any future expiry'
+```
+
+Like `--ws`, it is a program-level option rather than a per-command one: it works on every command — including `api`, `docs` and `prima` — and can go anywhere on the line. It is listed under `npx explorbot --help` rather than in each command's own help.
+
 ### `--session`
 
 Saves browser state (cookies, localStorage, sessionStorage) to a JSON file. The next run restores the session, so you skip login and setup steps.
@@ -104,6 +114,7 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 | `EXPLORBOT_EPHEMERAL` | Keep no state between runs — output goes to a fresh temp directory instead of the site dir |
 | `EXPLORBOT_KNOWLEDGE` | Inline knowledge text, applied to every page |
 | `EXPLORBOT_KNOWLEDGE_FILE` | Path to a knowledge markdown file |
+| `EXPLORBOT_SPEC` | Docbot application spec directory or index.md, used as page knowledge |
 | `EXPLORBOT_API_SPEC` | OpenAPI spec path for the API boat |
 | `EXPLORBOT_NO_BANNER` | Suppress the startup banner, for machine-readable output |
 | `EXPLORBOT_MAX_DURATION` | Wall-clock budget in minutes for an explore run; same as --max-duration |
@@ -444,18 +455,18 @@ Drill all components on a page to learn interactions.
 # CLI
 npx explorbot drill /components
 npx explorbot drill /components --max-components 10
-npx explorbot drill /login --knowledge /login
+npx explorbot drill /login --save-knowledge /login
 ```
 
 ```
 # TUI
 /drill
-/drill --knowledge /login --max-components 10
+/drill --save-knowledge /login --max-components 10
 ```
 
 | Option | Description |
 |---|---|
-| `--knowledge <path>` | Save learned interactions to a knowledge file at this URL path |
+| `--save-knowledge <path>` | Save learned interactions to a knowledge file at this URL path |
 | `--max-components <count>` | Maximum number of components to drill |
 
 ## Test Rerun
@@ -593,9 +604,15 @@ Crawl pages and generate a documentation spec with `Purpose`, `User Can`, and `U
 ```bash
 npx explorbot docs collect /users/sign_in
 npx explorbot docs collect /docs/openapi#tag/project-analytics-tags --max-pages 20
+npx explorbot docs collect /dashboard --url https://app.example.com
 npx explorbot docs collect https://teleportal.ua/ua/serials/stb/kod --path explorbot-testing --show --session --max-pages 20
 ```
 
+| Option | Description |
+|---|---|
+| `--url <url>` | Base URL of the site, for a relative path argument. Same as `EXPLORBOT_URL`; an absolute path argument carries its own |
+| `--max-pages <count>` | Stop after documenting this many pages |
+
 Output is written to:
 
 - `output/docs/spec.md`
@@ -718,6 +735,7 @@ Every command takes these:
 | `-i, --instance <name>` | Which prima-owned browser to talk to; parallel work needs one each |
 | `--session [file]` | Cookies and storage persisted across processes; ignored while attached, since the attached session keeps its own |
 | `--url <url>` | Page to open when the session has no page yet |
+| `--spec <path>` | A Docbot application spec directory or its `index.md`, read as page knowledge. Same as `EXPLORBOT_SPEC` / `PRIMA_CLI_SPEC` |
 | `--ephemeral` | Keep no state between runs. Applies to config-free runs only — with a config file the output directory comes from the config |
 | `--framework <name>` | Parsed but not active yet; reported code is CodeceptJS whatever you pass |
 | `-c, --config <path>`, `-p, --path <path>` | As on every other Explorbot command |
@@ -767,6 +785,8 @@ Prima follows the same [configuration ladder](#environment-variables) as every o
 EXPLORBOT_AI_PROVIDER=groq npx explorbot prima go https://app.example.com
 ```
 
+The three inputs a run needs beyond the model come from flags or the environment, so no file has to exist: `--url` / `PRIMA_CLI_URL` for the site, `--spec` / `PRIMA_CLI_SPEC` for collected documentation, and `--knowledge` / `PRIMA_CLI_KNOWLEDGE` for facts such as credentials. Every `EXPLORBOT_*` variable has a `PRIMA_CLI_*` twin that prima reads first.
+
 `pw` still works when no model is usable at all; commands that need one say so and point at the fallback.
 
 ## Plan Management

package/docs/workflow/agentic-usage.md

@@ -56,6 +56,7 @@ No `init`, no config file, no project directory, no model IDs to look up. These
 | `EXPLORBOT_EPHEMERAL` | no | Keep no state between runs — output goes to a fresh temp directory instead of the site dir |
 | `EXPLORBOT_KNOWLEDGE` | no | Inline knowledge text, applied to every page |
 | `EXPLORBOT_KNOWLEDGE_FILE` | no | Path to a knowledge markdown file |
+| `EXPLORBOT_SPEC` | no | Docbot application spec directory or index.md, used as page knowledge |
 | `EXPLORBOT_API_SPEC` | no | OpenAPI spec path for the API boat |
 | `EXPLORBOT_NO_BANNER` | no | Suppress the startup banner, for machine-readable output |
 | `EXPLORBOT_MAX_DURATION` | no | Wall-clock budget in minutes for an explore run; same as --max-duration |
@@ -124,6 +125,12 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 EXPLORBOT_KNOWLEDGE_FILE=./checkout-knowledge.md npx explorbot explore /checkout
 ```
 
+Both variables work in config-free runs and in runs on the global configuration, where what they carry is written into the site's knowledge directory for that run — rewritten on the next run, and removed by a run that sets neither variable. Facts worth keeping belong in `learn` or `know`. The `--knowledge` flag does the same thing as an argument, works with a project config as well, and writes nothing, so prefer it when one command needs one fact:
+
+```bash
+npx explorbot explore /checkout --knowledge 'Use the sandbox card 4111 1111 1111 1111'
+```
+
 ### What this mode changes
 
 Config-free runs leave no trace in the working directory:
@@ -213,9 +220,11 @@ The same variables drive API testing and doc collection.
 EXPLORBOT_URL=https://api.example.com \
 EXPLORBOT_API_SPEC=./openapi.yaml \
 EXPLORBOT_AI_PROVIDER=openrouter \
-  npx explorbot api explore
+  npx explorbot api explore /users
 ```
 
+The API boat also takes those two as flags, so one line carries the whole run: `npx explorbot api explore /users --endpoint https://api.example.com --spec ./openapi.yaml`.
+
 ```bash
 EXPLORBOT_AI_PROVIDER=openrouter \
   npx explorbot docs collect https://app.example.com/dashboard --max-pages 20
@@ -223,7 +232,7 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 
 `docs collect` takes its base URL from the absolute path argument, so `EXPLORBOT_URL` is optional there.
 
-Knowledge written by `EXPLORBOT_KNOWLEDGE` carries `endpoint: '*'` frontmatter alongside `url: '*'`, matching the convention `api init` and `api know` use. The API boat does not read knowledge at runtime yet; the frontmatter is there for when it does, and the web side ignores it.
+Knowledge written by `EXPLORBOT_KNOWLEDGE` carries `endpoint: '*'` frontmatter alongside `url: '*'`, matching the convention `api init` and `api know` use, so one variable reaches both boats.
 
 ## See Also
 

package/docs/workflow/knowledge.md

@@ -45,7 +45,48 @@ While exploring, use the `/learn` command.
 
 ### API Testing
 
-[API testing](../api-testing/basics.md) shares the same `knowledge/` directory. `npx explorbot api know <endpoint> "<description>"` adds endpoint-scoped notes, stored with an `endpoint:` frontmatter field instead of `url:`.
+[API testing](../api-testing/basics.md) shares the same `knowledge/` directory. `npx explorbot api know <endpoint> "<description>"` adds endpoint-scoped notes, stored with an `endpoint:` frontmatter field instead of `url:`. Chief reads them when planning an endpoint and Curler reads them when running its tests, so auth headers and payload rules reach both.
+
+## Per-Session Knowledge
+
+`--knowledge` passes facts to a single run. Nothing is written to `knowledge/`, so credentials and one-off test data stay out of the repository.
+
+```bash
+npx explorbot explore /pay --knowledge 'My credit card is 4111 1111 1111 1111'
+```
+
+Plain text applies to every page. Add frontmatter to scope it, with the same URL patterns knowledge files use:
+
+```bash
+npx explorbot explore / --knowledge '---
+url: /pay
+---
+Use the sandbox card 4111 1111 1111 1111 with any future expiry'
+```
+
+Repeat the flag for several facts:
+
+```bash
+npx explorbot explore / \
+  --knowledge '---
+url: /login
+---
+Log in as admin@example.com / secret123' \
+  --knowledge 'Dismiss the cookie banner before anything else'
+```
+
+Everything a knowledge file supports works here: `${env.VAR}` interpolation, and page automation fields such as `wait` and `waitForElement`.
+
+The flag works on every command of `explorbot`, `explorbot api`, `explorbot docs` and `prima`, and can go anywhere on the line. Scope API knowledge with `endpoint:` instead of `url:`:
+
+```bash
+npx explorbot api explore /orders --knowledge '---
+endpoint: /orders/*
+---
+Send X-Api-Key: ${env.API_KEY} on every request'
+```
+
+For runs driven from the environment — config-free, or on the global configuration — `EXPLORBOT_KNOWLEDGE` does the same job for the length of one run. See [Agentic usage](./agentic-usage.md).
 
 ## URL Patterns
 
@@ -81,10 +122,13 @@ Notes:
 
 | Field | Purpose |
 |-------|---------|
-| `url` | URL pattern to match (optional, defaults to `*`) |
+| `url` | Page URL pattern to match |
+| `endpoint` | API endpoint pattern to match |
 | `title` | Human-readable title (optional) |
 | Custom fields | Any additional metadata for agents |
 
+`url` scopes a file to browser pages and `endpoint` scopes it to API endpoints. A file with neither applies to both.
+
 ## Variables
 
 Knowledge files support variable interpolation with `${namespace.key}` syntax. Explorbot resolves variables when it loads the knowledge.

package/package.json

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

package/rules/planner/styles/normal.md

@@ -1,7 +1,7 @@
 Study the page and figure out its business purpose. What is this page FOR? What would a user come here to do?
 
 Based on the page type, propose tests for COMPLETE user workflows:
-- If this is a data page (lists, tables): test CRUD operations end-to-end (create item → verify in list, edit item → verify changes saved, delete item → verify removed)
+- If this is a data page (lists, tables): test create, edit and delete as separate tests, each preparing the item it acts on
 - If the page has inputs to fill in: test the full commit flow, not just that the controls render
 - If this has filters and search: test filtering AND verify results change, not just "filter tab clicked"
 - If this has modals/dropdowns: test the ACTION inside them, not just opening/closing them

package/src/ai/captain.ts

@@ -160,7 +160,7 @@ export class Captain extends CaptainBase implements Agent {
     const headingsBlock = headingLines.join('\n');
 
     let pageSummary = '';
-    const cachedResearch = Researcher.getCachedResearch(state);
+    const cachedResearch = Researcher.getCachedResearch(actionResult);
     if (cachedResearch) {
       pageSummary = `<page_summary>\n${this.explorBot.agentResearcher().extractBrief(cachedResearch)}\n</page_summary>`;
     }

package/src/ai/navigator.ts

@@ -575,7 +575,7 @@ class Navigator implements Agent {
     }
 
     const currentActionResult = actionResult || ActionResult.fromState(state);
-    const research = Researcher.getCachedResearch(state) || '';
+    const research = Researcher.getCachedResearch(currentActionResult) || '';
     const combinedHtml = await currentActionResult.combinedHtml();
 
     const history = stateManager.getStateHistory();

package/src/ai/planner.ts

@@ -114,11 +114,15 @@ export class Planner extends PlannerBase implements Agent {
       Tests must be relevant to the page
       Tests must be achievable from UI
       Tests must be verifiable from UI
-      NEVER split one workflow into multiple tests. Each test must be a complete end-to-end flow.
+      One test verifies ONE business operation: the steps that reach it, the action itself, and its verification.
+      Steps that only reach the action — opening a form, expanding a panel, creating or locating the item to act on — belong to that test. A second operation with its own verification does not.
       Bad: "Open delete dropdown" + "Confirm deletion" — these are ONE test, not two.
       Bad: "Search for X" + "Verify search results" — searching and verifying is ONE test.
       Bad: "Leave field empty" + "Click submit" — that's one negative test, not two.
-      If two scenarios cannot run independently (one requires the other to run first), merge them into one.${featureDirective}${focusExistingDataDirective}
+      Bad: "Create a record, rename it, delete it" — three verified operations, so THREE tests, not one.
+      Good: "Rename existing record and verify the new title" — ONE test; creating is skipped, we assume record already exists, only the rename is verified.
+      You may rely on another test having run first in case we deal with empty state and no relevant data was created yet and we expect another our test creates it
+      When the page reports a record is missing or unavailable, it is not a testable surface — plan list-level or recovery behavior instead of operations on that record.${featureDirective}${focusExistingDataDirective}
     </task>
 
     ${customPrompt || ''}
@@ -195,10 +199,6 @@ export class Planner extends PlannerBase implements Agent {
         throw new Error('No tasks were created successfully');
       }
 
-      if (aiResult.object.scenarios.length === 0 && !this.currentPlan) {
-        throw new Error('No tasks were created successfully');
-      }
-
       const defaultStartUrl = this.getDefaultStartUrl(state);
       const fromPlanning = aiResult.object.scenarios.map((s: any) => new Test(s.scenario, s.priority, s.expectedOutcomes, s.startUrl || defaultStartUrl, s.steps || []));
 
@@ -335,6 +335,7 @@ export class Planner extends PlannerBase implements Agent {
       <task>
       Based on the page research, create ${this.MIN_TASKS}-${this.MAX_TASKS} exploratory testing scenarios.
       For each scenario provide specific steps and expected outcomes.
+      Exception: if the page reports the requested resource is missing, shows a failure state, or holds no content and no controls, return an empty scenarios list. Never invent tests for a page with nothing to exercise.
       </task>
 
       <rules>
@@ -348,13 +349,13 @@ export class Planner extends PlannerBase implements Agent {
       Focus on error or success messages as outcome.
       Focus on URL page change or data persistency after page reload.
       If there are subpages (pages with same URL path) plan testing of those subpages as well
-      If you plan to test CRUD operations, plan them in correct order: create, read, update.
+      Plan CRUD operations in order: create, read, update, delete.
       Do not invent specific route names, success messages, validation texts, badge counts, or welcome messages unless they are visible in research, visited pages, or prior observed flows.
       When validation placement or wording was not observed, require feedback associated with the invalid input without inventing a specific location or message.
       If exact wording is unknown, describe the expected result generically, for example "an authentication error is shown" or "the user stays on the login page" instead of guessing the literal text.
       If exact redirect destination is unknown, describe the destination by visible page identity, for example "the dashboard page opens" or "the current workspace home page opens" instead of inventing a URL slug.
       Only propose scenarios whose prerequisites are evident from page research, visited pages, or API data preparation context.
-      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible or API preconditions can create it.
+      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible, API preconditions can create it, or the scenario itself creates the record as its setup.
       If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks write controls, prefer read-only scenarios such as opening panels, inspecting visible lists, filtering, searching, or verifying current state.
       Do not assume hidden data exists just because a control is present.
       For scenarios that act on existing items or search/filter by existing values, use only item names or values visible in research, visited pages, or prior observed flows.

package/src/ai/researcher.ts

@@ -76,6 +76,7 @@ export class Researcher extends ResearcherBase implements Agent {
   }
 
   static getCachedResearch(state: WebPageState): string {
+    if (state instanceof ActionResult) return getCachedResearch(state.baseHash);
     return getCachedResearch(ActionResult.fromState(state).baseHash);
   }
 

package/src/ai/rules.ts

@@ -154,11 +154,11 @@ export const protectionRule = dedent`
 
   Pre-existing data on the page belongs to the application, not the test.
   Items that were not created inside the current test scenario must not be deleted, removed, emptied, reset, archived, or otherwise destroyed.
-  If a scenario needs to verify destructive behaviour, the same scenario must first create a disposable target and then destroy that specific target — never operate on data that was already there when the test started.
+  If a scenario needs to verify destructive behaviour, the same scenario must first create its own target and then destroy that specific target — never operate on data that was already there when the test started.
 
   The resource that the current page URL represents is "under test".
   The test must not destroy the resource it is running against — doing so invalidates every subsequent scenario that starts on the same URL.
-  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on disposable children created within the scenario itself.
+  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on children created within the scenario itself.
   </important>
 `;
 
@@ -174,7 +174,7 @@ export const dataProtectionRules = dedent`
   filter, tab, or list-inspection constraint. Use visible existing data when it is available.
   If no suitable data exists, report the missing precondition instead of creating data.
 
-  Destructive actions are allowed only against disposable data created by the current scenario
+  Destructive actions are allowed only against data created by the current scenario
   or prepared for that scenario by Fisherman/API preconditions. Existing application data must
   remain unchanged.
   </data_protection_rules>

package/src/api/spec-reader.ts

@@ -6,7 +6,7 @@ import { tag } from '../utils/logger.ts';
 
 export function validateSpecs(specs?: string[]): void {
   if (!specs?.length) {
-    throw new Error('API spec is required. Set api.spec in your config file.');
+    throw new Error('API spec is required. Pass --spec, set EXPLORBOT_API_SPEC, or set api.spec in your config file.');
   }
 }
 

package/src/commands/config-command.ts

@@ -37,7 +37,7 @@ export class ConfigCommand extends BaseCommand {
     const dirs: Record<string, string> = {};
     if (options.root) {
       for (const [name, dir] of Object.entries({ output: 'output', ...config.dirs })) {
-        dirs[name] = path.join(options.root, dir);
+        dirs[name] = path.resolve(options.root, dir);
       }
     }
 

package/src/commands/drill-command.ts

@@ -26,7 +26,7 @@ export class DrillCommand extends BaseCommand {
   }
 
   private parseKnowledgeArg(args: string): string | undefined {
-    const match = args.match(/--knowledge\s+(\S+)/);
+    const match = args.match(/--save-knowledge\s+(\S+)/);
     return match ? match[1] : undefined;
   }
 

package/src/commands/explore-command.ts

@@ -261,9 +261,15 @@ export class ExploreCommand extends BaseCommand {
       tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
       try {
         await this.explorBot.visit(pick.url);
+        const errorPage = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
+        if (errorPage) {
+          tag('warning').log(`Skipping sub-page: ${errorPage.message}`);
+          this.failedSubPages.add(normalizeUrl(pick.url));
+          continue;
+        }
         await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans, styles);
         const subPlan = this.explorBot.getCurrentPlan();
-        if (subPlan && !this.completedPlans.includes(subPlan)) {
+        if (subPlan?.tests.length && !this.completedPlans.includes(subPlan)) {
           this.completedPlans.push(subPlan);
         }
         knownUrls.add(normalizeUrl(pick.url));
@@ -298,6 +304,11 @@ export class ExploreCommand extends BaseCommand {
       if (fresh && parentPlan) opts.extend = parentPlan;
       if (this.dryRun) opts.noSave = true;
       await this.planWithRetry(feature, opts, pageUrl);
+      const plan = this.explorBot.getCurrentPlan();
+      if (plan && plan.tests.length === 0) {
+        tag('warning').log('Nothing to test on this page, moving on');
+        return;
+      }
       await this.runPendingTests();
       this.rememberCurrentPlan();
       fresh = false;

package/src/commands/options/base-option.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander';
+
+export abstract class BaseOption {
+  abstract flags: string;
+  abstract description: string;
+  collect?: (value: string, previous: any) => any;
+
+  register(program: Command): void {
+    if (this.collect) program.option(this.flags, this.description, this.collect);
+    if (!this.collect) program.option(this.flags, this.description);
+
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+      this.apply(actionCommand.optsWithGlobals(), actionCommand);
+    });
+  }
+
+  protected abstract apply(options: Record<string, any>, command: Command): void;
+}

package/src/commands/options/index.ts

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

package/src/commands/options/knowledge-option.ts

@@ -0,0 +1,14 @@
+import { KnowledgeTracker } from '../../knowledge-tracker.js';
+import { BaseOption } from './base-option.js';
+
+export class KnowledgeOption extends BaseOption {
+  flags = '--knowledge <text>';
+  description = 'Knowledge for this run only, not saved to disk. Markdown text; add url: or endpoint: frontmatter to scope it, otherwise it applies everywhere. Repeatable';
+  collect = (value: string, previous: string[] = []) => [...previous, value];
+
+  protected apply(options: Record<string, any>): void {
+    for (const text of options.knowledge || []) {
+      KnowledgeTracker.appendSessionKnowledge(text);
+    }
+  }
+}

package/src/commands/options/ws-option.ts

@@ -0,0 +1,24 @@
+import type { Command } from 'commander';
+import { remote } from '../../remote.js';
+import { BaseOption } from './base-option.js';
+
+export class WsOption extends BaseOption {
+  flags = '--ws <url>';
+  description = 'Stream this run to a remote UI over WebSocket';
+
+  protected apply(options: Record<string, any>, command: Command): void {
+    const url = options.ws || process.env.EXPLORBOT_WS_URL;
+    if (!url) return;
+    remote.attach(String(url), commandPath(command));
+  }
+}
+
+function commandPath(command: Command): string {
+  const parts: string[] = [];
+  let node: Command | null = command;
+  while (node) {
+    parts.unshift(node.name());
+    node = node.parent;
+  }
+  return parts.slice(1).join(' ') || parts.join(' ');
+}

package/src/config.ts

@@ -271,6 +271,7 @@ export const EXPLORBOT_ENV_VARS: EnvVar[] = [
   { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
   { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
   { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
+  { name: 'EXPLORBOT_SPEC', description: 'Docbot application spec directory or index.md, used as page knowledge' },
   { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
   { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
   { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
@@ -405,6 +406,8 @@ export class ConfigParser {
         this.enterGlobalMode(this.config, target);
       }
 
+      this.applyEnvSpec(this.config);
+
       // Restore original directory after successful config load
       if (options?.path && originalCwd !== process.cwd()) {
         process.chdir(originalCwd);
@@ -555,10 +558,18 @@ export class ConfigParser {
 
     config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
     config.playwright = { ...config.playwright, browser: config.playwright?.browser || 'chromium', url: site.baseUrl };
+    materializeKnowledge(this.site.dir);
 
     log(`Global mode: ${site.baseUrl} stored in ${this.site.dir}`);
   }
 
+  private applyEnvSpec(config: ExplorbotConfig): void {
+    const spec = process.env.EXPLORBOT_SPEC;
+    if (!spec) return;
+    if (!config.dirs) config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
+    config.dirs.spec = spec;
+  }
+
   private async buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig> {
     const provider = process.env.EXPLORBOT_AI_PROVIDER;
     const modelSpec = process.env.EXPLORBOT_AI_MODEL;

package/src/explorbot.ts

@@ -166,7 +166,7 @@ export class ExplorBot {
   }
 
   knowledgeTracker(): KnowledgeTracker {
-    return (this._knowledgeTracker ||= new KnowledgeTracker(this.options.applicationSpec));
+    return (this._knowledgeTracker ||= new KnowledgeTracker({ applicationSpec: this.options.applicationSpec }));
   }
 
   experienceTracker(): ExperienceTracker {