explorbot 0.2.1 → 0.2.3

package/boat/prima/src/pw-parser.ts

@@ -0,0 +1,17 @@
+const FUNCTION_SHAPE = /^(async\s+)?(function\b|\()/;
+
+export function isFunctionExpression(expr: string): { valid: boolean; error?: string } {
+  const trimmed = expr.trim();
+  if (!trimmed) return { valid: false, error: 'empty expression; pass a function like ({ page }) => ...' };
+  if (!FUNCTION_SHAPE.test(trimmed)) return { valid: false, error: 'expression must be a function like ({ page }) => ... destructuring the playwright objects it needs' };
+  try {
+    new Function(`return (${trimmed})`);
+  } catch (e) {
+    return { valid: false, error: `not a valid function expression: ${(e as Error).message}` };
+  }
+  return { valid: true };
+}
+
+export function toCodeceptWrapper(expr: string): string {
+  return `I.usePlaywrightTo('pw', async (playwright) => (${expr.trim()})(playwright))`;
+}

package/boat/prima/src/pw-registry.ts

@@ -0,0 +1,75 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_TITLE = 'default';
+const DEFAULT_BROWSER = 'chromium';
+
+export function registryDir(): string {
+  if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright', 'b');
+  if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'ms-playwright', 'b');
+  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ms-playwright', 'b');
+}
+
+export function readDescriptors(dir = registryDir()): PwServerDescriptor[] {
+  const descriptors: PwServerDescriptor[] = [];
+  for (const fileName of listFiles(dir)) {
+    const descriptor = parseDescriptor(path.join(dir, fileName));
+    if (descriptor) descriptors.push(descriptor);
+  }
+  return descriptors;
+}
+
+export function selectDescriptor(descriptors: PwServerDescriptor[], opts: { workspaceDir: string; title?: string }): { match?: PwServerDescriptor; candidates: PwServerDescriptor[] } {
+  const workspaceDir = path.resolve(opts.workspaceDir);
+  const candidates = descriptors.filter((descriptor) => path.resolve(descriptor.workspaceDir) === workspaceDir);
+  if (!candidates.length) return { candidates };
+
+  if (opts.title) {
+    const titled = candidates.find((descriptor) => descriptor.title === opts.title);
+    if (titled) return { match: titled, candidates };
+    return { candidates };
+  }
+
+  const preferred = candidates.find((descriptor) => descriptor.title === DEFAULT_TITLE);
+  if (preferred) return { match: preferred, candidates };
+  if (candidates.length === 1) return { match: candidates[0], candidates };
+  return { candidates };
+}
+
+function listFiles(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+function parseDescriptor(file: string): PwServerDescriptor | null {
+  let data: any;
+  try {
+    data = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  if (!data?.endpoint || !data?.title || !data?.workspaceDir) return null;
+
+  return {
+    file,
+    title: data.title,
+    endpoint: data.endpoint,
+    workspaceDir: data.workspaceDir,
+    browserName: data.browser?.browserName || DEFAULT_BROWSER,
+    playwrightLib: data.playwrightLib || '',
+  };
+}
+
+export interface PwServerDescriptor {
+  file: string;
+  title: string;
+  endpoint: string;
+  workspaceDir: string;
+  browserName: string;
+  playwrightLib: string;
+}

package/dist/bin/explorbot-cli.js

@@ -36,6 +36,7 @@ function buildExplorBotOptions(from, options) {
         headless: options.headless,
         incognito: options.incognito,
         session: options.session,
+        applicationSpec: options.spec,
     };
 }
 function addCommonOptions(cmd) {
@@ -47,6 +48,7 @@ function addCommonOptions(cmd) {
         .option('-s, --show', 'Show browser window')
         .option('--headless', 'Run browser in headless mode')
         .option('--incognito', 'Run without recording experiences')
+        .option('--spec <path>', 'Use a Docbot application spec directory or index.md')
         .option('--session [file]', 'Save/restore browser session from file');
 }
 async function startTUI(explorBot) {
@@ -341,6 +343,13 @@ program
         process.exit(1);
     }
 });
+program
+    .command('sites')
+    .description('List sites registered in the global installation')
+    .action(async () => {
+    const { SitesCommand } = await import('../src/commands/sites-command.js');
+    await new SitesCommand(new ExplorBot()).execute('');
+});
 addCommonOptions(program.command('rerun <filename> [index]').description('Re-run generated tests with AI auto-healing')).action(async (filename, index, options) => {
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));
@@ -373,17 +382,29 @@ addCommonOptions(program
 });
 program
     .command('init')
-    .description('Initialize a new project with configuration')
-    .option('-c, --config-path <path>', 'Path for the config file', './explorbot.config.js')
+    .description('Initialize configuration for a project or for this machine')
+    .option('-c, --config-path <path>', 'Path for the config file')
     .option('-f, --force', 'Overwrite existing config file')
     .option('-p, --path <path>', 'Working directory for initialization')
+    .option('-g, --global', 'Configure explorbot in ~/.explorbot to run from anywhere')
+    .option('--provider <name>', `AI provider for the global config: ${Object.keys(PROVIDERS).join(', ')}`)
+    .option('--api-key <key>', 'API key stored in ~/.explorbot/.env')
     .action(async (options) => {
-    const { runInitCommand } = await import('../src/commands/init-command.js');
-    runInitCommand({
-        configPath: options.configPath,
-        force: options.force,
-        path: options.path,
-    });
+    try {
+        const { runInit } = await import('../src/commands/init-command.js');
+        await runInit({
+            configPath: options.configPath,
+            force: options.force,
+            path: options.path,
+            global: options.global,
+            provider: options.provider,
+            apiKey: options.apiKey,
+        });
+    }
+    catch (error) {
+        console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
 });
 program
     .command('clean [target]')
@@ -626,7 +647,7 @@ program
         };
         const explorBot = new ExplorBot(mainOptions);
         await explorBot.start();
-        await explorBot.agentNavigator().visit(url);
+        await explorBot.visit(url);
         const { ContextCommand } = await import('../src/commands/context-command.js');
         const argParts = [];
         if (options.full)
@@ -650,7 +671,7 @@ addCommonOptions(program.command('shell <url> <command>').description('Execute a
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
         await explorBot.start();
-        await explorBot.agentNavigator().visit(url);
+        await explorBot.visit(url);
         const action = explorBot.getExplorer().action();
         await action.execute(command);
         log('Command executed successfully');
@@ -671,10 +692,11 @@ browserCmd
     .description('Launch a persistent browser server')
     .option('-s, --show', 'Launch browser in headed mode (visible window)')
     .option('--headless', 'Launch browser in headless mode')
+    .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .action(async (options) => {
-    const { launchServer, removeEndpointFile } = await import('../src/browser-server.js');
+    const { launchServer, removeEndpointFile, keepServerRunning } = await import('../src/browser-server.js');
     await ConfigParser.getInstance().loadConfig({
         config: options.config,
         path: options.path,
@@ -688,45 +710,34 @@ browserCmd
     const server = await launchServer({
         browser: config.playwright.browser,
         show,
+    }, options.instance);
+    await keepServerRunning(async () => {
+        await server.close();
+        removeEndpointFile(options.instance);
     });
-    console.log('Browser server is running. Press Ctrl+C to stop.');
-    const cleanup = () => {
-        console.log('\nStopping browser server...');
-        server.close();
-        removeEndpointFile();
-        process.exit(0);
-    };
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
 });
 browserCmd
     .command('stop')
     .description('Stop a running browser server')
+    .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .action(async (options) => {
-    const { getAliveEndpoint, removeEndpointFile } = await import('../src/browser-server.js');
+    const { stopServer } = await import('../src/browser-server.js');
     await ConfigParser.getInstance().loadConfig({
         config: options.config,
         path: options.path,
     });
-    const endpoint = await getAliveEndpoint();
-    if (!endpoint) {
+    if (!(await stopServer(options.instance))) {
         console.log('No running browser server found.');
         process.exit(0);
     }
-    try {
-        const { chromium } = await import('playwright-core');
-        const browser = await chromium.connect(endpoint, { timeout: 3000 });
-        await browser.close();
-    }
-    catch { }
-    removeEndpointFile();
     console.log('Browser server stopped.');
 });
 browserCmd
     .command('status')
     .description('Check if a browser server is running')
+    .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .action(async (options) => {
@@ -735,7 +746,7 @@ browserCmd
         config: options.config,
         path: options.path,
     });
-    const endpoint = await getAliveEndpoint();
+    const endpoint = await getAliveEndpoint(options.instance);
     if (endpoint) {
         console.log(`Browser server is running at: ${endpoint}`);
     }
@@ -790,8 +801,10 @@ program
 });
 import { createApiCommands } from "../boat/api-tester/src/cli.js";
 import { createDocsCommands } from "../boat/doc-collector/src/cli.js";
+import { createPrimaCommands } from "../boat/prima/src/cli.js";
 program.addCommand(createApiCommands('api'));
 program.addCommand(createDocsCommands('docs'));
+program.addCommand(createPrimaCommands('prima'));
 const envHelp = () => {
     const width = Math.max(...EXPLORBOT_ENV_VARS.map((v) => v.name.length));
     const rows = EXPLORBOT_ENV_VARS.map((v) => `  ${v.name.padEnd(width)}  ${v.description}`).join('\n');

package/dist/boat/api-tester/src/apibot.js

@@ -30,7 +30,7 @@ export class ApiBot {
         }
     }
     async start() {
-        this.config = await this.configParser.loadConfig({ config: this.options.config, path: this.options.path });
+        this.config = await this.configParser.loadConfig({ config: this.options.config, path: this.options.path, endpoint: this.options.endpoint });
         this.provider = new AIProvider(this.config.ai);
         await this.provider.validateConnection();
         this.apiClient = new ApiClient(this.config.api.baseEndpoint, this.config.api.headers || {}, {
@@ -86,11 +86,12 @@ export class ApiBot {
     agentCurler() {
         return (this.agents.curler ||= this.createAgent(({ ai, apiClient, requestState }) => new Curler(ai, apiClient, requestState, this.reporter)));
     }
-    async plan(endpoint, opts = {}) {
+    async plan(target, opts = {}) {
         if (opts.fresh) {
             this.currentPlan = undefined;
             this.agents.chief = undefined;
         }
+        const endpoint = this.configParser.resolveEndpointPath(target);
         const chief = this.agentChief();
         const specDefinition = this.getEndpointDefinition(endpoint);
         this.currentPlan = await chief.plan(endpoint, { style: opts.style, specDefinition });

package/dist/boat/api-tester/src/cli.js

@@ -40,7 +40,7 @@ export function createApiCommands(name = 'api') {
     addCommonOptions(cmd.command('plan <endpoint>').description('Generate test plan for an API endpoint').option('--style <style>', 'Planning style: basename of a file in rules/chief/styles/').option('--fresh', 'Start planning from scratch')).action(async (endpoint, options) => {
         setPreserveConsoleLogs(true);
         try {
-            const bot = new ApiBot(buildOptions(options));
+            const bot = new ApiBot({ ...buildOptions(options), endpoint });
             await bot.start();
             await bot.plan(endpoint, { style: options.style, fresh: options.fresh });
             const plan = bot.getCurrentPlan();
@@ -104,7 +104,7 @@ export function createApiCommands(name = 'api') {
     addCommonOptions(cmd.command('explore <endpoint>').description('Full cycle: plan all styles, execute tests, re-plan')).action(async (endpoint, options) => {
         setPreserveConsoleLogs(true);
         try {
-            const bot = new ApiBot(buildOptions(options));
+            const bot = new ApiBot({ ...buildOptions(options), endpoint });
             await bot.start();
             const styles = Object.keys(getStyles());
             let totalPassed = 0;

package/dist/boat/api-tester/src/config.js

@@ -9,11 +9,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
 import { parseEnv } from 'node:util';
-import { EXPLORBOT_CONFIG_PATHS, createModel, materializeKnowledge, resolveModel, resolveOutputRoot } from "../../../src/config.js";
+import { ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot } from "../../../src/config.js";
+import { findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from "../../../src/global-config.js";
 export class ApibotConfigParser {
     static instance;
     config = null;
     configPath = null;
+    site = null;
     constructor() { }
     static getInstance() {
         if (!ApibotConfigParser.instance) {
@@ -34,6 +36,7 @@ export class ApibotConfigParser {
         if (options?.path) {
             process.chdir(resolve(options.path));
         }
+        ApibotConfigParser.loadEnv(globalEnvPath());
         ApibotConfigParser.loadEnv('.env');
         const resolvedPath = options?.config || this.findConfigFile();
         if (!resolvedPath) {
@@ -59,7 +62,12 @@ export class ApibotConfigParser {
                 };
             }
             this.config = this.mergeWithDefaults(loadedConfig);
+            await resolveConfigModels(this.config.ai);
             this.configPath = resolvedPath;
+            this.site = null;
+            if (isGlobalConfigPath(resolvedPath)) {
+                this.enterGlobalMode(this.config, options?.endpoint);
+            }
             this.validateConfig(this.config);
             return this.config;
         }
@@ -79,10 +87,23 @@ export class ApibotConfigParser {
     }
     getOutputDir() {
         const config = this.getConfig();
+        return path.join(this.getProjectRoot(), config.dirs?.output || 'output');
+    }
+    getProjectRoot() {
+        if (this.site)
+            return this.site.dir;
         const configPath = this.getConfigPath();
         if (!configPath)
             throw new Error('Config path not found');
-        return path.join(path.dirname(configPath), config.dirs?.output || 'output');
+        return path.dirname(configPath);
+    }
+    resolveEndpointPath(endpoint) {
+        if (!this.site)
+            return endpoint;
+        const resolved = resolveSiteTarget(endpoint, this.site.url);
+        if (resolved.baseUrl !== this.site.url)
+            return endpoint;
+        return resolved.path;
     }
     getPlansDir() {
         return path.join(this.getOutputDir(), 'plans');
@@ -92,21 +113,26 @@ export class ApibotConfigParser {
     }
     getKnowledgeDir() {
         const config = this.getConfig();
-        const configPath = this.getConfigPath();
-        if (!configPath)
-            throw new Error('Config path not found');
-        return path.join(path.dirname(configPath), config.dirs?.knowledge || 'knowledge');
+        return path.join(this.getProjectRoot(), config.dirs?.knowledge || 'knowledge');
     }
     ensureDirectory(dirPath) {
         if (!existsSync(dirPath)) {
             mkdirSync(dirPath, { recursive: true });
         }
     }
+    enterGlobalMode(config, endpoint) {
+        const site = resolveSiteTarget(endpoint);
+        this.site = registerSite(site.baseUrl);
+        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];
+    }
     async loadEnvConfig() {
         const provider = process.env.EXPLORBOT_AI_PROVIDER;
         const modelSpec = process.env.EXPLORBOT_AI_MODEL;
         if (!provider && !modelSpec) {
-            throw new Error('No configuration file found. Create apibot.config.js or set EXPLORBOT_URL and EXPLORBOT_AI_PROVIDER environment variables');
+            throw new ConfigMissingError(missingConfigMessage('apibot.config.js'));
         }
         if (modelSpec && !provider && !modelSpec.includes('/')) {
             throw new Error('EXPLORBOT_AI_MODEL needs a provider — set EXPLORBOT_AI_PROVIDER, or write it as "provider/model-id"');
@@ -149,7 +175,9 @@ export class ApibotConfigParser {
             if (existsSync(fullPath))
                 return fullPath;
         }
-        return null;
+        if (envConfigRequested())
+            return null;
+        return findGlobalConfig();
     }
     async loadConfigModule(configPath) {
         const ext = configPath.split('.').pop();

package/dist/boat/doc-collector/src/ai/documentarian.js

@@ -77,6 +77,9 @@ class Documentarian {
             if ((interaction.changes?.newElements || 0) > 0) {
                 return true;
             }
+            if ((interaction.changes?.removedElements || 0) > 0) {
+                return true;
+            }
             return (interaction.discoveredUrls || []).length > 0;
         });
     }

package/dist/boat/doc-collector/src/ai/tools.js

@@ -58,6 +58,7 @@ async function executeInteraction(explorer, stateManager, candidate, restoreUrl,
     if (!beforeState) {
         return null;
     }
+    const beforeScreenshot = await captureState?.before();
     const executed = await attemptInteraction(explorer, candidate);
     if (!executed) {
         return null;
@@ -75,12 +76,12 @@ async function executeInteraction(explorer, stateManager, candidate, restoreUrl,
         removedElements: ariaChanges.removedCount,
     });
     if (captureState && isMeaningfulStateTransition(transition)) {
-        const screenshot = await captureState(afterState, transition);
+        const screenshot = await captureState.after(beforeScreenshot ?? null, afterState, transition);
         if (screenshot) {
             transition.screenshot = screenshot;
         }
     }
-    if (urlChanged || ariaChanges.newCount > 0) {
+    if (urlChanged || ariaChanges.newCount > 0 || ariaChanges.removedCount > 0) {
         await restoreInteractionState(explorer, restoreUrl);
     }
     return transition;
@@ -108,11 +109,16 @@ async function restoreInteractionState(explorer, restoreUrl, primaryCommand) {
     await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`);
 }
 function buildTransition(candidate, beforeState, afterState, changes) {
+    const existingUrls = new Set(collectLinks(beforeState).map((link) => link.url));
     const transition = {
         action: describeAction(candidate),
         before: summarizeInteractiveState(beforeState),
         after: summarizeInteractiveState(afterState),
-        discoveredUrls: collectLinks(afterState).map((link) => link.url),
+        discoveredUrls: [
+            ...new Set(collectLinks(afterState)
+                .map((link) => link.url)
+                .filter((url) => !existingUrls.has(url))),
+        ],
         newCapabilities: collectDiscoveryNotes(afterState, changes),
         element: buildInteractionElement(candidate),
         changes,
@@ -150,7 +156,7 @@ function isMeaningfulStateTransition(transition) {
     if (transition.targetUrl || transition.changes?.urlChanged) {
         return true;
     }
-    return (transition.changes?.newElements || 0) > 0;
+    return (transition.changes?.newElements || 0) > 0 || (transition.changes?.removedElements || 0) > 0;
 }
 function buildInteractionElement(candidate) {
     const element = {

package/dist/boat/doc-collector/src/cli.js

@@ -47,6 +47,7 @@ export function createDocsCommands(name = 'docs') {
             console.log(`Skipped ${result.skipped.length} page(s)`);
             console.log(`Spec index: ${result.indexPath}`);
             console.log(`Pages dir: ${path.join(result.outputDir, 'pages')}`);
+            console.log(`Use in Explorbot: npx explorbot start ${startPath} --spec "${result.outputDir}"`);
             await bot.stop();
             process.exit(0);
         }
@@ -80,6 +81,7 @@ export function createDocsCommands(name = 'docs') {
             output: 'docs',
             screenshot: true,
             interactive: false,
+            ignoreErrors: true,
             collapseDynamicPages: true,
             scope: 'site',
             includePaths: [],

package/dist/boat/doc-collector/src/config.js

@@ -105,6 +105,7 @@ class DocbotConfigParser {
                 output: 'docs',
                 screenshot: true,
                 interactive: false,
+                ignoreErrors: true,
                 collapseDynamicPages: true,
                 scope: 'site',
                 includePaths: [],

package/dist/boat/doc-collector/src/docbot.js

@@ -9,7 +9,7 @@ import { DocbotConfigParser } from "./config.js";
 import { renderPageDocumentation, renderSpecIndex } from "./docs-renderer.js";
 import { getDocPageKey, shouldCrawlDocPath } from "./path-filter.js";
 import { extractResearchNavigationTargets } from "./research-navigation.js";
-import { captureDocumentationScreenshots, captureInteractionScreenshot } from "./screenshots.js";
+import { captureBeforeInteraction, captureDocumentationScreenshots, captureInteractionScreenshot } from "./screenshots.js";
 import { renderMermaidBody } from "./state-diagram.js";
 class DocBot {
     explorBot;
@@ -98,16 +98,17 @@ class DocBot {
                     force: true,
                 });
                 const pagePath = this.getPageFilePath(state.url);
-                const documentation = await this.documentarian.document(state, research, async (interactionState, transition) => {
-                    if (!this.shouldUseScreenshots()) {
-                        return null;
+                const captureState = this.shouldUseScreenshots()
+                    ? {
+                        before: () => captureBeforeInteraction(this.explorBot.getExplorer()),
+                        after: (beforeScreenshot, interactionState, transition) => captureInteractionScreenshot(this.explorBot.getExplorer(), beforeScreenshot, interactionState, transition, {
+                            pageFilePath: pagePath,
+                            screenshotsDir: this.getScreenshotsDir(),
+                            config: this.config,
+                        }),
                     }
-                    return captureInteractionScreenshot(this.explorBot.getExplorer(), interactionState, transition, {
-                        pageFilePath: pagePath,
-                        screenshotsDir: this.getScreenshotsDir(),
-                        config: this.config,
-                    });
-                });
+                    : undefined;
+                const documentation = await this.documentarian.document(state, research, captureState);
                 const lowSignalReason = this.getLowSignalReason(documentation, research);
                 if (lowSignalReason) {
                     skipped.push({
@@ -147,6 +148,9 @@ class DocBot {
             }
             catch (error) {
                 const reason = error instanceof Error ? error.message : String(error);
+                if (!this.shouldIgnoreError(error)) {
+                    throw error;
+                }
                 tag('warning').log(`Skipping ${target}: ${reason}`);
                 skipped.push({
                     url: target,
@@ -360,6 +364,28 @@ class DocBot {
         }
         return `low-signal page: only ${documentation.can.length} proven actions and ${interactiveCount} interactive elements`;
     }
+    shouldIgnoreError(error) {
+        const ignoreErrors = this.config.docs?.ignoreErrors;
+        if (ignoreErrors === undefined || ignoreErrors === true)
+            return true;
+        if (ignoreErrors === false)
+            return false;
+        const details = [error instanceof Error ? error.name : '', error instanceof Error ? error.message : String(error)];
+        if (typeof error === 'object' && error && 'code' in error) {
+            details.push(String(error.code));
+        }
+        const normalized = details
+            .join(' ')
+            .toLowerCase()
+            .replaceAll(/[\W_]+/g, ' ');
+        return ignoreErrors.some((pattern) => {
+            const normalizedPattern = pattern
+                .trim()
+                .toLowerCase()
+                .replaceAll(/[\W_]+/g, ' ');
+            return normalizedPattern.length > 0 && normalized.includes(normalizedPattern);
+        });
+    }
     countInteractiveElements(research) {
         const matches = [...research.matchAll(/\((\d+) elements?\)/g)];
         return matches.reduce((sum, match) => sum + Number.parseInt(match[1], 10), 0);

package/dist/boat/doc-collector/src/docs-renderer.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
-import { buildStateGraph, renderMermaidFromGraph, renderStateMapFromGraph } from "./state-diagram.js";
+import matter from 'gray-matter';
+import { APPLICATION_SPEC_FORMAT, APPLICATION_SPEC_VERSION } from "../../../src/application-spec-contract.js";
 import { normalizeInlineText } from "../../../src/utils/strings.js";
+import { buildStateGraph, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph } from "./state-diagram.js";
 function renderPageDocumentation(state, documentation, screenshots = []) {
     const lines = [];
     lines.push(`# ${state.url}`);
@@ -25,6 +27,13 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
         }
     }
     const interactions = documentation.interactions;
+    const pageStateDiagram = renderPageStateDiagram(state.title || state.url || 'page', state.url || '', interactions || []);
+    if (pageStateDiagram) {
+        lines.push('## State Map');
+        lines.push('');
+        lines.push(`\`\`\`mermaid\n${pageStateDiagram}\n\`\`\``);
+        lines.push('');
+    }
     if (interactions && interactions.length > 0) {
         lines.push('## State Transitions');
         lines.push('');
@@ -83,7 +92,11 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
         }
         lines.push('');
     }
-    return `${lines.join('\n').trimEnd()}\n`;
+    return matter.stringify(`${lines.join('\n').trimEnd()}\n`, {
+        url: state.url,
+        format: APPLICATION_SPEC_FORMAT,
+        version: APPLICATION_SPEC_VERSION,
+    });
 }
 function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
     const lines = [];
@@ -97,9 +110,10 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
     lines.push(`Max pages: ${maxPages}`);
     lines.push('');
     const graph = buildStateGraph(outputDir, pages);
+    const mermaid = renderMermaidFromGraph(graph, true);
     lines.push('## State Transitions');
     lines.push('');
-    lines.push(`\`\`\`mermaid\n${renderMermaidFromGraph(graph)}\n\`\`\``);
+    lines.push(`\`\`\`mermaid\n${mermaid}\n\`\`\``);
     lines.push('');
     const stateMap = renderStateMapFromGraph(graph);
     if (stateMap) {