explorbot 0.4.0 → 0.4.2

package/src/commands/explore-command.ts

@@ -261,9 +261,15 @@ export class ExploreCommand extends BaseCommand {
       tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
       try {
         await this.explorBot.visit(pick.url);
+        const errorPage = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
+        if (errorPage) {
+          tag('warning').log(`Skipping sub-page: ${errorPage.message}`);
+          this.failedSubPages.add(normalizeUrl(pick.url));
+          continue;
+        }
         await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans, styles);
         const subPlan = this.explorBot.getCurrentPlan();
-        if (subPlan && !this.completedPlans.includes(subPlan)) {
+        if (subPlan?.tests.length && !this.completedPlans.includes(subPlan)) {
           this.completedPlans.push(subPlan);
         }
         knownUrls.add(normalizeUrl(pick.url));
@@ -298,6 +304,11 @@ export class ExploreCommand extends BaseCommand {
       if (fresh && parentPlan) opts.extend = parentPlan;
       if (this.dryRun) opts.noSave = true;
       await this.planWithRetry(feature, opts, pageUrl);
+      const plan = this.explorBot.getCurrentPlan();
+      if (plan && plan.tests.length === 0) {
+        tag('warning').log('Nothing to test on this page, moving on');
+        return;
+      }
       await this.runPendingTests();
       this.rememberCurrentPlan();
       fresh = false;

package/src/commands/index.ts

@@ -28,6 +28,7 @@ import { PlanLoadCommand } from './plan-load-command.js';
 import { PlanReloadCommand } from './plan-reload-command.js';
 import { PlanSaveCommand } from './plan-save-command.js';
 import { PlansCommand } from './plans-command.js';
+import { RecommendedModelsCommand } from './recommended-models-command.js';
 import { RerunCommand } from './rerun-command.js';
 import { ResearchCommand } from './research-command.js';
 import { RunsCommand } from './runs-command.js';
@@ -72,6 +73,7 @@ const commandClasses: CommandClass[] = [
   RerunCommand,
   StatusCommand,
   ConfigCommand,
+  RecommendedModelsCommand,
   DebugCommand,
   ExitCommand,
 ];

package/src/commands/init-command.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
-import { ConfigParser, PROVIDERS } from '../config.ts';
+import { ConfigParser, type ModelRole, PROVIDERS, missingModelRoles } from '../config.ts';
 import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from '../global-config.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { log, tag } from '../utils/logger.js';
@@ -91,7 +91,7 @@ export function writeGlobalConfig(provider: string, apiKey?: string): void {
   writeEnvKey(envKey, apiKey || '');
   log(`Stored ${envKey} in ${globalEnvPath()}`);
 
-  const missing = missingRoles(provider);
+  const missing = missingModelRoles(provider);
   if (missing.length) {
     tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${globalConfigPath()}`);
   }
@@ -156,7 +156,7 @@ export function runInitCommand(options: InitCommandOptions): void {
       log(`Env file already exists: ${relativeToCwd(envPath)}`);
     }
 
-    const missing = missingRoles(provider);
+    const missing = missingModelRoles(provider);
     if (missing.length) {
       tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
     }
@@ -255,7 +255,7 @@ async function renderLocalProviderWizard(): Promise<string | null> {
 
 function modelLines(provider: string): string {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
-  const roles: Array<[ModelRoleName, string]> = [
+  const roles: Array<[ModelRole, string]> = [
     ['model', 'fast model with tool calling capabilities'],
     ['visionModel', 'vision model for screenshot analysis'],
     ['agenticModel', 'agentic model for decision making'],
@@ -308,11 +308,6 @@ function isModuleProject(configDir: string): boolean {
   }
 }
 
-function missingRoles(provider: string): string[] {
-  const recommended = ConfigParser.recommendedModels()[provider] || {};
-  return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);
-}
-
 function writeEnvKey(key: string, value: string): void {
   const envPath = globalEnvPath();
   let content = '# AI provider API keys';
@@ -327,8 +322,6 @@ function writeEnvKey(key: string, value: string): void {
   writeFileSync(envPath, `${lines.join('\n').trimEnd()}\n`, 'utf8');
 }
 
-type ModelRoleName = 'model' | 'visionModel' | 'agenticModel';
-
 type InitCommandOptions = {
   configPath?: string;
   force?: boolean;

package/src/commands/options/base-option.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander';
+
+export abstract class BaseOption {
+  abstract flags: string;
+  abstract description: string;
+  collect?: (value: string, previous: any) => any;
+
+  register(program: Command): void {
+    if (this.collect) program.option(this.flags, this.description, this.collect);
+    if (!this.collect) program.option(this.flags, this.description);
+
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+      this.apply(actionCommand.optsWithGlobals(), actionCommand);
+    });
+  }
+
+  protected abstract apply(options: Record<string, any>, command: Command): void;
+}

package/src/commands/options/index.ts

@@ -0,0 +1,7 @@
+import { KnowledgeOption } from './knowledge-option.js';
+import { WsOption } from './ws-option.js';
+
+export { BaseOption } from './base-option.js';
+
+export const knowledgeOption = new KnowledgeOption();
+export const wsOption = new WsOption();

package/src/commands/options/knowledge-option.ts

@@ -0,0 +1,14 @@
+import { KnowledgeTracker } from '../../knowledge-tracker.js';
+import { BaseOption } from './base-option.js';
+
+export class KnowledgeOption extends BaseOption {
+  flags = '--knowledge <text>';
+  description = 'Knowledge for this run only, not saved to disk. Markdown text; add url: or endpoint: frontmatter to scope it, otherwise it applies everywhere. Repeatable';
+  collect = (value: string, previous: string[] = []) => [...previous, value];
+
+  protected apply(options: Record<string, any>): void {
+    for (const text of options.knowledge || []) {
+      KnowledgeTracker.appendSessionKnowledge(text);
+    }
+  }
+}

package/src/commands/options/ws-option.ts

@@ -0,0 +1,24 @@
+import type { Command } from 'commander';
+import { remote } from '../../remote.js';
+import { BaseOption } from './base-option.js';
+
+export class WsOption extends BaseOption {
+  flags = '--ws <url>';
+  description = 'Stream this run to a remote UI over WebSocket';
+
+  protected apply(options: Record<string, any>, command: Command): void {
+    const url = options.ws || process.env.EXPLORBOT_WS_URL;
+    if (!url) return;
+    remote.attach(String(url), commandPath(command));
+  }
+}
+
+function commandPath(command: Command): string {
+  const parts: string[] = [];
+  let node: Command | null = command;
+  while (node) {
+    parts.unshift(node.name());
+    node = node.parent;
+  }
+  return parts.slice(1).join(' ') || parts.join(' ');
+}

package/src/commands/plans-command.ts

@@ -21,8 +21,7 @@ export class PlansCommand extends BaseCommand {
       return;
     }
 
-    const file = this.resolvePlanFile(target, files);
-    const plan = Plan.fromMarkdown(file.path);
+    const { plan, file } = this.resolvePlanFile(target, files);
     this.printPlanDetails(plan, file);
   }
 
@@ -71,12 +70,12 @@ export class PlansCommand extends BaseCommand {
     tag('info').log(`${getCliName()} test 1 --from-plan ${file.name}`);
   }
 
-  private resolvePlanFile(target: string, files: PlanFile[]): PlanFile {
+  private resolvePlanFile(target: string, files: PlanFile[]): { plan: Plan; file: PlanFile } {
     const index = Number.parseInt(target, 10);
     if (!Number.isNaN(index) && String(index) === target) {
       const file = files[index - 1];
       if (!file) throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
-      return file;
+      return { plan: Plan.fromMarkdown(file.path), file };
     }
 
     const plan = Plan.loadFromFile(target, this.explorBot.getPlansDir());
@@ -84,11 +83,12 @@ export class PlansCommand extends BaseCommand {
       throw new Error(`Plan file not found: ${target}`);
     }
 
-    return {
+    const file = {
       name: path.basename(plan.filePath),
       path: plan.filePath,
       modifiedAt: statSync(plan.filePath).mtimeMs,
     };
+    return { plan, file };
   }
 }
 

package/src/commands/recommended-models-command.ts

@@ -0,0 +1,92 @@
+import chalk from 'chalk';
+import type { Command } from 'commander';
+import { ConfigParser, EXPLORBOT_ENV_VARS, MODEL_ROLES, PROVIDERS } from '../config.js';
+import { getCliName } from '../utils/cli-name.js';
+import { renderSection } from '../utils/cli-section.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+const DESCRIPTION = 'Show the models recommended for every AI provider';
+
+const ROLES: Record<string, { hint: string; env: string }> = {
+  model: { hint: 'fast', env: 'EXPLORBOT_AI_MODEL' },
+  visionModel: { hint: 'screenshots', env: 'EXPLORBOT_VISION_MODEL' },
+  agenticModel: { hint: 'smart', env: 'EXPLORBOT_AGENTIC_MODEL' },
+};
+
+const MODEL_ENV_VARS = MODEL_ROLES.map((role) => ROLES[role].env);
+
+export class RecommendedModelsCommand extends BaseCommand {
+  name = 'recommended-models';
+  description = DESCRIPTION;
+
+  async execute(): Promise<void> {
+    tag('info').log(RecommendedModelsCommand.render());
+  }
+
+  static register(program: Command): void {
+    program
+      .command('recommended-models')
+      .description(DESCRIPTION)
+      .option('--json', 'Print the recommendations as JSON')
+      .action((options) => console.log(RecommendedModelsCommand.render(options.json)));
+  }
+
+  static render(json = false): string {
+    const recommended = ConfigParser.recommendedModels();
+    if (json) return JSON.stringify(recommended, null, 2);
+
+    const lines = [
+      chalk.bold('Export the provider key, then pick one of two ways to select models:'),
+      `  ${chalk.bold('EXPLORBOT_AI_PROVIDER')} — every role takes that provider's recommendation below`,
+      `  ${chalk.bold(MODEL_ENV_VARS.join(' + '))} — no provider variable, pin every role yourself as ${chalk.dim('provider/model-id')}`,
+      '',
+    ];
+
+    for (const [provider, roles] of Object.entries(recommended)) {
+      lines.push(chalk.bold.yellow(`${provider}:`));
+
+      const models: [string, string][] = [];
+      for (const role of MODEL_ROLES) {
+        const label = `${role} (${ROLES[role].hint})`;
+        if (roles[role]) models.push([label, roles[role]]);
+        if (!roles[role]) models.push([label, chalk.dim('not served, pair with another provider')]);
+      }
+      lines.push(...renderSection('models', models, 2));
+
+      const envKey = PROVIDERS[provider]?.envKey;
+      if (!envKey) {
+        lines.push(`  ${chalk.dim('not bundled — import the provider in your config')}`, '');
+        continue;
+      }
+
+      const env: [string, string][] = [
+        ['key', envKey],
+        ['provider', `EXPLORBOT_AI_PROVIDER=${provider}`],
+      ];
+      let label = 'or models';
+      for (const role of MODEL_ROLES) {
+        if (!roles[role]) continue;
+        env.push([label, `${ROLES[role].env}=${provider}/${roles[role]}`]);
+        label = '';
+      }
+      lines.push(...renderSection('env variables', env, 2));
+    }
+
+    const modelVars = ['EXPLORBOT_AI_PROVIDER', ...MODEL_ENV_VARS];
+    const current: [string, string][] = [];
+    for (const variable of EXPLORBOT_ENV_VARS) {
+      if (!modelVars.includes(variable.name)) continue;
+      if (process.env[variable.name]) current.push([variable.name, process.env[variable.name]!]);
+    }
+    for (const [provider, { envKey }] of Object.entries(PROVIDERS)) {
+      if (process.env[envKey]) current.push([envKey, chalk.dim(`set, ${provider} usable`)]);
+    }
+
+    if (!current.length) lines.push(chalk.dim('Nothing set — export one of the variables above, or write models into your config'), '');
+    if (current.length) lines.push(...renderSection('Currently set', current));
+
+    lines.push(chalk.bold('Example using OpenRouter:'), `  OPENROUTER_API_KEY=sk-... EXPLORBOT_AI_PROVIDER=openrouter ${getCliName()} <command>`);
+    return lines.join('\n');
+  }
+}

package/src/config.ts

@@ -19,6 +19,8 @@ export const PROVIDERS: Record<string, ProviderInfo> = {
   sambanova: { envKey: 'SAMBANOVA_API_KEY', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
 };
 
+export const MODEL_ROLES: ModelRole[] = ['model', 'visionModel', 'agenticModel'];
+
 let cachedOutputRoot: string | null = null;
 
 interface PlaywrightConfig {
@@ -271,6 +273,7 @@ export const EXPLORBOT_ENV_VARS: EnvVar[] = [
   { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
   { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
   { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
+  { name: 'EXPLORBOT_SPEC', description: 'Docbot application spec directory or index.md, used as page knowledge' },
   { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
   { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
   { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
@@ -405,6 +408,8 @@ export class ConfigParser {
         this.enterGlobalMode(this.config, target);
       }
 
+      this.applyEnvSpec(this.config);
+
       // Restore original directory after successful config load
       if (options?.path && originalCwd !== process.cwd()) {
         process.chdir(originalCwd);
@@ -555,10 +560,18 @@ export class ConfigParser {
 
     config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
     config.playwright = { ...config.playwright, browser: config.playwright?.browser || 'chromium', url: site.baseUrl };
+    materializeKnowledge(this.site.dir);
 
     log(`Global mode: ${site.baseUrl} stored in ${this.site.dir}`);
   }
 
+  private applyEnvSpec(config: ExplorbotConfig): void {
+    const spec = process.env.EXPLORBOT_SPEC;
+    if (!spec) return;
+    if (!config.dirs) config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
+    config.dirs.spec = spec;
+  }
+
   private async buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig> {
     const provider = process.env.EXPLORBOT_AI_PROVIDER;
     const modelSpec = process.env.EXPLORBOT_AI_MODEL;
@@ -754,6 +767,11 @@ export async function resolveModel(spec: string, role: ModelRole = 'model'): Pro
   return createModel(spec, modelId);
 }
 
+export function missingModelRoles(provider: string): ModelRole[] {
+  const recommended = ConfigParser.recommendedModels()[provider] || {};
+  return MODEL_ROLES.filter((role) => !recommended[role]);
+}
+
 export class ConfigMissingError extends Error {}
 
 export function envConfigRequested(): boolean {
@@ -775,6 +793,7 @@ export function missingConfigMessage(configFile = 'explorbot.config.js'): string
         EXPLORBOT_AI_PROVIDER=openrouter EXPLORBOT_URL=https://your-app.example.com ${cli} ...
 
     Providers: ${Object.keys(PROVIDERS).join(', ')}
+    See the models each one recommends: ${cli} recommended-models
   `;
 }
 
@@ -807,8 +826,7 @@ export function configuredModels(ai?: AIConfig): Record<string, ConfiguredModel>
 export async function resolveConfigModels(ai?: AIConfig): Promise<void> {
   if (!ai) return;
 
-  const roles: ModelRole[] = ['model', 'visionModel', 'agenticModel'];
-  for (const role of roles) {
+  for (const role of MODEL_ROLES) {
     if (typeof ai[role] === 'string') ai[role] = await resolveModel(ai[role], role);
   }
 

package/src/experience-tracker.ts

@@ -127,7 +127,7 @@ export class ExperienceTracker {
         url: state.url ? extractStatePath(state.url) : '',
         title: state.title,
       };
-      if (state.overlay.present && state.overlay.name) {
+      if (state.overlay.isOpen && state.overlay.name) {
         frontmatter.region = state.overlay.name;
         if (state.overlay.root) frontmatter.root = state.overlay.root;
       }

package/src/explorbot.ts

@@ -166,7 +166,7 @@ export class ExplorBot {
   }
 
   knowledgeTracker(): KnowledgeTracker {
-    return (this._knowledgeTracker ||= new KnowledgeTracker(this.options.applicationSpec));
+    return (this._knowledgeTracker ||= new KnowledgeTracker({ applicationSpec: this.options.applicationSpec }));
   }
 
   experienceTracker(): ExperienceTracker {
@@ -465,9 +465,9 @@ export class ExplorBot {
   }
 
   loadPlans(filename: string): Plan[] {
-    const plan = Plan.loadFromFile(filename, this.getPlansDir());
-    if (!plan?.filePath) throw new Error(`Plan file not found: ${filename}`);
-    return parsePlansFromMarkdown(plan.filePath);
+    const filePath = Plan.resolveFile(filename, this.getPlansDir());
+    if (!filePath) throw new Error(`Plan file not found: ${filename}`);
+    return parsePlansFromMarkdown(filePath);
   }
 
   setCurrentPlan(plan?: Plan): void {

package/src/global-config.ts

@@ -47,6 +47,14 @@ export function listSites(): SiteRecord[] {
     .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
 }
 
+export function findSiteWith(subpath: string): SiteRecord | undefined {
+  return listSites().find((site) => existsSync(join(site.dir, subpath)));
+}
+
+export function listSitePlanDirs(): string[] {
+  return listSites().map((site) => join(site.dir, 'output', 'plans'));
+}
+
 export function registerSite(baseUrl: string): SiteRecord {
   const folder = siteFolderName(baseUrl);
   const dir = join(sitesDir(), folder);

package/src/knowledge-tracker.ts

@@ -11,36 +11,54 @@ import { loadMarkdownFiles } from './utils/markdown-files.js';
 import { mdq } from './utils/markdown-query.js';
 import { isSecretName, registerSecret } from './utils/secrets.js';
 import { slugify } from './utils/strings.js';
+import { extractStatePath, matchesUrl } from './utils/url-matcher.js';
 
 const debugLog = createDebug('explorbot:knowledge-tracker');
 
-export interface Knowledge {
-  filePath: string;
-  url: string;
-  content: string;
-  [key: string]: any;
-}
+const sessionEntries: string[] = [];
 
 export class KnowledgeTracker {
   private knowledgeDir: string;
   private knowledgeFiles: Knowledge[] = [];
+  private sessionKnowledge: Knowledge[] = [];
   private isLoaded = false;
   private applicationSpec?: ApplicationSpec;
 
-  constructor(applicationSpecPath?: string) {
-    const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
-    this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
+  static appendSessionKnowledge(text: string): void {
+    sessionEntries.push(text);
+  }
+
+  static resetSessionKnowledge(): void {
+    sessionEntries.length = 0;
+  }
+
+  constructor(options: KnowledgeTrackerOptions = {}) {
+    let knowledgeDir = options.knowledgeDir;
+    let specPath = options.applicationSpec;
+
+    if (!knowledgeDir) {
+      const configParser = ConfigParser.getInstance();
+      const config = configParser.getConfig();
+      knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
+      specPath ||= config.dirs?.spec;
+    }
+
+    this.knowledgeDir = knowledgeDir;
 
     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`);
     }
+
+    this.sessionKnowledge = sessionEntries.map((entry, index) => {
+      const parsed = matter(entry);
+      debugLog(`Session knowledge #${index + 1}`);
+      return this.toKnowledge(`--knowledge #${index + 1}`, parsed.data, parsed.content.trim());
+    });
   }
 
   private loadKnowledgeFiles(): void {
@@ -49,12 +67,7 @@ export class KnowledgeTracker {
     this.knowledgeFiles = [];
 
     for (const entry of loadMarkdownFiles(this.knowledgeDir, { recursive: true })) {
-      this.knowledgeFiles.push({
-        filePath: entry.filePath,
-        url: entry.data.url || entry.data.path || '*',
-        content: this.interpolateVars(entry.content),
-        ...entry.data,
-      });
+      this.knowledgeFiles.push(this.toKnowledge(entry.filePath, entry.data, entry.content));
     }
 
     this.isLoaded = true;
@@ -63,28 +76,22 @@ export class KnowledgeTracker {
   getRelevantKnowledge(state: ActionResult): Knowledge[] {
     this.loadKnowledgeFiles();
 
-    return this.knowledgeFiles.filter((knowledge) => {
-      return state.isMatchedBy(knowledge);
-    });
+    return this.allKnowledge().filter((knowledge) => knowledge.url && state.isMatchedBy(knowledge));
   }
 
-  renderRelevantKnowledge(state: ActionResult): string {
-    const knowledgeFiles = this.getRelevantKnowledge(state);
-    if (knowledgeFiles.length === 0) return '';
+  getEndpointKnowledge(endpoint: string): Knowledge[] {
+    this.loadKnowledgeFiles();
+    const path = extractStatePath(endpoint);
 
-    const knowledgeContent = knowledgeFiles
-      .map((k) => k.content)
-      .filter((k) => !!k)
-      .join('\n\n');
+    return this.allKnowledge().filter((knowledge) => knowledge.endpoint && matchesUrl(knowledge.endpoint, path));
+  }
 
-    tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
-    return dedent`
-      <knowledge>
-      Here is relevant knowledge for this page:
+  renderRelevantKnowledge(state: ActionResult): string {
+    return this.renderKnowledge(this.getRelevantKnowledge(state), 'page');
+  }
 
-      ${knowledgeContent}
-      </knowledge>
-    `;
+  renderEndpointKnowledge(endpoint: string): string {
+    return this.renderKnowledge(this.getEndpointKnowledge(endpoint), 'endpoint');
   }
 
   renderRelevantContext(state: ActionResult): string {
@@ -188,7 +195,7 @@ export class KnowledgeTracker {
   getExistingUrls(): string[] {
     this.loadKnowledgeFiles();
 
-    return this.knowledgeFiles.map((knowledge) => knowledge.url).filter((url) => url && url !== '*');
+    return this.knowledgeFiles.map((knowledge) => knowledge.url || '').filter((url) => url && url !== '*');
   }
 
   getKnowledgeForUrl(urlPattern: string): string[] {
@@ -205,7 +212,7 @@ export class KnowledgeTracker {
       const content = knowledge.content.trim();
       const firstLine = mdq(content).meta()[0]?.text.split('\n')[0]?.trim() || '';
       return {
-        url: knowledge.url,
+        url: knowledge.url || knowledge.endpoint || '',
         firstLine,
         filePath: knowledge.filePath,
       };
@@ -242,4 +249,55 @@ export class KnowledgeTracker {
 
     return result;
   }
+
+  private allKnowledge(): Knowledge[] {
+    return [...this.knowledgeFiles, ...this.sessionKnowledge];
+  }
+
+  private toKnowledge(filePath: string, data: Record<string, any>, content: string): Knowledge {
+    const knowledge: Knowledge = {
+      ...data,
+      filePath,
+      url: data.url || data.path,
+      content: this.interpolateVars(content),
+    };
+
+    if (!data.url && !data.path && !data.endpoint) {
+      knowledge.url = '*';
+      knowledge.endpoint = '*';
+    }
+
+    return knowledge;
+  }
+
+  private renderKnowledge(knowledgeFiles: Knowledge[], scope: string): string {
+    if (knowledgeFiles.length === 0) return '';
+
+    const knowledgeContent = knowledgeFiles
+      .map((k) => k.content)
+      .filter((k) => !!k)
+      .join('\n\n');
+
+    tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
+    return dedent`
+      <knowledge>
+      Here is relevant knowledge for this ${scope}:
+
+      ${knowledgeContent}
+      </knowledge>
+    `;
+  }
+}
+
+export interface Knowledge {
+  filePath: string;
+  url?: string;
+  endpoint?: string;
+  content: string;
+  [key: string]: any;
+}
+
+export interface KnowledgeTrackerOptions {
+  applicationSpec?: string;
+  knowledgeDir?: string;
 }

package/src/remote.ts

@@ -1,4 +1,3 @@
-import type { Command } from 'commander';
 import stripAnsi from 'strip-ansi';
 import { type ActivityEntry, addActivityListener } from './activity.ts';
 import { executionController } from './execution-controller.ts';
@@ -30,15 +29,6 @@ export class Remote implements LogDestination {
   private askCounter = 0;
   private lastActivity: string | null = null;
 
-  registerOption(program: Command): void {
-    program.option('--ws <url>', 'Stream this run to a remote UI over WebSocket');
-    program.hook('preAction', (_thisCommand, actionCommand) => {
-      const url = actionCommand.optsWithGlobals().ws || process.env.EXPLORBOT_WS_URL;
-      if (!url) return;
-      this.attach(String(url), this.commandPath(actionCommand));
-    });
-  }
-
   attach(url: string, command: string): void {
     if (this.url) return;
     this.url = url;
@@ -225,16 +215,6 @@ export class Remote implements LogDestination {
     if (typeof failure.message === 'string') return failure.message;
     return undefined;
   }
-
-  private commandPath(command: Command): string {
-    const parts: string[] = [];
-    let node: Command | null = command;
-    while (node) {
-      parts.unshift(node.name());
-      node = node.parent;
-    }
-    return parts.slice(1).join(' ') || parts.join(' ');
-  }
 }
 
 export const remote = new Remote();