explorbot 0.4.0 → 0.4.2

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

@@ -11,8 +11,9 @@ import { type DocbotConfig, DocbotConfigParser } from './config.ts';
 import { type DocumentedPage, type SkippedPage, renderPageDocumentation, renderSpecIndex } from './docs-renderer.ts';
 import { getDocPageKey, shouldCrawlDocPath } from './path-filter.ts';
 import { extractResearchNavigationTargets } from './research-navigation.ts';
-import { type DocumentationScreenshot, captureBeforeInteraction, captureDocumentationScreenshots, captureInteractionScreenshot } from './screenshots.ts';
+import { type DocumentationScreenshot, captureBeforeInteraction, captureDocumentationScreenshots, captureEvidenceScreenshots, captureInteractionScreenshot } from './screenshots.ts';
 import { renderMermaidBody } from './state-diagram.ts';
+import { type TemplateRecord, buildTemplateRecord, findTemplateMatch } from './template-dedup.ts';
 
 class DocBot {
   private explorBot: ExplorBot;
@@ -24,7 +25,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,
@@ -60,6 +61,7 @@ class DocBot {
     const queue: string[] = [];
     const queued = new Set<string>();
     const documented = new Set<string>();
+    const templates: TemplateRecord[] = [];
     const pages: DocumentedPage[] = [];
     const skipped: SkippedPage[] = [];
     const baseUrl = this.explorBot.getConfig().playwright.url;
@@ -86,15 +88,6 @@ class DocBot {
         tag('info').log(`Collecting docs for ${this.toDisplayUrl(target, baseUrl)}`);
         await this.explorBot.visit(target);
 
-        if (stateManager.isInDeadLoop()) {
-          tag('warning').log('Dead loop detected during docs crawl, stopping collection');
-          skipped.push({
-            url: target,
-            reason: 'dead loop detected during crawl',
-          });
-          break;
-        }
-
         const state = this.explorBot.getCurrentState();
         if (!state) {
           skipped.push({
@@ -109,6 +102,22 @@ class DocBot {
           continue;
         }
 
+        if (this.shouldCollapseTemplates(opts.collapseTemplatePages)) {
+          const templateUrl = findTemplateMatch(state.ariaSnapshot ?? null, templates, this.getTemplateSimilarity(opts.templateSimilarity));
+          if (templateUrl) {
+            skipped.push({
+              url: state.url,
+              reason: `same layout as ${templateUrl} (only content differs)`,
+            });
+            documented.add(pageKey);
+            for (const nextPath of this.extractNextPaths(state, baseUrl, '')) {
+              if (documented.has(this.getPageKey(nextPath)) || stateManager.hasVisitedState(nextPath)) continue;
+              this.enqueuePath(nextPath, queue, queued);
+            }
+            continue;
+          }
+        }
+
         const research = await this.explorBot.agentResearcher().research(state, {
           screenshot: this.shouldUseScreenshots(),
           force: true,
@@ -153,6 +162,9 @@ class DocBot {
         });
         documented.add(pageKey);
 
+        const templateRecord = buildTemplateRecord(state.url, state.ariaSnapshot ?? null);
+        if (templateRecord) templates.push(templateRecord);
+
         const nextPaths = this.extractNextPaths(state, baseUrl, research, documentation);
         const interactionPriorityPaths = new Set(this.extractInteractionPaths(baseUrl, documentation));
         for (const nextPath of nextPaths) {
@@ -209,6 +221,23 @@ class DocBot {
     return true;
   }
 
+  private shouldCollapseTemplates(override?: boolean): boolean {
+    if (override === false) {
+      return false;
+    }
+    if (this.config.docs?.collapseTemplatePages === false) {
+      return false;
+    }
+    return true;
+  }
+
+  private getTemplateSimilarity(override?: number): number | undefined {
+    const value = override ?? this.config.docs?.templateSimilarity;
+    if (value == null) return undefined;
+    if (!Number.isFinite(value) || value <= 0 || value > 100) return undefined;
+    return value;
+  }
+
   private extractNextPaths(state: WebPageState, baseUrl: string, research: string, documentation?: PageDocumentation): string[] {
     const paths: string[] = [];
     const seen = new Set<string>();
@@ -446,7 +475,8 @@ class DocBot {
   private async savePageDocumentation(state: WebPageState, documentation: PageDocumentation, research: string): Promise<string> {
     const pagePath = this.getPageFilePath(state.url);
     const screenshots = await this.captureScreenshots(state, research, pagePath);
-    writeFileSync(pagePath, renderPageDocumentation(state, documentation, screenshots), 'utf8');
+    const evidence = await this.captureEvidence(state, documentation, research, pagePath);
+    writeFileSync(pagePath, renderPageDocumentation(state, documentation, screenshots, evidence), 'utf8');
     return pagePath;
   }
 
@@ -462,6 +492,19 @@ class DocBot {
     });
   }
 
+  private async captureEvidence(state: WebPageState, documentation: PageDocumentation, research: string, pagePath: string): Promise<Array<DocumentationScreenshot | null>> {
+    if (!this.shouldUseScreenshots()) {
+      return documentation.can.map(() => null);
+    }
+
+    return captureEvidenceScreenshots(this.explorBot.getExplorer(), state, documentation, {
+      pageFilePath: pagePath,
+      screenshotsDir: this.getScreenshotsDir(),
+      config: this.config,
+      research,
+    });
+  }
+
   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');
@@ -505,6 +548,8 @@ interface DocbotOptions extends ExplorBotOptions {
 
 interface CollectOptions {
   maxPages?: number;
+  collapseTemplatePages?: boolean;
+  templateSimilarity?: number;
 }
 
 interface CollectionResult {

package/boat/doc-collector/src/docs-renderer.ts

@@ -7,7 +7,7 @@ import type { PageDocumentation, StateTransition } from './ai/documentarian.ts';
 import type { DocumentationScreenshot } from './screenshots.ts';
 import { type DocumentedPage, type SkippedPage, buildStateGraph, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph } from './state-diagram.ts';
 
-function renderPageDocumentation(state: WebPageState, documentation: PageDocumentation, screenshots: DocumentationScreenshot[] = []): string {
+function renderPageDocumentation(state: WebPageState, documentation: PageDocumentation, screenshots: DocumentationScreenshot[] = [], evidence: Array<DocumentationScreenshot | null> = []): string {
   const lines: string[] = [];
   lines.push(`# ${state.url}`);
   lines.push('');
@@ -22,6 +22,42 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
   lines.push(ensureSentence(documentation.summary));
   lines.push('');
 
+  lines.push('## User Can');
+  lines.push('');
+
+  if (documentation.can.length === 0) {
+    lines.push('- No proven actions were identified from the collected research.');
+    lines.push('');
+  }
+
+  for (const [index, item] of documentation.can.entries()) {
+    lines.push(`- ${normalizeAction(item.action)} -> ${item.scope}`);
+    lines.push(`  Proof: ${ensureSentence(item.evidence)}`);
+    const shot = evidence[index];
+    if (shot) {
+      lines.push('');
+      lines.push(`  ![${normalizeInlineText(item.action)}](${shot.relativePath})`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## User Might');
+  lines.push('');
+
+  if (documentation.might.length === 0) {
+    lines.push('- No assumption-based actions were identified.');
+    lines.push('');
+  }
+
+  for (const item of documentation.might) {
+    lines.push(`- ${normalizeAction(item.action, 'might')} -> ${item.scope}`);
+    lines.push(`  Signal: ${ensureSentence(item.evidence)}`);
+  }
+
+  if (documentation.might.length > 0) {
+    lines.push('');
+  }
+
   if (screenshots.length > 0) {
     lines.push('## Screenshots');
     lines.push('');
@@ -34,6 +70,26 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
     }
   }
 
+  const navigationLinks = renderNavigationLinks(state);
+  if (navigationLinks.length > 0) {
+    lines.push('## Navigation');
+    lines.push('');
+    for (const link of navigationLinks) {
+      lines.push(`- ${link.title}: ${link.url}`);
+    }
+    lines.push('');
+  }
+
+  const qualityNotes = documentation.qualityNotes;
+  if (qualityNotes && qualityNotes.length > 0) {
+    lines.push('## Coverage Notes');
+    lines.push('');
+    for (const note of qualityNotes) {
+      lines.push(`- ${ensureSentence(note)}`);
+    }
+    lines.push('');
+  }
+
   const interactions = documentation.interactions;
   const pageStateDiagram = renderPageStateDiagram(state.title || state.url || 'page', state.url || '', interactions || []);
   if (pageStateDiagram) {
@@ -66,50 +122,6 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
     }
   }
 
-  lines.push('## User Can');
-  lines.push('');
-
-  if (documentation.can.length === 0) {
-    lines.push('- No proven actions were identified from the collected research.');
-    lines.push('');
-  }
-
-  for (const item of documentation.can) {
-    lines.push(`- ${normalizeAction(item.action)} -> ${item.scope}`);
-    lines.push(`  Proof: ${ensureSentence(item.evidence)}`);
-  }
-
-  if (documentation.can.length > 0) {
-    lines.push('');
-  }
-
-  lines.push('## User Might');
-  lines.push('');
-
-  if (documentation.might.length === 0) {
-    lines.push('- No assumption-based actions were identified.');
-    lines.push('');
-  }
-
-  for (const item of documentation.might) {
-    lines.push(`- ${normalizeAction(item.action, 'might')} -> ${item.scope}`);
-    lines.push(`  Signal: ${ensureSentence(item.evidence)}`);
-  }
-
-  if (documentation.might.length > 0) {
-    lines.push('');
-  }
-
-  const qualityNotes = documentation.qualityNotes;
-  if (qualityNotes && qualityNotes.length > 0) {
-    lines.push('## Coverage Notes');
-    lines.push('');
-    for (const note of qualityNotes) {
-      lines.push(`- ${ensureSentence(note)}`);
-    }
-    lines.push('');
-  }
-
   return matter.stringify(`${lines.join('\n').trimEnd()}\n`, {
     url: state.url,
     format: APPLICATION_SPEC_FORMAT,
@@ -130,17 +142,7 @@ function renderSpecIndex(outputDir: string, startPath: string, pages: Documented
   lines.push('');
   const graph = buildStateGraph(outputDir, pages);
   const mermaid = renderMermaidFromGraph(graph, true);
-  lines.push('## State Transitions');
-  lines.push('');
-  lines.push(`\`\`\`mermaid\n${mermaid}\n\`\`\``);
-  lines.push('');
   const stateMap = renderStateMapFromGraph(graph);
-  if (stateMap) {
-    lines.push('### State Index');
-    lines.push('');
-    lines.push(stateMap);
-    lines.push('');
-  }
   lines.push('## Pages');
   lines.push('');
 
@@ -208,9 +210,31 @@ function renderSpecIndex(outputDir: string, startPath: string, pages: Documented
     lines.push('');
   }
 
+  lines.push('## State Transitions');
+  lines.push('');
+  lines.push(`\`\`\`mermaid\n${mermaid}\n\`\`\``);
+  lines.push('');
+  if (stateMap) {
+    lines.push('### State Index');
+    lines.push('');
+    lines.push(stateMap);
+    lines.push('');
+  }
+
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
+function renderNavigationLinks(state: WebPageState): Array<{ title: string; url: string }> {
+  const links: Array<{ title: string; url: string }> = [];
+  const seen = new Set<string>();
+  for (const link of state.links || []) {
+    if (!link.url || seen.has(link.url)) continue;
+    seen.add(link.url);
+    links.push({ title: normalizeInlineText(link.title) || link.url, url: link.url });
+  }
+  return links;
+}
+
 function normalizeAction(action: string, kind: 'can' | 'might' = 'can'): string {
   const trimmed = normalizeInlineText(action);
   if (!trimmed) {

package/boat/doc-collector/src/interaction-screenshots.ts

@@ -2,6 +2,7 @@ import { writeFileSync } from 'node:fs';
 import pixelmatch from 'pixelmatch';
 import type { Page } from 'playwright';
 import { PNG } from 'pngjs';
+import { removeVisualAnnotations } from '../../../src/ai/researcher/coordinates.ts';
 
 const REGION_PADDING = 30;
 const SCREENSHOT_OPTIONS = { animations: 'disabled', caret: 'hide' } as const;
@@ -44,7 +45,7 @@ export function findChangedRegion(beforeScreenshot: Buffer, afterScreenshot: Buf
   return changedPixels ? addPadding(changedPixels, before.width, before.height, padding) : null;
 }
 
-function saveRegion(after: PNG, region: ScreenshotRegion, filePath: string): void {
+export function saveRegion(after: PNG, region: ScreenshotRegion, filePath: string): void {
   const cropped = new PNG({ width: region.width, height: region.height });
   PNG.bitblt(after, cropped, region.x, region.y, region.width, region.height, 0, 0);
   writeFileSync(filePath, PNG.sync.write(cropped));
@@ -73,7 +74,23 @@ function findChangedPixelBounds(before: PNG, after: PNG): ScreenshotRegion | nul
   return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
 }
 
-function addPadding(region: ScreenshotRegion, imageWidth: number, imageHeight: number, padding = REGION_PADDING): ScreenshotRegion {
+export function regionAround(png: PNG, box: { x: number; y: number; width: number; height: number }, viewport: { width: number; height: number } | null, padding: number): ScreenshotRegion {
+  let scaleX = 1;
+  let scaleY = 1;
+  if (viewport) {
+    scaleX = png.width / viewport.width;
+    scaleY = png.height / viewport.height;
+  }
+  const scaled: ScreenshotRegion = {
+    x: Math.round(box.x * scaleX),
+    y: Math.round(box.y * scaleY),
+    width: Math.round(box.width * scaleX),
+    height: Math.round(box.height * scaleY),
+  };
+  return addPadding(scaled, png.width, png.height, Math.round(padding * scaleX));
+}
+
+export function addPadding(region: ScreenshotRegion, imageWidth: number, imageHeight: number, padding = REGION_PADDING): ScreenshotRegion {
   const x = Math.max(0, region.x - padding);
   const y = Math.max(0, region.y - padding);
   const maxX = Math.min(imageWidth, region.x + region.width + padding);
@@ -81,14 +98,6 @@ function addPadding(region: ScreenshotRegion, imageWidth: number, imageHeight: n
   return { x, y, width: maxX - x, height: maxY - y };
 }
 
-async function removeVisualAnnotations(page: Page): Promise<void> {
-  try {
-    await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
-      for (const element of elements) element.remove();
-    });
-  } catch {}
-}
-
 async function findOverlayRegion(page: Page, image: PNG, detectUnmarkedOverlay: boolean): Promise<ScreenshotRegion | null> {
   let box: { x: number; y: number; width: number; height: number } | null = null;
   try {

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

@@ -1,14 +1,19 @@
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { PNG } from 'pngjs';
+import { removeVisualAnnotations } from '../../../src/ai/researcher/coordinates.ts';
 import { parseResearchSections } from '../../../src/ai/researcher/parser.ts';
+import { parseAriaLocator } from '../../../src/utils/aria.ts';
 import type Explorer from '../../../src/explorer.ts';
-import type { WebPageState } from '../../../src/state-manager.ts';
+import { type WebPageState, normalizeUrl } from '../../../src/state-manager.ts';
 import { safeFilename, sanitizeFilename } from '../../../src/utils/strings.ts';
+import type { PageDocumentation } from './ai/documentarian.ts';
 import type { DocStateTransition } from './ai/tools.ts';
 import type { DocbotConfig } from './config.ts';
-import { captureInteractionAfter, captureInteractionBefore } from './interaction-screenshots.ts';
+import { addPadding, captureInteractionAfter, captureInteractionBefore, regionAround, saveRegion } from './interaction-screenshots.ts';
 
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
+const EVIDENCE_PADDING = 250;
 
 export async function captureDocumentationScreenshots(explorer: Explorer, state: WebPageState, research: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot[]> {
   const page = explorer.page;
@@ -16,6 +21,8 @@ export async function captureDocumentationScreenshots(explorer: Explorer, state:
     return [];
   }
 
+  await dismissTransientOverlay(page);
+  await removeVisualAnnotations(page);
   mkdirSync(options.screenshotsDir, { recursive: true });
 
   const screenshots: DocumentationScreenshot[] = [];
@@ -37,6 +44,101 @@ export async function captureDocumentationScreenshots(explorer: Explorer, state:
   return screenshots;
 }
 
+export async function captureEvidenceScreenshots(explorer: Explorer, state: WebPageState, documentation: PageDocumentation, options: DocumentationScreenshotOptions): Promise<Array<DocumentationScreenshot | null>> {
+  const page = explorer.page;
+  if (!page) {
+    return documentation.can.map(() => null);
+  }
+
+  await dismissTransientOverlay(page);
+  await removeVisualAnnotations(page);
+  if (!isOnDocumentedPage(page, state)) {
+    return documentation.can.map(() => null);
+  }
+  mkdirSync(options.screenshotsDir, { recursive: true });
+  const pageName = sanitizeFilename(state.url || 'page') || 'page';
+  const shots: Array<DocumentationScreenshot | null> = [];
+  for (const [index, item] of documentation.can.entries()) {
+    shots.push(await captureEvidenceScreenshot(page, pageName, index, item, options));
+  }
+  return shots;
+}
+
+async function captureEvidenceScreenshot(page: any, pageName: string, index: number, item: { action: string; element?: string | null }, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
+  if (!item.element) return null;
+  const element = resolveResearchLocator(item.element, options.research);
+  if (!element) return null;
+  const locatorInfo = parseAriaLocator(element);
+  try {
+    const locator = resolveEvidenceLocator(page, element, locatorInfo);
+    if ((await locator.count()) !== 1) return null;
+    await locator.scrollIntoViewIfNeeded({ timeout: 2000 });
+    const box = await locator.boundingBox();
+    if (!box || box.width <= 0 || box.height <= 0) return null;
+    const image = await page.screenshot();
+    const png = PNG.sync.read(image);
+    const region = regionAround(png, box, await page.viewportSize(), EVIDENCE_PADDING);
+    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_can_${index + 1}`, '.png'));
+    saveRegion(png, region, filePath);
+    return {
+      title: item.action,
+      path: filePath,
+      relativePath: toMarkdownPath(options.pageFilePath, filePath),
+      kind: 'evidence',
+    };
+  } catch {
+    return null;
+  }
+}
+
+function resolveResearchLocator(requested: string, research?: string): string | null {
+  if (!research) return requested;
+  const requestedAria = parseAriaLocator(requested);
+  const requestedCss = unwrapLocator(requested);
+  for (const section of parseResearchSections(research)) {
+    for (const element of section.elements) {
+      if (requestedAria && element.aria?.role === requestedAria.role && element.aria.text === requestedAria.text) {
+        return `{ role: '${element.aria.role}', text: '${element.aria.text}' }`;
+      }
+      if (element.css && requestedCss === unwrapLocator(element.css)) return element.css;
+    }
+  }
+  return null;
+}
+
+function unwrapLocator(locator: string): string {
+  const trimmed = locator.trim();
+  const first = trimmed.at(0);
+  const last = trimmed.at(-1);
+  if (first === last && (first === '`' || first === '"' || first === "'")) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function isOnDocumentedPage(page: any, state: WebPageState): boolean {
+  try {
+    const current = new URL(page.url());
+    const expected = new URL(state.url || '', current.origin);
+    return current.origin === expected.origin && normalizeUrl(current.href) === normalizeUrl(expected.href);
+  } catch {
+    return false;
+  }
+}
+
+function resolveEvidenceLocator(page: any, element: string, locatorInfo: { role: string; text: string } | null): any {
+  if (locatorInfo?.text) {
+    return page.getByRole(locatorInfo.role, { name: locatorInfo.text, exact: true });
+  }
+  return page.locator(element);
+}
+
+async function dismissTransientOverlay(page: any): Promise<void> {
+  try {
+    await page.keyboard.press('Escape');
+  } catch {}
+}
+
 export function getScreenshotSections(research: string): ScreenshotSection[] {
   const sections: ScreenshotSection[] = [];
   const seen = new Set<string>();
@@ -150,7 +252,7 @@ export interface DocumentationScreenshot {
   title: string;
   path: string;
   relativePath: string;
-  kind: 'page' | 'section' | 'state';
+  kind: 'page' | 'section' | 'state' | 'evidence';
   selector?: string;
 }
 
@@ -158,6 +260,7 @@ interface DocumentationScreenshotOptions {
   pageFilePath: string;
   screenshotsDir: string;
   config: DocbotConfig;
+  research?: string;
 }
 
 interface ScreenshotSection {

package/boat/doc-collector/src/template-dedup.ts

@@ -0,0 +1,31 @@
+import { ariaTemplateSignature } from '../../../src/utils/aria.ts';
+import { diceSimilarity } from '../../../src/utils/similarity.ts';
+
+const TEMPLATE_MIN_SIGNATURE_SIZE = 8;
+const TEMPLATE_SIMILARITY_THRESHOLD = 90;
+
+export function buildTemplateRecord(url: string, snapshot: string | null): TemplateRecord | null {
+  const signature = ariaTemplateSignature(snapshot);
+  if (signature.size < TEMPLATE_MIN_SIGNATURE_SIZE) return null;
+  return { url, signature };
+}
+
+export function findTemplateMatch(snapshot: string | null, known: TemplateRecord[], threshold: number = TEMPLATE_SIMILARITY_THRESHOLD): string | null {
+  const signature = ariaTemplateSignature(snapshot);
+  if (signature.size < TEMPLATE_MIN_SIGNATURE_SIZE) return null;
+  let bestUrl: string | null = null;
+  let bestScore = 0;
+  for (const record of known) {
+    const score = diceSimilarity(signature, record.signature);
+    if (score < bestScore) continue;
+    bestScore = score;
+    bestUrl = record.url;
+  }
+  if (bestScore < threshold) return null;
+  return bestUrl;
+}
+
+export interface TemplateRecord {
+  url: string;
+  signature: Set<string>;
+}

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

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import dedent from 'dedent';
 import { keepServerRunning } from '../../../src/browser-server.ts';
+import { RecommendedModelsCommand } from '../../../src/commands/recommended-models-command.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { isVerboseMode, setQuietMode } from '../../../src/utils/logger.ts';
 import { clearActivityLine, trackActivityLine } from './activity-line.ts';
@@ -116,6 +117,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}`);
@@ -126,6 +128,7 @@ 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));
 }
 
@@ -218,6 +221,8 @@ export function createPrimaCommands(name = 'prima'): Command {
       process.exit(0);
     });
 
+  RecommendedModelsCommand.register(cmd);
+
   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) => {

package/boat/prima/src/prima.ts

@@ -15,7 +15,7 @@ import { getAliveEndpoint, launchServer, listInstances, stopServer } from '../..
 import { ConfigCommand } from '../../../src/commands/config-command.ts';
 import { ConfigMissingError, ConfigParser, EXPLORBOT_ENV_VARS, type ExplorbotConfig, outputPath } from '../../../src/config.ts';
 import { ExplorBot } from '../../../src/explorbot.ts';
-import { listSites } from '../../../src/global-config.ts';
+import { findSiteWith, listSites } from '../../../src/global-config.ts';
 import { Reporter } from '../../../src/reporter.ts';
 import type { WebPageState } from '../../../src/state-manager.ts';
 import { Stats } from '../../../src/stats.ts';
@@ -1067,8 +1067,7 @@ export class Prima {
 
   async status(hash: string): Promise<EnvelopeData> {
     if (!this.artifactsDir) {
-      const sites = listSites();
-      const site = sites.find((candidate) => existsSync(path.join(candidate.dir, 'output', 'prima', hash))) || sites[0];
+      const site = findSiteWith(path.join('output', 'prima', hash)) || listSites()[0];
       if (site && !this.configBaseUrl()) this.sessionUrl = site.url;
       await this.loadConfig();
     }
@@ -1113,7 +1112,7 @@ export class Prima {
       aria: result.ariaSnapshot,
       html: await result.combinedHtml(),
       screenshot: result.screenshot,
-      requests: this.bot.requestStore().getRequests(),
+      requests: this.bot.requestStore().getMadeRequests(),
     });
   }