explorbot 0.4.0 → 0.4.2

package/dist/src/commands/init-command.js

@@ -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.js";
+import { ConfigParser, PROVIDERS, missingModelRoles } from "../config.js";
 import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from "../global-config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { log, tag } from '../utils/logger.js';
@@ -82,7 +82,7 @@ export function writeGlobalConfig(provider, apiKey) {
     const envKey = PROVIDERS[provider].envKey;
     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()}`);
     }
@@ -139,7 +139,7 @@ export function runInitCommand(options) {
         else {
             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)}`);
         }
@@ -269,10 +269,6 @@ function isModuleProject(configDir) {
         currentDir = parentDir;
     }
 }
-function missingRoles(provider) {
-    const recommended = ConfigParser.recommendedModels()[provider] || {};
-    return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);
-}
 function writeEnvKey(key, value) {
     const envPath = globalEnvPath();
     let content = '# AI provider API keys';

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

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+export declare abstract class BaseOption {
+    abstract flags: string;
+    abstract description: string;
+    collect?: (value: string, previous: any) => any;
+    register(program: Command): void;
+    abstract apply(options: Record<string, any>, command: Command): void;
+}

package/dist/src/commands/options/base-option.js

@@ -0,0 +1,12 @@
+export class BaseOption {
+    collect;
+    register(program) {
+        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);
+        });
+    }
+}

package/dist/src/commands/options/index.d.ts

@@ -0,0 +1,5 @@
+import { KnowledgeOption } from './knowledge-option.js';
+import { WsOption } from './ws-option.js';
+export { BaseOption } from './base-option.js';
+export declare const knowledgeOption: KnowledgeOption;
+export declare const wsOption: WsOption;

package/dist/src/commands/options/index.js

@@ -0,0 +1,5 @@
+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/dist/src/commands/options/knowledge-option.d.ts

@@ -0,0 +1,7 @@
+import { BaseOption } from './base-option.js';
+export declare class KnowledgeOption extends BaseOption {
+    flags: string;
+    description: string;
+    collect: (value: string, previous?: string[]) => string[];
+    apply(options: Record<string, any>): void;
+}

package/dist/src/commands/options/knowledge-option.js

@@ -0,0 +1,12 @@
+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, previous = []) => [...previous, value];
+    apply(options) {
+        for (const text of options.knowledge || []) {
+            KnowledgeTracker.appendSessionKnowledge(text);
+        }
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import { BaseOption } from './base-option.js';
+export declare class WsOption extends BaseOption {
+    flags: string;
+    description: string;
+    apply(options: Record<string, any>, command: Command): void;
+}

package/dist/src/commands/options/ws-option.js

@@ -0,0 +1,21 @@
+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';
+    apply(options, command) {
+        const url = options.ws || process.env.EXPLORBOT_WS_URL;
+        if (!url)
+            return;
+        remote.attach(String(url), commandPath(command));
+    }
+}
+function commandPath(command) {
+    const parts = [];
+    let node = command;
+    while (node) {
+        parts.unshift(node.name());
+        node = node.parent;
+    }
+    return parts.slice(1).join(' ') || parts.join(' ');
+}

package/dist/src/commands/plans-command.d.ts

@@ -11,7 +11,10 @@ export declare class PlansCommand extends BaseCommand {
     getPlanFiles(): PlanFile[];
     printPlans(files: PlanFile[]): void;
     printPlanDetails(plan: Plan, file: PlanFile): void;
-    resolvePlanFile(target: string, files: PlanFile[]): PlanFile;
+    resolvePlanFile(target: string, files: PlanFile[]): {
+        plan: Plan;
+        file: PlanFile;
+    };
 }
 interface PlanFile {
     name: string;

package/dist/src/commands/plans-command.js

@@ -17,8 +17,7 @@ export class PlansCommand extends BaseCommand {
             this.printPlans(files);
             return;
         }
-        const file = this.resolvePlanFile(target, files);
-        const plan = Plan.fromMarkdown(file.path);
+        const { plan, file } = this.resolvePlanFile(target, files);
         this.printPlanDetails(plan, file);
     }
     getPlanFiles() {
@@ -68,16 +67,17 @@ export class PlansCommand extends BaseCommand {
             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());
         if (!plan?.filePath) {
             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/dist/src/commands/recommended-models-command.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import { BaseCommand } from './base-command.js';
+export declare class RecommendedModelsCommand extends BaseCommand {
+    name: string;
+    description: string;
+    execute(): Promise<void>;
+    static register(program: Command): void;
+    static render(json?: boolean): string;
+}

package/dist/src/commands/recommended-models-command.js

@@ -0,0 +1,85 @@
+import chalk from 'chalk';
+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 = {
+    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() {
+        tag('info').log(RecommendedModelsCommand.render());
+    }
+    static register(program) {
+        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) {
+        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 = [];
+            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 = [
+                ['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 = [];
+        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/dist/src/config.d.ts

@@ -1,5 +1,6 @@
 import { type SiteRecord } from './global-config.js';
 export declare const PROVIDERS: Record<string, ProviderInfo>;
+export declare const MODEL_ROLES: ModelRole[];
 interface PlaywrightConfig {
     browser: 'chromium' | 'firefox' | 'webkit';
     url: string;
@@ -255,6 +256,7 @@ export declare class ConfigParser {
     static getTestDirectories(): string[];
     static cleanupAllTestDirectories(): void;
     enterGlobalMode(config: ExplorbotConfig, target: string | null): void;
+    applyEnvSpec(config: ExplorbotConfig): void;
     buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
     loadConfigModule(configPath: string): Promise<any>;
@@ -269,6 +271,7 @@ export declare class ConfigParser {
 }
 export declare function outputPath(...segments: string[]): string;
 export declare function resolveModel(spec: string, role?: ModelRole): Promise<any>;
+export declare function missingModelRoles(provider: string): ModelRole[];
 export declare class ConfigMissingError extends Error {
 }
 export declare function envConfigRequested(): boolean;

package/dist/src/config.js

@@ -25,6 +25,7 @@ export const PROVIDERS = {
     openrouter: { envKey: 'OPENROUTER_API_KEY', load: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter() },
     sambanova: { envKey: 'SAMBANOVA_API_KEY', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
 };
+export const MODEL_ROLES = ['model', 'visionModel', 'agenticModel'];
 let cachedOutputRoot = null;
 const config = {
     playwright: {
@@ -46,6 +47,7 @@ export const EXPLORBOT_ENV_VARS = [
     { 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' },
@@ -129,6 +131,7 @@ export class ConfigParser {
             if (resolvedPath && isGlobalConfigPath(resolvedPath)) {
                 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);
@@ -269,8 +272,17 @@ export class ConfigParser {
         this.siteStartPath = site.path;
         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}`);
     }
+    applyEnvSpec(config) {
+        const spec = process.env.EXPLORBOT_SPEC;
+        if (!spec)
+            return;
+        if (!config.dirs)
+            config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
+        config.dirs.spec = spec;
+    }
     async buildEnvConfig(baseUrl, outputRoot) {
         const provider = process.env.EXPLORBOT_AI_PROVIDER;
         const modelSpec = process.env.EXPLORBOT_AI_MODEL;
@@ -447,6 +459,10 @@ export async function resolveModel(spec, role = 'model') {
     }
     return createModel(spec, modelId);
 }
+export function missingModelRoles(provider) {
+    const recommended = ConfigParser.recommendedModels()[provider] || {};
+    return MODEL_ROLES.filter((role) => !recommended[role]);
+}
 export class ConfigMissingError extends Error {
 }
 export function envConfigRequested() {
@@ -467,6 +483,7 @@ export function missingConfigMessage(configFile = 'explorbot.config.js') {
         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
   `;
 }
 export function modelName(model) {
@@ -500,8 +517,7 @@ export function configuredModels(ai) {
 export async function resolveConfigModels(ai) {
     if (!ai)
         return;
-    const roles = ['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/dist/src/experience-tracker.js

@@ -105,7 +105,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/dist/src/explorbot.js

@@ -132,7 +132,7 @@ export class ExplorBot {
         return this.explorer;
     }
     knowledgeTracker() {
-        return (this._knowledgeTracker ||= new KnowledgeTracker(this.options.applicationSpec));
+        return (this._knowledgeTracker ||= new KnowledgeTracker({ applicationSpec: this.options.applicationSpec }));
     }
     experienceTracker() {
         return (this._experienceTracker ||= new ExperienceTracker(this.knowledgeTracker()));
@@ -399,10 +399,10 @@ export class ExplorBot {
         return plan;
     }
     loadPlans(filename) {
-        const plan = Plan.loadFromFile(filename, this.getPlansDir());
-        if (!plan?.filePath)
+        const filePath = Plan.resolveFile(filename, this.getPlansDir());
+        if (!filePath)
             throw new Error(`Plan file not found: ${filename}`);
-        return parsePlansFromMarkdown(plan.filePath);
+        return parsePlansFromMarkdown(filePath);
     }
     setCurrentPlan(plan) {
         this.currentPlan = plan;

package/dist/src/global-config.d.ts

@@ -6,6 +6,8 @@ export declare function isGlobalConfigPath(configPath: string): boolean;
 export declare function sitesDir(): string;
 export declare function siteFolderName(url: string): string;
 export declare function listSites(): SiteRecord[];
+export declare function findSiteWith(subpath: string): SiteRecord | undefined;
+export declare function listSitePlanDirs(): string[];
 export declare function registerSite(baseUrl: string): SiteRecord;
 export declare function resolveSiteTarget(target?: string, defaultBaseUrl?: string): SiteTarget;
 interface SiteRecord {

package/dist/src/global-config.js

@@ -38,6 +38,12 @@ export function listSites() {
         .filter((site) => !!site)
         .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
 }
+export function findSiteWith(subpath) {
+    return listSites().find((site) => existsSync(join(site.dir, subpath)));
+}
+export function listSitePlanDirs() {
+    return listSites().map((site) => join(site.dir, 'output', 'plans'));
+}
 export function registerSite(baseUrl) {
     const folder = siteFolderName(baseUrl);
     const dir = join(sitesDir(), folder);

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

@@ -1,20 +1,19 @@
 import { ActionResult } from './action-result.js';
 import { ApplicationSpec } from './application-spec.js';
-export interface Knowledge {
-    filePath: string;
-    url: string;
-    content: string;
-    [key: string]: any;
-}
 export declare class KnowledgeTracker {
     knowledgeDir: string;
     knowledgeFiles: Knowledge[];
+    sessionKnowledge: Knowledge[];
     isLoaded: boolean;
     applicationSpec?: ApplicationSpec;
-    constructor(applicationSpecPath?: string);
+    static appendSessionKnowledge(text: string): void;
+    static resetSessionKnowledge(): void;
+    constructor(options?: KnowledgeTrackerOptions);
     loadKnowledgeFiles(): void;
     getRelevantKnowledge(state: ActionResult): Knowledge[];
+    getEndpointKnowledge(endpoint: string): Knowledge[];
     renderRelevantKnowledge(state: ActionResult): string;
+    renderEndpointKnowledge(endpoint: string): string;
     renderRelevantContext(state: ActionResult): string;
     renderApplicationSpec(state: ActionResult): string;
     addKnowledge(urlPattern: string, description: string, opts?: {
@@ -36,4 +35,18 @@ export declare class KnowledgeTracker {
     getMatchingKnowledge(url: string): Knowledge[];
     normalizeUrl(url: string): string;
     getStateParameters(state: ActionResult, keys: string[]): Record<string, any>;
+    allKnowledge(): Knowledge[];
+    toKnowledge(filePath: string, data: Record<string, any>, content: string): Knowledge;
+    renderKnowledge(knowledgeFiles: Knowledge[], scope: string): string;
+}
+export interface Knowledge {
+    filePath: string;
+    url?: string;
+    endpoint?: string;
+    content: string;
+    [key: string]: any;
+}
+export interface KnowledgeTrackerOptions {
+    applicationSpec?: string;
+    knowledgeDir?: string;
 }

package/dist/src/knowledge-tracker.js

@@ -11,61 +11,67 @@ 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');
+const sessionEntries = [];
 export class KnowledgeTracker {
     knowledgeDir;
     knowledgeFiles = [];
+    sessionKnowledge = [];
     isLoaded = false;
     applicationSpec;
-    constructor(applicationSpecPath) {
-        const configParser = ConfigParser.getInstance();
-        const config = configParser.getConfig();
-        this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
+    static appendSessionKnowledge(text) {
+        sessionEntries.push(text);
+    }
+    static resetSessionKnowledge() {
+        sessionEntries.length = 0;
+    }
+    constructor(options = {}) {
+        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());
+        });
     }
     loadKnowledgeFiles() {
         if (this.isLoaded)
             return;
         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;
     }
     getRelevantKnowledge(state) {
         this.loadKnowledgeFiles();
-        return this.knowledgeFiles.filter((knowledge) => {
-            return state.isMatchedBy(knowledge);
-        });
+        return this.allKnowledge().filter((knowledge) => knowledge.url && state.isMatchedBy(knowledge));
+    }
+    getEndpointKnowledge(endpoint) {
+        this.loadKnowledgeFiles();
+        const path = extractStatePath(endpoint);
+        return this.allKnowledge().filter((knowledge) => knowledge.endpoint && matchesUrl(knowledge.endpoint, path));
     }
     renderRelevantKnowledge(state) {
-        const knowledgeFiles = this.getRelevantKnowledge(state);
-        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 page:
-
-      ${knowledgeContent}
-      </knowledge>
-    `;
+        return this.renderKnowledge(this.getRelevantKnowledge(state), 'page');
+    }
+    renderEndpointKnowledge(endpoint) {
+        return this.renderKnowledge(this.getEndpointKnowledge(endpoint), 'endpoint');
     }
     renderRelevantContext(state) {
         return [this.renderRelevantKnowledge(state), this.renderApplicationSpec(state)].filter(Boolean).join('\n\n');
@@ -151,7 +157,7 @@ export class KnowledgeTracker {
     }
     getExistingUrls() {
         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) {
         this.loadKnowledgeFiles();
@@ -164,7 +170,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,
             };
@@ -194,4 +200,36 @@ export class KnowledgeTracker {
         }
         return result;
     }
+    allKnowledge() {
+        return [...this.knowledgeFiles, ...this.sessionKnowledge];
+    }
+    toKnowledge(filePath, data, content) {
+        const 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;
+    }
+    renderKnowledge(knowledgeFiles, scope) {
+        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>
+    `;
+    }
 }

package/dist/src/remote.d.ts

@@ -1,4 +1,3 @@
-import type { Command } from 'commander';
 import { type ActivityEntry } from './activity.js';
 import { type LogDestination, type TaggedLogEntry } from './utils/logger.js';
 /**
@@ -19,7 +18,6 @@ export declare class Remote implements LogDestination {
     asks: Map<string, (value: string | null) => void>;
     askCounter: number;
     lastActivity: string | null;
-    registerOption(program: Command): void;
     attach(url: string, command: string): void;
     isAttached(): boolean;
     send(type: string, data?: Record<string, unknown>): void;
@@ -42,7 +40,6 @@ export declare class Remote implements LogDestination {
      *  nothing — so skip repeats, the priming null included. */
     reportActivity(activity: ActivityEntry | null): void;
     errorOf(args: any[] | undefined): string | undefined;
-    commandPath(command: Command): string;
 }
 export declare const remote: Remote;
 /** Whatever the run wants to say. Not a schema — the UI renders what it knows