explorbot 0.4.1 → 0.4.3

package/bin/explorbot-cli.ts

@@ -8,6 +8,8 @@ import figureSet from 'figures';
 import { render } from 'ink';
 import React from 'react';
 import { flushTelemetry } from '../src/ai/provider.js';
+import { HelpJsonCommand } from '../src/commands/help-json-command.js';
+import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
 import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
@@ -42,7 +44,9 @@ process.on('unhandledRejection', (reason) => {
   tag('error').log(`Unhandled rejection: ${reason instanceof Error ? `${reason.message}\n${reason.stack}` : String(reason)}`);
 });
 
-if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
+const printsJson = process.argv.includes('--json') || process.argv.includes('help-json');
+
+if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima') && !printsJson) {
   console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 
@@ -336,12 +340,14 @@ addCommonOptions(program.command('test <planfile> [index]').description('Execute
         indexArg = planfile;
       }
 
-      const planTarget = Plan.loadFromFile(planfileArg)?.startUrl;
+      const peeked = Plan.loadFromFile(planfileArg);
 
-      const explorBot = new ExplorBot(buildExplorBotOptions(planTarget, options));
+      const explorBot = new ExplorBot(buildExplorBotOptions(peeked?.startUrl, options));
       await explorBot.start();
 
-      const plan = explorBot.loadPlan(planfileArg);
+      let plan = peeked;
+      if (plan) explorBot.setCurrentPlan(plan);
+      if (!plan) plan = explorBot.loadPlan(planfileArg);
       const pending = plan.getPendingTests();
       log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests, ${pending.length} pending)`);
 
@@ -470,6 +476,8 @@ program
     }
   });
 
+RecommendedModelsCommand.register(program);
+
 program
   .command('init')
   .description('Initialize configuration for a project or for this machine')
@@ -947,6 +955,8 @@ ${rows}
 `;
 };
 
+program.addHelpText('after', `\nFor agents and tools:\n  ${cli} help-json [command...]  the same definitions as JSON — commands, arguments, options, defaults\n`);
 program.addHelpText('after', envHelp);
+HelpJsonCommand.register(program);
 
 program.parse();

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

@@ -66,7 +66,7 @@ export function createCurlerTools(apiClient: ApiClient, requestState: RequestSto
           queryParams: input.queryParams,
         });
 
-        requestState.addRequest(result);
+        requestState.addMadeRequest(result);
 
         if (result.error) {
           tag('error').log(`${input.method} ${input.path} > Network error: ${result.error}`);

package/boat/api-tester/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 { RecommendedModelsCommand } from '../../../src/commands/recommended-models-command.ts';
 import { listSites } from '../../../src/global-config.ts';
 import { setPreserveConsoleLogs } from '../../../src/utils/logger.ts';
 import { getStyles } from './ai/chief/styles.ts';
@@ -109,6 +110,8 @@ export function createApiCommands(name = 'api'): Command {
       }
     });
 
+  RecommendedModelsCommand.register(cmd);
+
   addCommonOptions(cmd.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1-3, *')).action(async (planfile, index, options) => {
     setPreserveConsoleLogs(true);
     try {

package/boat/doc-collector/src/ai/documentarian.ts

@@ -4,7 +4,9 @@ import type { AIProvider } from '../../../../src/ai/provider.ts';
 import type Explorer from '../../../../src/explorer.ts';
 import type { StateManager } from '../../../../src/state-manager.ts';
 import type { WebPageState } from '../../../../src/state-manager.ts';
+import { parseAriaLocator } from '../../../../src/utils/aria.ts';
 import { tag } from '../../../../src/utils/logger.ts';
+import { parseResearchSections } from '../../../../src/ai/researcher/parser.ts';
 import type { DocbotConfig } from '../config.ts';
 import { type CaptureInteractionState, type DocStateTransition, collectDocInteractions } from './tools.ts';
 
@@ -182,6 +184,9 @@ class Documentarian {
       Only list capabilities that are grounded in the provided page research.
       Put actions into "can" only when there is direct evidence in the page context.
       Put actions into "might" only when the UI strongly suggests a capability but proof is incomplete.
+      Going to another page is navigation, not a capability. "can" and "might" list only actions the user performs on this page; links and menus are documented in a separate navigation section, never here.
+      Raw interaction observations that change the URL are navigation evidence only. Never turn them into "can" or "might" actions.
+      Exclude capabilities supplied by unrelated embedded support, marketing, consent, or feedback widgets. Include an embedded interface only when it is part of the current page's documented purpose.
       Describe each action from the end-user perspective.
       Be explicit about scope:
       - one item
@@ -189,7 +194,7 @@ class Documentarian {
       - bulk operations
       - all items
       - page-level
-      Avoid implementation details, selectors, and QA wording.
+      Avoid implementation details, selectors, and QA wording — except the machine-consumed element field, which is a locator, not prose.
       Avoid duplicate actions with different phrasing.
       </rules>
 
@@ -241,6 +246,8 @@ class Documentarian {
       - action: concise user-facing capability phrased as "user can ..."
       - scope: one of one item, list of items, bulk operations, all items, page-level
       - evidence: short reason based on visible UI or research
+      - element: required for every "can" and "might" action. Return the proving or suggesting control's locator copied verbatim from the page research table — the value from the ARIA column, or from the CSS column when the ARIA column is empty. Return null only when no single element supports the action. It is machine metadata used for validation and never shown as prose.
+      Never copy the human-readable Element description from interaction_observations into element. It is not a locator.
       </output_requirements>
     `;
   }
@@ -274,8 +281,30 @@ class Documentarian {
     return message.includes('Failed to generate JSON') || message.includes('Failed to validate JSON') || message.includes('failed_generation') || message.includes('No object generated') || message.includes('response did not match schema');
   }
 
-  private normalizeDocumentation(documentation: GeneratedPageDocumentation & Partial<Pick<PageDocumentation, 'interactions'>>, _state: WebPageState, _research: string): PageDocumentation {
+  private normalizeDocumentation(documentation: GeneratedPageDocumentation & Partial<Pick<PageDocumentation, 'interactions'>>, _state: WebPageState, research: string): PageDocumentation {
     const normalized = { ...documentation };
+    const navigationLocators = new Set<string>();
+    const researchLocators = new Set<string>();
+    for (const section of parseResearchSections(research)) {
+      for (const element of section.elements) {
+        const aria = element.aria ? `{ role: '${element.aria.role}', text: '${element.aria.text}' }` : null;
+        if (aria) researchLocators.add(this.locatorKey(aria));
+        if (element.css) researchLocators.add(this.locatorKey(element.css));
+        if (element.aria?.role !== 'link') continue;
+        if (aria) navigationLocators.add(this.locatorKey(aria));
+        if (element.css) navigationLocators.add(this.locatorKey(element.css));
+      }
+    }
+    normalized.can = normalized.can.filter((capability) => {
+      if (!capability.element) return true;
+      const key = this.locatorKey(capability.element);
+      return researchLocators.has(key) && !navigationLocators.has(key);
+    });
+    normalized.might = normalized.might.filter((capability) => {
+      if (!capability.element) return false;
+      const key = this.locatorKey(capability.element);
+      return researchLocators.has(key) && !navigationLocators.has(key);
+    });
     if (!normalized.interactions) {
       normalized.interactions = undefined;
     }
@@ -288,6 +317,18 @@ class Documentarian {
     });
   }
 
+  private locatorKey(locator: string): string {
+    const aria = parseAriaLocator(locator);
+    if (aria) return `aria:${aria.role}:${aria.text}`;
+    const trimmed = locator.trim();
+    const first = trimmed.at(0);
+    const last = trimmed.at(-1);
+    if (first === last && (first === '`' || first === '"' || first === "'")) {
+      return `css:${trimmed.slice(1, -1).trim()}`;
+    }
+    return `css:${trimmed}`;
+  }
+
   private evaluateDocumentationQuality(documentation: PageDocumentation): string[] {
     const notes: string[] = [];
 
@@ -355,6 +396,14 @@ const capabilitySchema = z.object({
   action: z.string(),
   scope: z.enum(['one item', 'list of items', 'bulk operations', 'all items', 'page-level']),
   evidence: z.string(),
+  element: z.string().nullable().optional(),
+});
+
+const generatedCapabilitySchema = z.object({
+  action: z.string(),
+  scope: z.enum(['one item', 'list of items', 'bulk operations', 'all items', 'page-level']),
+  evidence: z.string(),
+  element: z.string().nullable(),
 });
 
 const stateTransitionSchema = z.object({
@@ -397,11 +446,14 @@ const stateTransitionSchema = z.object({
 
 const generatedPageDocumentationSchema = z.object({
   summary: z.string(),
-  can: z.array(capabilitySchema),
-  might: z.array(capabilitySchema),
+  can: z.array(generatedCapabilitySchema),
+  might: z.array(generatedCapabilitySchema),
 });
 
-const pageDocumentationSchema = generatedPageDocumentationSchema.extend({
+const pageDocumentationSchema = z.object({
+  summary: z.string(),
+  can: z.array(capabilitySchema),
+  might: z.array(capabilitySchema),
   interactions: z.array(stateTransitionSchema).optional(),
   qualityNotes: z.array(z.string()).optional(),
 });

package/boat/doc-collector/src/ai/tools.ts

@@ -225,7 +225,7 @@ function buildTransition(candidate: InteractionCandidate, beforeState: WebPageSt
 function describeTargetState(beforeState: WebPageState, afterState: WebPageState, candidate: InteractionCandidate): InteractionState {
   const beforeFocus = detectFocusArea(beforeState.ariaSnapshot || null);
   const afterFocus = detectFocusArea(afterState.ariaSnapshot || null);
-  if (afterFocus.detected && (!beforeFocus.detected || beforeFocus.name !== afterFocus.name)) {
+  if (afterFocus.type && (!beforeFocus.type || beforeFocus.name !== afterFocus.name)) {
     return {
       kind: afterFocus.type || 'dialog',
       label: afterFocus.name || candidate.element.name.trim(),

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 { RecommendedModelsCommand } from '../../../src/commands/recommended-models-command.ts';
 import { remote } from '../../../src/remote.ts';
 import { isVerboseMode, setPreserveConsoleLogs, setQuietMode } from '../../../src/utils/logger.ts';
 import { DocBot, type DocbotOptions } from './docbot.ts';
@@ -38,7 +39,14 @@ export function createDocsCommands(name = 'docs'): Command {
   const cmd = new Command(name);
   cmd.description('AI-powered website documentation collector');
 
-  addCommonOptions(cmd.command('collect <path>').description('Crawl pages and generate documentation spec').option('--max-pages <count>', 'Maximum number of pages to document')).action(async (startPath, options) => {
+  addCommonOptions(
+    cmd
+      .command('collect <path>')
+      .description('Crawl pages and generate documentation spec')
+      .option('--max-pages <count>', 'Maximum number of pages to document')
+      .option('--no-collapse-template-pages', 'Visit every page even when its layout matches a documented page')
+      .option('--template-similarity <percent>', 'Structural similarity percent that counts pages as the same layout (default 90)')
+  ).action(async (startPath, options) => {
     setPreserveConsoleLogs(true);
 
     try {
@@ -52,8 +60,12 @@ export function createDocsCommands(name = 'docs'): Command {
       if (options.maxPages) {
         maxPages = Number.parseInt(options.maxPages, 10);
       }
+      let templateSimilarity: number | undefined;
+      if (options.templateSimilarity) {
+        templateSimilarity = Number.parseInt(options.templateSimilarity, 10);
+      }
 
-      const result = await bot.collect(startPath, { maxPages });
+      const result = await bot.collect(startPath, { maxPages, collapseTemplatePages: options.collapseTemplatePages, templateSimilarity });
 
       console.log(`\nDocumented ${result.pages.length} page(s)`);
       console.log(`Skipped ${result.skipped.length} page(s)`);
@@ -83,6 +95,8 @@ export function createDocsCommands(name = 'docs'): Command {
       }
     });
 
+  RecommendedModelsCommand.register(cmd);
+
   cmd
     .command('init')
     .description('Initialize doc collector configuration')
@@ -112,6 +126,8 @@ export function createDocsCommands(name = 'docs'): Command {
             interactive: false,
             ignoreErrors: true,
             collapseDynamicPages: true,
+            collapseTemplatePages: true,
+            templateSimilarity: 90,
             scope: 'site',
             includePaths: [],
             excludePaths: [],

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

@@ -119,6 +119,7 @@ class DocbotConfigParser {
           interactive: false,
           ignoreErrors: true,
           collapseDynamicPages: true,
+          collapseTemplatePages: true,
           scope: 'site',
           includePaths: [],
           excludePaths: [],
@@ -157,6 +158,8 @@ interface DocbotConfig {
     ignoreErrors?: boolean | string[];
     prompt?: string;
     collapseDynamicPages?: boolean;
+    collapseTemplatePages?: boolean;
+    templateSimilarity?: number;
     scope?: 'site' | 'section' | 'subtree';
     includePaths?: string[];
     excludePaths?: string[];

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;
@@ -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 {