explorbot 0.2.1 → 0.2.3

package/dist/src/global-config.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import { join } from 'node:path';
+const GLOBAL_CONFIG_NAMES = ['config.js', 'config.mjs', 'config.ts'];
+const SITE_DIRS = ['knowledge', 'experience', 'output'];
+export function globalDir() {
+    return join(os.homedir(), '.explorbot');
+}
+export function globalEnvPath() {
+    return join(globalDir(), '.env');
+}
+export function globalConfigPath() {
+    return join(globalDir(), 'config.js');
+}
+export function findGlobalConfig() {
+    for (const name of GLOBAL_CONFIG_NAMES) {
+        const fullPath = join(globalDir(), name);
+        if (existsSync(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+export function isGlobalConfigPath(configPath) {
+    return GLOBAL_CONFIG_NAMES.some((name) => join(globalDir(), name) === configPath);
+}
+export function sitesDir() {
+    return join(globalDir(), 'sites');
+}
+export function siteFolderName(url) {
+    return new URL(url).host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+}
+export function listSites() {
+    if (!existsSync(sitesDir()))
+        return [];
+    return readdirSync(sitesDir(), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => readSite(entry.name))
+        .filter((site) => !!site)
+        .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
+}
+export function registerSite(baseUrl) {
+    const folder = siteFolderName(baseUrl);
+    const dir = join(sitesDir(), folder);
+    for (const subDir of SITE_DIRS) {
+        mkdirSync(join(dir, subDir), { recursive: true, mode: 0o700 });
+    }
+    const now = new Date().toISOString();
+    const meta = {
+        url: baseUrl,
+        createdAt: readSite(folder)?.createdAt || now,
+        lastRunAt: now,
+    };
+    writeFileSync(join(dir, 'site.json'), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+    return { folder, dir, ...meta };
+}
+export function resolveSiteTarget(target, defaultBaseUrl) {
+    const raw = (target || process.env.EXPLORBOT_URL || defaultBaseUrl || '').trim();
+    if (!raw) {
+        throw new Error(withSites('No site to explore. Pass a URL to the command or set EXPLORBOT_URL.'));
+    }
+    if (raw.startsWith('http://') || raw.startsWith('https://')) {
+        const url = new URL(raw);
+        return { baseUrl: url.origin, path: `${url.pathname}${url.search}${url.hash}` };
+    }
+    if (raw.startsWith('/')) {
+        const base = defaultBaseUrl || process.env.EXPLORBOT_URL;
+        if (!base) {
+            throw new Error(withSites(`Cannot resolve path "${raw}" without a site.`));
+        }
+        return { baseUrl: new URL(base).origin, path: raw };
+    }
+    let reference = raw;
+    let path = '/';
+    const separator = raw.indexOf('/');
+    if (separator > -1) {
+        reference = raw.slice(0, separator);
+        path = raw.slice(separator);
+    }
+    const site = findSite(reference);
+    if (!site) {
+        throw new Error(withSites(`Unknown site "${reference}".`));
+    }
+    return { baseUrl: site.url, path };
+}
+function readSite(folder) {
+    const dir = join(sitesDir(), folder);
+    const metaPath = join(dir, 'site.json');
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+        new URL(meta.url);
+        return { folder, dir, url: meta.url, createdAt: meta.createdAt, lastRunAt: meta.lastRunAt };
+    }
+    catch {
+        return null;
+    }
+}
+function findSite(reference) {
+    const normalized = reference.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+    const sites = listSites();
+    const byFolder = sites.find((site) => site.folder === normalized);
+    if (byFolder)
+        return byFolder;
+    return sites.find((site) => new URL(site.url).host.toLowerCase() === reference.toLowerCase()) || null;
+}
+function withSites(message) {
+    const lines = [message];
+    const sites = listSites();
+    if (sites.length) {
+        lines.push('Registered sites:');
+        for (const site of sites)
+            lines.push(`  ${site.folder} → ${site.url}`);
+    }
+    lines.push('Explore a new site by passing its full URL, e.g. https://app.example.com/login');
+    return lines.join('\n');
+}

package/dist/src/knowledge-tracker.d.ts

@@ -1,4 +1,5 @@
 import { ActionResult } from './action-result.js';
+import { ApplicationSpec } from './application-spec.js';
 export interface Knowledge {
     filePath: string;
     url: string;
@@ -9,10 +10,13 @@ export declare class KnowledgeTracker {
     knowledgeDir: string;
     knowledgeFiles: Knowledge[];
     isLoaded: boolean;
-    constructor();
+    applicationSpec?: ApplicationSpec;
+    constructor(applicationSpecPath?: string);
     loadKnowledgeFiles(): void;
     getRelevantKnowledge(state: ActionResult): Knowledge[];
     renderRelevantKnowledge(state: ActionResult): string;
+    renderRelevantContext(state: ActionResult): string;
+    renderApplicationSpec(state: ActionResult): string;
     addKnowledge(urlPattern: string, description: string): {
         filename: string;
         filePath: string;

package/dist/src/knowledge-tracker.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import dedent from 'dedent';
 import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
+import { ApplicationSpec } from "./application-spec.js";
 import { ConfigParser } from './config.js';
 import { getCliName } from "./utils/cli-name.js";
 import { createDebug, pluralize, tag } from './utils/logger.js';
@@ -15,13 +16,19 @@ export class KnowledgeTracker {
     knowledgeDir;
     knowledgeFiles = [];
     isLoaded = false;
-    constructor() {
+    applicationSpec;
+    constructor(applicationSpecPath) {
         const configParser = ConfigParser.getInstance();
         const config = configParser.getConfig();
         this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
         if (!existsSync(this.knowledgeDir)) {
             mkdirSync(this.knowledgeDir, { recursive: true });
         }
+        const specPath = applicationSpecPath || config.dirs?.spec;
+        if (specPath) {
+            this.applicationSpec = new ApplicationSpec(specPath);
+            tag('info').log(`Loaded application spec with ${this.applicationSpec.pageCount} documented pages`);
+        }
     }
     loadKnowledgeFiles() {
         if (this.isLoaded)
@@ -60,6 +67,12 @@ export class KnowledgeTracker {
       </knowledge>
     `;
     }
+    renderRelevantContext(state) {
+        return [this.renderRelevantKnowledge(state), this.renderApplicationSpec(state)].filter(Boolean).join('\n\n');
+    }
+    renderApplicationSpec(state) {
+        return this.applicationSpec?.renderFor(state) || '';
+    }
     addKnowledge(urlPattern, description) {
         const configParser = ConfigParser.getInstance();
         const configPath = configParser.getConfigPath();

package/dist/src/utils/cli-name.js

@@ -8,8 +8,12 @@ export function getCliName() {
         cached = 'bunx explorbot';
     else if (ua.includes('npm'))
         cached = 'npx explorbot';
-    else if (process.argv[1]?.endsWith('.ts'))
-        cached = `bun ${path.relative(process.cwd(), process.argv[1])}`;
+    else if (process.argv[1]?.endsWith('.ts')) {
+        let script = path.relative(process.cwd(), process.argv[1]);
+        if (script.startsWith('..'))
+            script = process.argv[1];
+        cached = `bun ${script}`;
+    }
     else
         cached = 'explorbot';
     return cached;

package/dist/src/utils/test-files.js

@@ -57,8 +57,7 @@ export async function dryRunTestFile(filePath) {
         return;
     }
     const config = ConfigParser.getInstance().getConfig();
-    const configPath = ConfigParser.getInstance().getConfigPath();
-    const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
+    const projectRoot = ConfigParser.getInstance().getProjectRoot();
     const codeceptConfig = {
         helpers: {
             Playwright: { browser: config.playwright.browser, url: config.playwright.url },

package/dist/src/utils/url-matcher.d.ts

@@ -4,3 +4,4 @@ export declare function generalizeSegment(segment: string): string;
 export declare function generalizeUrl(url: string): string;
 export declare function matchesUrl(pattern: string, path: string): boolean;
 export declare function extractStatePath(url: string): string;
+export declare function matchesNavigationUrl(expected: string, current: string): boolean;

package/dist/src/utils/url-matcher.js

@@ -102,3 +102,12 @@ export function extractStatePath(url) {
         return url;
     }
 }
+export function matchesNavigationUrl(expected, current) {
+    const expectedPath = extractStatePath(expected);
+    let currentPath = extractStatePath(current);
+    if (!expectedPath.includes('#')) {
+        currentPath = currentPath.split('#')[0];
+    }
+    const normalize = (value) => value.replace(/^\/+|\/+$/g, '').toLowerCase();
+    return normalize(expectedPath) === normalize(currentPath);
+}

package/models.json

@@ -4,6 +4,9 @@
     "visionModel": "google/gemma-4-31b-it:nitro",
     "agenticModel": "google/gemma-4-31b-it:nitro"
   },
+  "poolside": {
+    "model": "poolside/laguna-xs-2.1"
+  },
   "groq": {
     "model": "openai/gpt-oss-20b",
     "visionModel": "qwen/qwen3.6-27b",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -14,7 +14,8 @@
     }
   },
   "bin": {
-    "explorbot": "./dist/bin/explorbot-cli.js"
+    "explorbot": "./dist/bin/explorbot-cli.js",
+    "prima": "./dist/boat/prima/bin/prima-cli.js"
   },
   "files": [
     "dist/",
@@ -25,6 +26,9 @@
     "boat/doc-collector/src/**/*.ts",
     "boat/doc-collector/bin/**/*.ts",
     "boat/doc-collector/package.json",
+    "boat/prima/src/**/*.ts",
+    "boat/prima/bin/**/*.ts",
+    "boat/prima/package.json",
     "rules/",
     "assets/sample-files/",
     "models.json"
@@ -114,7 +118,9 @@
     "micromatch": "^4.0.8",
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
+    "pixelmatch": "^7.2.0",
     "playwright": "^1.60",
+    "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",
     "strip-ansi": "^7.1.2",
@@ -131,6 +137,7 @@
     "@types/debug": "^4.1.12",
     "@types/jsdom": "^27.0.0",
     "@types/micromatch": "^4.0.9",
+    "@types/pngjs": "^6.0.5",
     "@types/react": "^18.2.0",
     "@types/yargs": "^17.0.24",
     "bunosh": "^0.4.0",

package/src/action.ts

@@ -65,8 +65,8 @@ class Action {
     return this.recovery(() => this.captureOnce(opts));
   }
 
-  async execute(code: string): Promise<Action> {
-    return this.recovery(() => this.executeOnce(code));
+  async execute(code: string, opts: ExecuteOptions = {}): Promise<Action> {
+    return this.recovery(() => this.executeOnce(code, opts.verbatim));
   }
 
   private async captureOnce({ includeScreenshot = false, codeBlock }: { includeScreenshot?: boolean; codeBlock?: string } = {}): Promise<ActionResult> {
@@ -270,7 +270,7 @@ class Action {
     }
   }
 
-  private async executeOnce(code: string): Promise<Action> {
+  private async executeOnce(code: string, verbatim = false): Promise<Action> {
     let error: Error | null = null;
 
     setActivity('🔎 Browsing...', 'action');
@@ -287,8 +287,8 @@ class Action {
     const tracer = trace.getTracer('ai');
     const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
     setStepSpanParent(stepSpan);
-    const sanitizedCode = sanitizeCodeBlock(codeString);
-    const isPlaywright = hasPlaywrightCommands(sanitizedCode);
+    const sanitizedCode = verbatim ? codeString : sanitizeCodeBlock(codeString);
+    const isPlaywright = !verbatim && hasPlaywrightCommands(sanitizedCode);
 
     try {
       debugLog('Executing action:', codeString);
@@ -386,6 +386,10 @@ export default Action;
 
 export type RecoveryRunner = <T>(fn: () => Promise<T>) => Promise<T>;
 
+export interface ExecuteOptions {
+  verbatim?: boolean;
+}
+
 function errorToString(error: any): string {
   if (error.cliMessage) {
     return error.cliMessage();

package/src/ai/captain/mixin.ts

@@ -16,7 +16,7 @@ export interface ModeContext {
 }
 
 export function resolveProjectRoot(): string | null {
-  const configPath = ConfigParser.getInstance().getConfigPath();
-  if (!configPath) return null;
-  return dirname(configPath);
+  const configParser = ConfigParser.getInstance();
+  if (!configParser.getConfigPath()) return null;
+  return configParser.getProjectRoot();
 }

package/src/ai/captain/web-mode.ts

@@ -27,7 +27,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
           execute: async ({ destination }) => {
             try {
               debugLog('navigate', destination);
-              await ctx.explorBot.agentNavigator().visit(destination);
+              await ctx.explorBot.visit(destination);
               const stateManager = ctx.explorBot.stateManager();
               const state = stateManager.getCurrentState();
               return { success: true, url: state?.url, title: state?.title };

package/src/ai/navigator.ts

@@ -13,7 +13,7 @@ import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import { extractStatePath } from '../utils/url-matcher.js';
+import { extractStatePath, matchesNavigationUrl } from '../utils/url-matcher.js';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import type { Provider } from './provider.js';
@@ -134,7 +134,7 @@ class Navigator implements Agent {
       return false;
     }
     const currentUrl = this.getComparableCurrentUrl(stateManager, expectedUrl);
-    return normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
+    return matchesNavigationUrl(expectedUrl, currentUrl);
   }
 
   async visit(url: string): Promise<void> {
@@ -189,14 +189,16 @@ class Navigator implements Agent {
     }
   }
 
-  async resolveState(message: string, actionResult: ActionResult, opts?: { action?: Action; expectedUrl?: string }): Promise<boolean> {
+  async resolveState(message: string, actionResult: ActionResult, opts?: { action?: Action; expectedUrl?: string; onAttempt?: (attempt: { code: string; error?: string }) => void }): Promise<boolean> {
+    if (!this.provider) throw new Error('AI-assisted recovery is unavailable: no AI model is configured.');
+
     tag('info').log('AI Navigator resolving state at', actionResult.url);
     debugLog('Resolution message:', message);
 
     const action = opts?.action ?? this.explorer.action();
     const expectedUrl = opts?.expectedUrl;
 
-    const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
+    const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
     let experience = '';
 
     if (!actionResult.isInsideIframe) {
@@ -363,24 +365,27 @@ class Navigator implements Agent {
           }
         }
 
+        if (attemptOk) opts?.onAttempt?.({ code: codeBlock });
+
         if (!attemptOk) {
           const raw = action.lastError?.message || 'attempt failed';
           const firstMeaningful = raw.split('\n').find((l) => l.trim() && !l.trim().startsWith('at ')) || raw;
           const shortErr = firstMeaningful.replace(/\s+/g, ' ').trim().slice(0, 220);
           batchFailures.push({ code: codeBlock, error: shortErr });
+          opts?.onAttempt?.({ code: codeBlock, error: shortErr });
         }
 
         if (expectedUrl) {
           if (page) {
             try {
-              await page.waitForURL((url: URL) => normalizeUrl(url.pathname) === normalizeUrl(expectedUrl), { timeout: 5000 });
+              await page.waitForURL((url: URL) => matchesNavigationUrl(expectedUrl, `${url.pathname}${url.search}${url.hash}`), { timeout: 5000 });
             } catch {
               // URL did not transition to expectedUrl within timeout
             }
           }
           const freshState = await this.explorer.capture();
           const currentUrl = /^https?:\/\//i.test(expectedUrl) ? freshState.fullUrl || freshState.url || '' : freshState.url || '';
-          const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
+          const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && matchesNavigationUrl(expectedUrl, currentUrl);
           const stateChanged = freshState.getStateHash() !== actionResult.getStateHash();
           resolved = urlMatches && stateChanged;
 
@@ -625,7 +630,7 @@ class Navigator implements Agent {
       return { verified: cachedVerification, successfulCodes: [], assertionSteps: [], totalAttempted: 0 };
     }
 
-    const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
+    const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
     let experience = '';
 
     if (!actionResult.isInsideIframe) {

package/src/ai/planner.ts

@@ -53,6 +53,7 @@ export class Planner extends PlannerBase implements Agent {
   provider: Provider;
   stateManager: StateManager;
   private experienceTracker: ExperienceTracker;
+  private knowledgeTracker: AgentDeps['knowledgeTracker'];
 
   MIN_TASKS = 3;
   MAX_TASKS = 12;
@@ -70,6 +71,7 @@ export class Planner extends PlannerBase implements Agent {
     this.researcher = researcher;
     this.stateManager = deps.stateManager;
     this.experienceTracker = deps.stateManager.getExperienceTracker();
+    this.knowledgeTracker = deps.knowledgeTracker;
   }
 
   setFisherman(fisherman: Fisherman): void {
@@ -411,6 +413,11 @@ export class Planner extends PlannerBase implements Agent {
       </page_research>
     `);
 
+    const applicationContext = this.knowledgeTracker.renderApplicationSpec(state);
+    if (applicationContext) {
+      conversation.addUserText(applicationContext);
+    }
+
     conversation.addUserText(dedent`
       ${this.buildApproach(style)}
 

package/src/ai/researcher/locators.ts

@@ -228,7 +228,7 @@ export function WithLocators<T extends Constructor>(Base: T) {
         const eidxList = section.elements.map((el) => el.eidx).filter(Boolean) as string[];
         if (eidxList.length < 2) continue;
 
-        const ancestor = await this.explorer.runWithBrowserRecovery('recoverContainerFromChildren', () => WebElement.commonAncestor(this.explorer.playwrightHelper.page, eidxList));
+        const ancestor = await this.explorer.withPage((page) => WebElement.commonAncestor(page, eidxList));
         if (!ancestor) continue;
 
         const candidates: string[] = [];

package/src/ai/researcher.ts

@@ -438,7 +438,7 @@ export class Researcher extends ResearcherBase implements Agent {
     if (!this.actionResult) throw new Error('actionResult is not set');
 
     const html = await this.actionResult.combinedHtml();
-    const knowledge = this.knowledgeTracker.renderRelevantKnowledge(this.actionResult);
+    const knowledge = this.knowledgeTracker.renderRelevantContext(this.actionResult);
 
     const ariaSnapshot = this.actionResult.getCompactARIA();
 

package/src/ai/task-agent.ts

@@ -73,7 +73,7 @@ export abstract class TaskAgent {
   }
 
   protected getKnowledge(actionResult: ActionResult): string {
-    return this.getKnowledgeTracker().renderRelevantKnowledge(actionResult);
+    return this.getKnowledgeTracker().renderRelevantContext(actionResult);
   }
 
   protected getExperience(actionResult: ActionResult): string {

package/src/ai/tester.ts

@@ -62,6 +62,7 @@ export class Tester extends TaskAgent implements Agent {
   private seenUiMapUrls = new Set<string>();
   private lastAnalyzedStateHash: string | null = null;
   private stalledIterations = 0;
+  private hasSuccessfulAssertion = false;
   private readonly MAX_STALLED_ITERATIONS = 3;
 
   constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any) {
@@ -110,6 +111,7 @@ export class Tester extends TaskAgent implements Agent {
     this.seenUiMapUrls.clear();
     this.lastAnalyzedStateHash = null;
     this.stalledIterations = 0;
+    this.hasSuccessfulAssertion = false;
     this.stateManager.clearHistory();
     this.resetFailureCount();
     this.pilot?.reset();
@@ -312,9 +314,17 @@ export class Tester extends TaskAgent implements Agent {
           const allToolNames = result?.toolExecutions?.map((execution: any) => execution.toolName) || [];
           const successfulToolNames = result?.toolExecutions?.filter((execution: any) => execution.wasSuccessful)?.map((execution: any) => execution.toolName) || [];
           const actionPerformed = !!allToolNames.find((toolName: string) => this.ACTION_TOOLS.includes(toolName));
+          const successfulActionPerformed = !!successfulToolNames.find((toolName: string) => this.ACTION_TOOLS.includes(toolName));
           assertionPerformed = !!successfulToolNames.find((toolName: string) => this.ASSERTION_TOOLS.includes(toolName));
           const wasSuccessful = result?.toolExecutions?.every((execution: any) => execution.wasSuccessful);
 
+          if (successfulActionPerformed) {
+            this.hasSuccessfulAssertion = false;
+          }
+          if (assertionPerformed) {
+            this.hasSuccessfulAssertion = true;
+          }
+
           this.trackToolExecutions(result?.toolExecutions || []);
 
           if (this.consecutiveEmptyResults >= 5) {
@@ -464,6 +474,11 @@ export class Tester extends TaskAgent implements Agent {
     this.stalledIterations++;
     if (this.stalledIterations < this.MAX_STALLED_ITERATIONS) return false;
 
+    if (this.hasSuccessfulAssertion) {
+      task.addNote('No further browser progress after successful verification; requesting final review');
+      return true;
+    }
+
     task.addNote('No browser progress after repeated attempts on unchanged page', TestResult.FAILED);
     task.finish(TestResult.FAILED);
     return true;

package/src/application-spec-contract.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const APPLICATION_SPEC_FORMAT = 'explorbot-application-spec';
+export const APPLICATION_SPEC_VERSION = 1;
+
+export const APPLICATION_SPEC_PAGE_SCHEMA = z.object({
+  format: z.literal(APPLICATION_SPEC_FORMAT),
+  version: z.literal(APPLICATION_SPEC_VERSION),
+  url: z.string().trim().min(1),
+});

package/src/application-spec.ts

@@ -0,0 +1,87 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import dedent from 'dedent';
+import { ActionResult } from './action-result.ts';
+import { APPLICATION_SPEC_PAGE_SCHEMA } from './application-spec-contract.ts';
+import { ConfigParser } from './config.ts';
+import { tag } from './utils/logger.ts';
+import { loadMarkdownFiles } from './utils/markdown-files.ts';
+
+export class ApplicationSpec {
+  private pages: ApplicationSpecPage[] = [];
+  readonly sourcePath: string;
+
+  constructor(sourcePath: string) {
+    this.sourcePath = this.resolveSourcePath(sourcePath);
+    this.load();
+  }
+
+  renderFor(state: ActionResult): string {
+    const relevant = this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
+    if (relevant.length === 0) return '';
+
+    tag('operation').log(`Found application specification for ${state.url}`);
+    return dedent`
+      <application_spec>
+      This is previously collected application documentation. Treat User Can and observed state transitions as supporting context, not as a replacement for the current page state. Treat User Might as unverified possibilities that must be confirmed before use.
+
+      ${relevant.map((page) => page.content).join('\n\n')}
+      </application_spec>
+    `;
+  }
+
+  get pageCount(): number {
+    return this.pages.length;
+  }
+
+  private load(): void {
+    if (!existsSync(this.sourcePath)) {
+      throw new Error(`Application spec not found: ${this.sourcePath}`);
+    }
+
+    const isDirectory = statSync(this.sourcePath).isDirectory();
+    if (!isDirectory && path.basename(this.sourcePath).toLowerCase() !== 'index.md') {
+      throw new Error(`Application spec file must be index.md: ${this.sourcePath}`);
+    }
+
+    const bundlePath = isDirectory ? this.sourcePath : path.dirname(this.sourcePath);
+    const indexPath = path.join(bundlePath, 'index.md');
+    if (!existsSync(indexPath)) {
+      throw new Error(`Application spec index not found: ${indexPath}`);
+    }
+
+    const pagesPath = path.join(bundlePath, 'pages');
+    if (!existsSync(pagesPath)) {
+      throw new Error(`Application spec pages directory not found: ${pagesPath}`);
+    }
+
+    for (const file of loadMarkdownFiles(pagesPath, { recursive: true })) {
+      const parsed = APPLICATION_SPEC_PAGE_SCHEMA.safeParse(file.data);
+      if (!parsed.success && parsed.error.issues.some((issue) => issue.path[0] === 'format')) {
+        throw new Error(`Invalid application spec format in ${file.filePath}`);
+      }
+      if (!parsed.success && parsed.error.issues.some((issue) => issue.path[0] === 'version')) {
+        throw new Error(`Unsupported application spec version in ${file.filePath}: ${String(file.data.version)}`);
+      }
+      if (!parsed.success) {
+        throw new Error(`Application spec page URL is missing in ${file.filePath}`);
+      }
+      this.pages.push({ url: parsed.data.url, content: file.content.trim() });
+    }
+
+    if (this.pages.length === 0) {
+      throw new Error(`Application spec contains no documented pages: ${pagesPath}`);
+    }
+  }
+
+  private resolveSourcePath(sourcePath: string): string {
+    if (path.isAbsolute(sourcePath)) return path.resolve(sourcePath);
+    const configParser = ConfigParser.getInstance();
+    return path.resolve(configParser.resolveProjectDir(sourcePath));
+  }
+}
+
+interface ApplicationSpecPage {
+  url: string;
+  content: string;
+}