explorbot 0.3.5 → 0.4.1

package/bin/explorbot-cli.ts

@@ -10,6 +10,7 @@ import React from 'react';
 import { flushTelemetry } from '../src/ai/provider.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
+import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
@@ -28,7 +29,8 @@ const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../p
 const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version as string;
 
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
-remote.registerOption(program);
+wsOption.register(program);
+knowledgeOption.register(program);
 
 process.on('uncaughtException', async (error) => {
   tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);
@@ -146,6 +148,7 @@ addCommonOptions(
     .command('explore <path>')
     .description('Explore a page autonomously and run invented scenarios')
     .option('--max-tests <count>', 'Maximum number of tests to run')
+    .option('--max-duration <minutes>', 'Wall-clock budget in minutes for the whole run; wraps up before the limit is hit')
     .option('--focus <feature>', 'Focus area for exploration')
     .option('--configure <spec>', 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"')
     .option('--dry-run', 'Mark picked tests as skipped without executing or generating new ones')
@@ -157,6 +160,8 @@ addCommonOptions(
     const { ExploreCommand } = await import('../src/commands/explore-command.js');
     const cmd = new ExploreCommand(explorBot);
     if (options.maxTests) cmd.maxTests = Number.parseInt(options.maxTests, 10);
+    if (options.maxDuration) cmd.maxDurationMinutes = Number.parseInt(options.maxDuration, 10);
+    else if (process.env.EXPLORBOT_MAX_DURATION) cmd.maxDurationMinutes = Number.parseInt(process.env.EXPLORBOT_MAX_DURATION, 10);
     if (options.dryRun) cmd.dryRun = true;
     const execArgs: string[] = [];
     if (options.focus) execArgs.push('--focus', `"${options.focus}"`);
@@ -257,14 +262,13 @@ addCommonOptions(program.command('plan <path>').description('Generate test plan
 
 addCommonOptions(program.command('plan:load <planfile> [index]').description('Load a plan file and display its tests. Pass index to see test details.')).action(async (planfile: string, index: string | undefined) => {
   try {
-    const resolvedPath = path.resolve(planfile);
-    if (!fs.existsSync(resolvedPath)) {
-      console.error(`Plan file not found: ${resolvedPath}`);
+    const plan = Plan.loadFromFile(planfile);
+    if (!plan?.filePath) {
+      console.error(`Plan file not found: ${planfile}`);
       process.exit(1);
     }
 
-    const plan = Plan.fromMarkdown(resolvedPath);
-    const planFile = path.basename(resolvedPath);
+    const planFile = path.basename(plan.filePath);
 
     if (index) {
       const idx = Number.parseInt(index, 10);
@@ -276,7 +280,7 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
       const lines: string[] = [];
       lines.push(`## #${idx} ${test.scenario}\n`);
       lines.push(`**Priority:** ${test.priority}`);
-      const planUrl = plan.url || plan.tests[0]?.startUrl;
+      const planUrl = plan.startUrl;
       if (planUrl) lines.push(`**Plan URL:** ${planUrl}`);
       if (test.startUrl && test.startUrl !== planUrl) lines.push(`**Test URL:** ${test.startUrl}`);
       if (test.plannedSteps.length) {
@@ -293,7 +297,7 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
       return;
     }
 
-    const planUrl = plan.url || plan.tests[0]?.startUrl;
+    const planUrl = plan.startUrl;
     const lines: string[] = [`**${plan.title}** (${plan.tests.length} tests)\n`];
     if (planUrl) {
       lines.push(`URL: ${planUrl}\n`);
@@ -325,9 +329,6 @@ addCommonOptions(program.command('plan:load <planfile> [index]').description('Lo
 addCommonOptions(program.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1,3, 1-5, *, all').option('--grep <pattern>', 'Run tests matching pattern').option('--from-plan <file>', 'Load plan file when the first argument is a test index')).action(
   async (planfile, index, options) => {
     try {
-      const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));
-      await explorBot.start();
-
       let planfileArg = planfile;
       let indexArg = index;
       if (options.fromPlan) {
@@ -335,11 +336,16 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
         indexArg = planfile;
       }
 
+      const planTarget = Plan.loadFromFile(planfileArg)?.startUrl;
+
+      const explorBot = new ExplorBot(buildExplorBotOptions(planTarget, options));
+      await explorBot.start();
+
       const plan = explorBot.loadPlan(planfileArg);
       const pending = plan.getPendingTests();
       log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests, ${pending.length} pending)`);
 
-      const startUrl = plan.url || pending[0]?.startUrl;
+      const startUrl = plan.startUrl;
       if (!startUrl) {
         throw new Error('No URL found in plan or tests. Cannot determine where to navigate.');
       }
@@ -347,7 +353,7 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
       log(`Navigating to ${startUrl}`);
       await explorBot.visit(startUrl);
 
-      let args = '';
+      let args = '*';
       if (indexArg) args = indexArg;
       else if (options.grep) args = options.grep;
 
@@ -437,10 +443,11 @@ addCommonOptions(
     .option('--shallow', 'Breadth-first: pick globally least-visited page')
     .option('--scope <prefix>', 'Restrict navigation to URL prefix')
     .option('--max-tests <count>', 'Maximum number of tests to run')
+    .option('--max-duration <minutes>', 'Wall-clock budget in minutes for the whole run')
 ).action(async (startUrl, options) => {
   const explorBot = new ExplorBot(buildExplorBotOptions(startUrl || '/', options));
   await explorBot.start();
-  const args = [options.deep && '--deep', options.shallow && '--shallow', options.scope && `--scope ${options.scope}`, options.maxTests && `--max-tests ${options.maxTests}`].filter(Boolean).join(' ');
+  const args = [options.deep && '--deep', options.shallow && '--shallow', options.scope && `--scope ${options.scope}`, options.maxTests && `--max-tests ${options.maxTests}`, options.maxDuration && `--max-duration ${options.maxDuration}`].filter(Boolean).join(' ');
   const { FreesailCommand } = await import('../src/commands/freesail-command.js');
   const cmd = new FreesailCommand(explorBot);
   await cmd.execute(args);
@@ -701,7 +708,7 @@ addCommonOptions(program.command('navigate <url>').description('Navigate to a UR
 });
 
 addCommonOptions(
-  program.command('drill <url>').alias('driller').description('Drill all components on a page to learn interactions').option('--knowledge <path>', 'Save learned interactions to knowledge file at this URL path').option('--max-components <count>', 'Maximum number of components to drill')
+  program.command('drill <url>').alias('driller').description('Drill all components on a page to learn interactions').option('--save-knowledge <path>', 'Save learned interactions to knowledge file at this URL path').option('--max-components <count>', 'Maximum number of components to drill')
 ).action(async (url, options) => {
   try {
     const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
@@ -710,7 +717,7 @@ addCommonOptions(
     await explorBot.visit(url);
 
     const plan = await explorBot.agentDriller().drill({
-      knowledgePath: options.knowledge,
+      knowledgePath: options.saveKnowledge,
       maxComponents: Number.parseInt(options.maxComponents || '30', 10),
       interactive: false,
     });

package/boat/api-tester/src/ai/chief.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { Conversation } from '../../../../src/ai/conversation.ts';
 import { WithSessionDedup } from '../../../../src/ai/planner/session-dedup.ts';
 import type { AIProvider } from '../../../../src/ai/provider.ts';
+import type { KnowledgeTracker } from '../../../../src/knowledge-tracker.ts';
 import { Observability } from '../../../../src/observability.ts';
 import { Plan, Test } from '../../../../src/test-plan.ts';
 import { createDebug, tag } from '../../../../src/utils/logger.ts';
@@ -33,17 +34,19 @@ export class Chief extends ChiefBase {
   private provider: AIProvider;
   private config: ApibotConfig;
   private apiClient: ApiClient | null;
+  private knowledgeTracker?: KnowledgeTracker;
   currentPlan: Plan | null = null;
   private lastStyleName = '';
 
   MIN_TASKS = 3;
   MAX_TASKS = 10;
 
-  constructor(provider: AIProvider, config: ApibotConfig, apiClient?: ApiClient | null) {
+  constructor(provider: AIProvider, config: ApibotConfig, apiClient?: ApiClient | null, knowledgeTracker?: KnowledgeTracker) {
     super();
     this.provider = provider;
     this.config = config;
     this.apiClient = apiClient || null;
+    this.knowledgeTracker = knowledgeTracker;
   }
 
   async plan(endpoint: string, opts?: { style?: string; specDefinition?: string }): Promise<Plan> {
@@ -56,6 +59,9 @@ export class Chief extends ChiefBase {
       const sampleData = await this.collectSampleData(endpoint);
       const conversation = this.buildConversation(endpoint, opts?.style, sampleData);
 
+      const knowledge = this.knowledgeTracker?.renderEndpointKnowledge(endpoint);
+      if (knowledge) conversation.addUserText(knowledge);
+
       if (opts?.specDefinition) {
         conversation.addUserText(dedent`
           <api_spec>

package/boat/api-tester/src/ai/curler.ts

@@ -2,6 +2,7 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import type { AIProvider } from '../../../../src/ai/provider.ts';
 import type { RequestStore } from '../../../../src/api/request-store.ts';
+import type { KnowledgeTracker } from '../../../../src/knowledge-tracker.ts';
 import type { Reporter } from '../../../../src/reporter.ts';
 import { type Test, TestResult } from '../../../../src/test-plan.ts';
 import { createDebug, tag } from '../../../../src/utils/logger.ts';
@@ -18,12 +19,14 @@ export class Curler {
   private apiClient: ApiClient;
   private requestState: RequestStore;
   private reporter: Reporter;
+  private knowledgeTracker?: KnowledgeTracker;
 
-  constructor(provider: AIProvider, apiClient: ApiClient, requestState: RequestStore, reporter: Reporter) {
+  constructor(provider: AIProvider, apiClient: ApiClient, requestState: RequestStore, reporter: Reporter, knowledgeTracker?: KnowledgeTracker) {
     this.provider = provider;
     this.apiClient = apiClient;
     this.requestState = requestState;
     this.reporter = reporter;
+    this.knowledgeTracker = knowledgeTracker;
   }
 
   async test(test: Test, opts?: { specDefinition?: string; baseEndpoint?: string; searchSpec?: (query: string) => string }): Promise<{ success: boolean }> {
@@ -37,6 +40,9 @@ export class Curler {
     const conversation = this.provider.startConversation(this.buildSystemPrompt(), 'curler', this.provider.getAgenticModel('curler'));
     const tools = createCurlerTools(this.apiClient, this.requestState, test, opts?.searchSpec);
 
+    const knowledge = test.startUrl && this.knowledgeTracker?.renderEndpointKnowledge(test.startUrl);
+    if (knowledge) conversation.addUserText(knowledge);
+
     const initialPrompt = this.buildTestPrompt(test, opts?.specDefinition, opts?.baseEndpoint);
     conversation.addUserText(initialPrompt);
 

package/boat/api-tester/src/apibot.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { AIProvider } from '../../../src/ai/provider.ts';
 import { RequestStore } from '../../../src/api/request-store.ts';
 import { extractEndpointDefinition, loadSpec, searchEndpoints, validateSpecs } from '../../../src/api/spec-reader.ts';
+import { KnowledgeTracker } from '../../../src/knowledge-tracker.ts';
 import { Reporter } from '../../../src/reporter.ts';
 import { Plan } from '../../../src/test-plan.ts';
 import { setVerboseMode, tag } from '../../../src/utils/logger.ts';
@@ -20,6 +21,7 @@ export class ApiBot {
   private apiClient!: ApiClient;
   private requestState!: RequestStore;
   private reporter!: Reporter;
+  private knowledgeTracker!: KnowledgeTracker;
   private options: ApibotOptions;
   private apiSpec: any;
 
@@ -33,7 +35,7 @@ export class ApiBot {
   }
 
   async start(): Promise<void> {
-    this.config = await this.configParser.loadConfig({ config: this.options.config, path: this.options.path, endpoint: this.options.endpoint });
+    this.config = await this.configParser.loadConfig(this.options);
     this.provider = new AIProvider(this.config.ai);
     await this.provider.validateConnection();
 
@@ -47,6 +49,7 @@ export class ApiBot {
     this.configParser.ensureDirectory(outputDir);
     this.requestState = new RequestStore(outputDir);
     this.reporter = new Reporter(this.config.reporter);
+    this.knowledgeTracker = new KnowledgeTracker({ knowledgeDir: this.configParser.getKnowledgeDir() });
 
     validateSpecs(this.config.api.spec);
     this.apiSpec = await loadSpec(this.config.api.spec!, outputDir);
@@ -84,21 +87,22 @@ export class ApiBot {
     await this.apiClient?.teardown();
   }
 
-  createAgent<T>(factory: (deps: { ai: AIProvider; config: ApibotConfig; apiClient: ApiClient; requestState: RequestStore }) => T): T {
+  createAgent<T>(factory: (deps: { ai: AIProvider; config: ApibotConfig; apiClient: ApiClient; requestState: RequestStore; knowledge: KnowledgeTracker }) => T): T {
     return factory({
       ai: this.provider,
       config: this.config,
       apiClient: this.apiClient,
       requestState: this.requestState,
+      knowledge: this.knowledgeTracker,
     });
   }
 
   agentChief(): Chief {
-    return (this.agents.chief ||= this.createAgent(({ ai, config, apiClient }) => new Chief(ai, config, apiClient)));
+    return (this.agents.chief ||= this.createAgent(({ ai, config, apiClient, knowledge }) => new Chief(ai, config, apiClient, knowledge)));
   }
 
   agentCurler(): Curler {
-    return (this.agents.curler ||= this.createAgent(({ ai, apiClient, requestState }) => new Curler(ai, apiClient, requestState, this.reporter)));
+    return (this.agents.curler ||= this.createAgent(({ ai, apiClient, requestState, knowledge }) => new Curler(ai, apiClient, requestState, this.reporter, knowledge)));
   }
 
   async plan(target: string, opts: { style?: string; fresh?: boolean } = {}): Promise<Plan> {
@@ -200,6 +204,8 @@ interface ApibotOptions {
   config?: string;
   path?: string;
   endpoint?: string;
+  baseEndpoint?: string;
+  spec?: string;
 }
 
 export type { ApibotOptions };

package/boat/api-tester/src/cli.ts

@@ -13,11 +13,19 @@ function buildOptions(options: any): ApibotOptions {
     verbose: options.verbose || options.debug,
     config: options.config,
     path: options.path,
+    baseEndpoint: options.endpoint,
+    spec: options.spec,
   };
 }
 
 function addCommonOptions(cmd: Command): Command {
-  return cmd.option('-v, --verbose', 'Enable verbose logging').option('--debug', 'Enable debug logging').option('-c, --config <path>', 'Path to configuration file').option('-p, --path <path>', 'Working directory path');
+  return cmd
+    .option('-v, --verbose', 'Enable verbose logging')
+    .option('--debug', 'Enable debug logging')
+    .option('-c, --config <path>', 'Path to configuration file')
+    .option('-p, --path <path>', 'Working directory path')
+    .option('--endpoint <url>', 'Base API endpoint to test (env: EXPLORBOT_URL)')
+    .option('--spec <path>', 'OpenAPI spec file or URL (env: EXPLORBOT_API_SPEC)');
 }
 
 function selectTests(tests: any[], index?: string): any[] {
@@ -90,8 +98,10 @@ export function createApiCommands(name = 'api'): Command {
     .action(async (endpoint, options) => {
       const parser = ApibotConfigParser.getInstance();
       const [site] = listSites();
+      const runOptions = buildOptions(options);
+      runOptions.endpoint = endpoint || site?.url;
       try {
-        const config = await parser.loadConfig({ config: options.config, path: options.path, endpoint: endpoint || site?.url });
+        const config = await parser.loadConfig(runOptions);
         console.log(ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json: options.json }));
       } catch (error) {
         console.error(error instanceof Error ? error.message : 'Unknown error');

package/boat/api-tester/src/config.ts

@@ -45,7 +45,7 @@ export class ApibotConfigParser {
     Object.assign(process.env, parseEnv(readFileSync(resolved, 'utf8')));
   }
 
-  async loadConfig(options?: { config?: string; path?: string; endpoint?: string }): Promise<ApibotConfig> {
+  async loadConfig(options?: { config?: string; path?: string; endpoint?: string; baseEndpoint?: string; spec?: string }): Promise<ApibotConfig> {
     if (this.config && !options?.config && !options?.path) return this.config;
 
     const originalCwd = process.cwd();
@@ -55,6 +55,7 @@ export class ApibotConfigParser {
 
     ApibotConfigParser.loadEnv(globalEnvPath());
     ApibotConfigParser.loadEnv('.env');
+    this.applyRunOptions(options);
 
     const resolvedPath = options?.config || this.findConfigFile();
     if (!resolvedPath) {
@@ -82,6 +83,8 @@ export class ApibotConfigParser {
       }
 
       this.config = this.mergeWithDefaults(loadedConfig);
+      this.applyEnvSpec(this.config.api);
+      if (options?.baseEndpoint) this.config.api.baseEndpoint = options.baseEndpoint.replace(/\/$/, '');
       await resolveConfigModels(this.config.ai);
       this.configPath = resolvedPath;
       this.site = null;
@@ -126,6 +129,11 @@ export class ApibotConfigParser {
 
     const resolved = resolveSiteTarget(endpoint, this.site.url);
     if (resolved.baseUrl !== this.site.url) return endpoint;
+
+    const basePath = new URL(this.getConfig().api.baseEndpoint).pathname.replace(/\/$/, '');
+    if (!basePath) return resolved.path;
+    if (resolved.path === basePath) return '/';
+    if (resolved.path.startsWith(`${basePath}/`)) return resolved.path.slice(basePath.length);
     return resolved.path;
   }
 
@@ -148,13 +156,27 @@ export class ApibotConfigParser {
     }
   }
 
+  private applyRunOptions(options?: { baseEndpoint?: string; spec?: string }): void {
+    if (options?.baseEndpoint) process.env.EXPLORBOT_URL = options.baseEndpoint;
+    if (options?.spec) process.env.EXPLORBOT_API_SPEC = options.spec;
+  }
+
+  private applyEnvSpec(api: ApiConfig): void {
+    if (!process.env.EXPLORBOT_API_SPEC) return;
+    api.spec = [process.env.EXPLORBOT_API_SPEC];
+  }
+
   private enterGlobalMode(config: ApibotConfig, endpoint?: string): void {
     const site = resolveSiteTarget(endpoint);
     this.site = registerSite(site.baseUrl);
 
+    let baseEndpoint = site.baseUrl;
+    const envUrl = process.env.EXPLORBOT_URL;
+    if (envUrl && URL.parse(envUrl)?.origin === site.baseUrl) baseEndpoint = envUrl.replace(/\/$/, '');
+
     config.dirs = { output: 'output', knowledge: 'knowledge' };
-    config.api = { ...config.api, baseEndpoint: site.baseUrl };
-    if (process.env.EXPLORBOT_API_SPEC) config.api.spec = [process.env.EXPLORBOT_API_SPEC];
+    config.api = { ...config.api, baseEndpoint };
+    materializeKnowledge(this.site.dir);
   }
 
   private async loadEnvConfig(): Promise<ApibotConfig> {
@@ -169,16 +191,14 @@ export class ApibotConfigParser {
 
     const baseEndpoint = process.env.EXPLORBOT_URL;
     if (!baseEndpoint) {
-      throw new Error('No API endpoint to test. Set EXPLORBOT_URL to the API base endpoint');
+      throw new Error('No API endpoint to test. Pass --endpoint or set EXPLORBOT_URL to the API base endpoint');
     }
 
     const outputRoot = resolveOutputRoot();
     materializeKnowledge(outputRoot);
 
     const api: ApiConfig = { baseEndpoint };
-    if (process.env.EXPLORBOT_API_SPEC) {
-      api.spec = [process.env.EXPLORBOT_API_SPEC];
-    }
+    this.applyEnvSpec(api);
 
     let model: any;
     if (provider && modelSpec) model = await createModel(provider, modelSpec);
@@ -246,7 +266,7 @@ export class ApibotConfigParser {
   }
 
   private mergeWithDefaults(config: Partial<ApibotConfig>): ApibotConfig {
-    return this.deepMerge({ dirs: { output: 'output' } }, config);
+    return this.deepMerge({ dirs: { output: 'output' }, api: {} }, config);
   }
 
   private deepMerge(target: any, source: any): any {

package/boat/doc-collector/bin/doc-collector-cli.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
-import { remote } from '../../../src/remote.ts';
+import { knowledgeOption, wsOption } from '../../../src/commands/options/index.ts';
 import { createDocsCommands } from '../src/cli.ts';
 
 const program = createDocsCommands('doc-collector');
-remote.registerOption(program);
+wsOption.register(program);
+knowledgeOption.register(program);
 program.parse();

package/boat/doc-collector/src/cli.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
 import { ConfigCommand } from '../../../src/commands/config-command.ts';
+import { remote } from '../../../src/remote.ts';
 import { isVerboseMode, setPreserveConsoleLogs, setQuietMode } from '../../../src/utils/logger.ts';
 import { DocBot, type DocbotOptions } from './docbot.ts';
 
@@ -15,6 +16,7 @@ function buildOptions(options: any): DocbotOptions {
     incognito: options.incognito,
     session: options.session,
     docsConfig: options.docsConfig,
+    baseUrl: options.url,
   };
 }
 
@@ -25,6 +27,7 @@ function addCommonOptions(cmd: Command): Command {
     .option('-c, --config <path>', 'Path to explorbot configuration file')
     .option('--docs-config <path>', 'Path to doc collector configuration file')
     .option('-p, --path <path>', 'Working directory path')
+    .option('--url <url>', 'Base URL of the site, when the path argument is relative (env: EXPLORBOT_URL)')
     .option('-s, --show', 'Show browser window')
     .option('--headless', 'Run browser in headless mode')
     .option('--incognito', 'Run without recording experiences')
@@ -59,9 +62,11 @@ export function createDocsCommands(name = 'docs'): Command {
       console.log(`Use in Explorbot: npx explorbot start ${startPath} --spec "${result.outputDir}"`);
 
       await bot.stop();
+      await remote.close(0);
       process.exit(0);
     } catch (error) {
       console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+      await remote.close(1);
       process.exit(1);
     }
   });
@@ -71,7 +76,7 @@ export function createDocsCommands(name = 'docs'): Command {
     .action(async (url, options) => {
       setQuietMode(!isVerboseMode());
       try {
-        console.log(await ConfigCommand.summary({ config: options.config, path: options.path, url, json: options.json }));
+        console.log(await ConfigCommand.summary({ config: options.config, path: options.path, url: url || options.url, json: options.json }));
       } catch (error) {
         console.error(error instanceof Error ? error.message : 'Unknown error');
         process.exit(1);

package/boat/doc-collector/src/docbot.ts

@@ -24,7 +24,7 @@ class DocBot {
 
   constructor(options: DocbotOptions = {}) {
     this.options = options;
-    const baseUrl = this.extractAbsoluteBaseUrl(options.startUrl || '/');
+    const baseUrl = this.extractAbsoluteBaseUrl(options.startUrl || '/') || options.baseUrl;
     this.explorBot = new ExplorBot({
       baseUrl,
       verbose: options.verbose,
@@ -465,7 +465,9 @@ class DocBot {
   private saveIndex(startPath: string, pages: DocumentedPage[], skipped: SkippedPage[], maxPages: number): { indexPath: string; diagramPath: string } {
     const outputDir = this.configParser.getOutputDir();
     const indexPath = path.join(outputDir, 'index.md');
-    writeFileSync(indexPath, renderSpecIndex(outputDir, startPath, pages, skipped, maxPages), 'utf8');
+    const index = renderSpecIndex(outputDir, startPath, pages, skipped, maxPages);
+    writeFileSync(indexPath, index, 'utf8');
+    tag('data').log('docs', { path: indexPath, content: index });
     const diagramPath = path.join(outputDir, 'state-diagram.mmd');
     writeFileSync(diagramPath, renderMermaidBody(outputDir, pages), 'utf8');
     return { indexPath, diagramPath };

package/boat/prima/bin/prima-cli.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env bun
+import { knowledgeOption } from '../../../src/commands/options/index.ts';
 import { createPrimaCommands } from '../src/cli.ts';
 
 const program = createPrimaCommands('prima');
+knowledgeOption.register(program);
 program.parse();

package/boat/prima/src/cli.ts

@@ -31,9 +31,9 @@ const checkHelp = dedent`
               as false.
   Outcomes are settled against a screenshot of the whole page: what a user can see is
   the proof, and the run log only says what was done. CONTRADICTION means the two
-  disagree - reported with both sides rather than settled one way, and ### Artifacts
-  then names the html, aria and screenshot on disk so you can judge it yourself. Not
-  finding something in the picture is not enough on its own; that is "not verified".
+  disagree - reported with both sides rather than settled one way, so read the html,
+  aria and screenshot named under ### Artifacts and judge it yourself. Not finding
+  something in the picture is not enough on its own; that is "not verified".
   ok: follows those outcomes - false when one FAILED or CONTRADICTED, or when the run
   could not complete, which is reported as such rather than as an app failure.
   Page problems seen on the way appear under ### Answer, not as step failures.
@@ -53,6 +53,13 @@ const verifyHelp = dedent`
   could not be expressed, which is not the same as false.
 `;
 
+const statusHelp = dedent`
+  Reads the files a command recorded, so it needs no browser and outlives the session.
+  The hash is looked up across every recorded site. ### Artifacts names every file kept
+  under it: the aria tree, the html, the screenshot and network log when they were
+  captured, and the per-step captures of a do run.
+`;
+
 const reportHelp = dedent`
   Commands are logged as they run, so the report needs no browser and outlives the session.
   The most recent session is reported unless --pw-session names another.
@@ -109,6 +116,7 @@ function addCommonOptions(cmd: Command): Command {
     .option('--ephemeral', 'Keep no state between runs; applies to config-free runs, where output goes to a temp directory')
     .option('--framework <name>', 'Not active yet: framework the reported code targets, codeceptjs or playwright')
     .option('--url <url>', 'Page to open when the session has no page yet')
+    .option('--spec <path>', 'Docbot application spec directory or index.md to read as page knowledge')
     .option('--endpoint <ep>', 'Websocket endpoint of a browser server to attach to, skipping discovery')
     .option('--pw-session <title>', 'Title of the playwright-cli session to attach to')
     .addHelpText('after', `\n${sessionHelp}`);
@@ -119,10 +127,11 @@ function primaFor(options: any): Prima {
   if (options.ephemeral) process.env.EXPLORBOT_EPHEMERAL = '1';
   if (options.model) process.env.EXPLORBOT_AI_MODEL = options.model;
   if (options.visionModel) process.env.EXPLORBOT_VISION_MODEL = options.visionModel;
+  if (options.spec) process.env.EXPLORBOT_SPEC = options.spec;
   return new Prima(buildOptions(options));
 }
 
-async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>, record = true): Promise<void> {
+async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>): Promise<void> {
   setQuietMode(!isVerboseMode());
   trackActivityLine();
   const prima = primaFor(options);
@@ -136,7 +145,7 @@ async function runPrima(options: any, command: string, run: (prima: Prima) => Pr
     envelope = await prima.toolFailureEnvelope(command, error);
   }
 
-  if (record) prima.record(envelope, Date.now() - startedAt);
+  prima.record(envelope, Date.now() - startedAt);
   clearActivityLine();
   console.log(renderEnvelope(envelope));
   await prima.stop().catch(() => {});
@@ -211,9 +220,15 @@ export function createPrimaCommands(name = 'prima'): Command {
       process.exit(0);
     });
 
-  addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command')).action(async (hash, options) => {
-    await runPrima(options, `status ${hash}`, (prima) => prima.status(hash), false);
-  });
+  addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command'))
+    .addHelpText('after', `\n${statusHelp}`)
+    .action(async (hash, options) => {
+      setQuietMode(!isVerboseMode());
+      const prima = primaFor(options);
+      const envelope = await prima.status(hash).catch((error: unknown) => prima.toolFailureEnvelope(`status ${hash}`, error));
+      console.log(renderEnvelope(envelope));
+      process.exit(envelope.ok ? 0 : 1);
+    });
 
   addCommonOptions(cmd.command('report').description('Turn every command of a session into one html and markdown report'))
     .addHelpText('after', `\n${reportHelp}`)