explorbot 0.4.0 → 0.4.1

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
-import { remote } from "../../../src/remote.js";
+import { knowledgeOption, wsOption } from "../../../src/commands/options/index.js";
 import { createDocsCommands } from "../src/cli.js";
 const program = createDocsCommands('doc-collector');
-remote.registerOption(program);
+wsOption.register(program);
+knowledgeOption.register(program);
 program.parse();

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

@@ -15,6 +15,7 @@ function buildOptions(options) {
         incognito: options.incognito,
         session: options.session,
         docsConfig: options.docsConfig,
+        baseUrl: options.url,
     };
 }
 function addCommonOptions(cmd) {
@@ -24,6 +25,7 @@ function addCommonOptions(cmd) {
         .option('-c, --config <path>', 'Path to explorbot configuration file')
         .option('--docs-config <path>', 'Path to doc collector configuration file')
         .option('-p, --path <path>', 'Working directory path')
+        .option('--url <url>', 'Base URL of the site, when the path argument is relative (env: EXPLORBOT_URL)')
         .option('-s, --show', 'Show browser window')
         .option('--headless', 'Run browser in headless mode')
         .option('--incognito', 'Run without recording experiences')
@@ -65,7 +67,7 @@ export function createDocsCommands(name = 'docs') {
         .action(async (url, options) => {
         setQuietMode(!isVerboseMode());
         try {
-            console.log(await ConfigCommand.summary({ config: options.config, path: options.path, url, json: options.json }));
+            console.log(await ConfigCommand.summary({ config: options.config, path: options.path, url: url || options.url, json: options.json }));
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : 'Unknown error');

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

@@ -20,7 +20,7 @@ class DocBot {
     scopeRoot = '/';
     constructor(options = {}) {
         this.options = options;
-        const baseUrl = this.extractAbsoluteBaseUrl(options.startUrl || '/');
+        const baseUrl = this.extractAbsoluteBaseUrl(options.startUrl || '/') || options.baseUrl;
         this.explorBot = new ExplorBot({
             baseUrl,
             verbose: options.verbose,

package/dist/boat/prima/bin/prima-cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { knowledgeOption } from "../../../src/commands/options/index.js";
 import { createPrimaCommands } from "../src/cli.js";
 const program = createPrimaCommands('prima');
+knowledgeOption.register(program);
 program.parse();

package/dist/boat/prima/src/cli.js

@@ -106,6 +106,7 @@ function addCommonOptions(cmd) {
         .option('--ephemeral', 'Keep no state between runs; applies to config-free runs, where output goes to a temp directory')
         .option('--framework <name>', 'Not active yet: framework the reported code targets, codeceptjs or playwright')
         .option('--url <url>', 'Page to open when the session has no page yet')
+        .option('--spec <path>', 'Docbot application spec directory or index.md to read as page knowledge')
         .option('--endpoint <ep>', 'Websocket endpoint of a browser server to attach to, skipping discovery')
         .option('--pw-session <title>', 'Title of the playwright-cli session to attach to')
         .addHelpText('after', `\n${sessionHelp}`);
@@ -118,6 +119,8 @@ function primaFor(options) {
         process.env.EXPLORBOT_AI_MODEL = options.model;
     if (options.visionModel)
         process.env.EXPLORBOT_VISION_MODEL = options.visionModel;
+    if (options.spec)
+        process.env.EXPLORBOT_SPEC = options.spec;
     return new Prima(buildOptions(options));
 }
 async function runPrima(options, command, run) {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/dist/rules/planner/styles/normal.md

@@ -1,7 +1,7 @@
 Study the page and figure out its business purpose. What is this page FOR? What would a user come here to do?
 
 Based on the page type, propose tests for COMPLETE user workflows:
-- If this is a data page (lists, tables): test CRUD operations end-to-end (create item → verify in list, edit item → verify changes saved, delete item → verify removed)
+- If this is a data page (lists, tables): test create, edit and delete as separate tests, each preparing the item it acts on
 - If the page has inputs to fill in: test the full commit flow, not just that the controls render
 - If this has filters and search: test filtering AND verify results change, not just "filter tab clicked"
 - If this has modals/dropdowns: test the ACTION inside them, not just opening/closing them

package/dist/src/ai/captain.js

@@ -137,7 +137,7 @@ export class Captain extends CaptainBase {
         const headingLines = formatHeadings(state);
         const headingsBlock = headingLines.join('\n');
         let pageSummary = '';
-        const cachedResearch = Researcher.getCachedResearch(state);
+        const cachedResearch = Researcher.getCachedResearch(actionResult);
         if (cachedResearch) {
             pageSummary = `<page_summary>\n${this.explorBot.agentResearcher().extractBrief(cachedResearch)}\n</page_summary>`;
         }

package/dist/src/ai/navigator.js

@@ -522,7 +522,7 @@ class Navigator {
             return null;
         }
         const currentActionResult = actionResult || ActionResult.fromState(state);
-        const research = Researcher.getCachedResearch(state) || '';
+        const research = Researcher.getCachedResearch(currentActionResult) || '';
         const combinedHtml = await currentActionResult.combinedHtml();
         const history = stateManager.getStateHistory();
         const visitCounts = new Map();

package/dist/src/ai/planner.js

@@ -96,11 +96,15 @@ export class Planner extends PlannerBase {
       Tests must be relevant to the page
       Tests must be achievable from UI
       Tests must be verifiable from UI
-      NEVER split one workflow into multiple tests. Each test must be a complete end-to-end flow.
+      One test verifies ONE business operation: the steps that reach it, the action itself, and its verification.
+      Steps that only reach the action — opening a form, expanding a panel, creating or locating the item to act on — belong to that test. A second operation with its own verification does not.
       Bad: "Open delete dropdown" + "Confirm deletion" — these are ONE test, not two.
       Bad: "Search for X" + "Verify search results" — searching and verifying is ONE test.
       Bad: "Leave field empty" + "Click submit" — that's one negative test, not two.
-      If two scenarios cannot run independently (one requires the other to run first), merge them into one.${featureDirective}${focusExistingDataDirective}
+      Bad: "Create a record, rename it, delete it" — three verified operations, so THREE tests, not one.
+      Good: "Rename existing record and verify the new title" — ONE test; creating is skipped, we assume record already exists, only the rename is verified.
+      You may rely on another test having run first in case we deal with empty state and no relevant data was created yet and we expect another our test creates it
+      When the page reports a record is missing or unavailable, it is not a testable surface — plan list-level or recovery behavior instead of operations on that record.${featureDirective}${focusExistingDataDirective}
     </task>
 
     ${customPrompt || ''}
@@ -166,9 +170,6 @@ export class Planner extends PlannerBase {
             if (!aiResult?.object?.scenarios) {
                 throw new Error('No tasks were created successfully');
             }
-            if (aiResult.object.scenarios.length === 0 && !this.currentPlan) {
-                throw new Error('No tasks were created successfully');
-            }
             const defaultStartUrl = this.getDefaultStartUrl(state);
             const fromPlanning = aiResult.object.scenarios.map((s) => new Test(s.scenario, s.priority, s.expectedOutcomes, s.startUrl || defaultStartUrl, s.steps || []));
             return { tests: fromPlanning, planName: aiResult.object.planName };
@@ -295,6 +296,7 @@ export class Planner extends PlannerBase {
       <task>
       Based on the page research, create ${this.MIN_TASKS}-${this.MAX_TASKS} exploratory testing scenarios.
       For each scenario provide specific steps and expected outcomes.
+      Exception: if the page reports the requested resource is missing, shows a failure state, or holds no content and no controls, return an empty scenarios list. Never invent tests for a page with nothing to exercise.
       </task>
 
       <rules>
@@ -308,13 +310,13 @@ export class Planner extends PlannerBase {
       Focus on error or success messages as outcome.
       Focus on URL page change or data persistency after page reload.
       If there are subpages (pages with same URL path) plan testing of those subpages as well
-      If you plan to test CRUD operations, plan them in correct order: create, read, update.
+      Plan CRUD operations in order: create, read, update, delete.
       Do not invent specific route names, success messages, validation texts, badge counts, or welcome messages unless they are visible in research, visited pages, or prior observed flows.
       When validation placement or wording was not observed, require feedback associated with the invalid input without inventing a specific location or message.
       If exact wording is unknown, describe the expected result generically, for example "an authentication error is shown" or "the user stays on the login page" instead of guessing the literal text.
       If exact redirect destination is unknown, describe the destination by visible page identity, for example "the dashboard page opens" or "the current workspace home page opens" instead of inventing a URL slug.
       Only propose scenarios whose prerequisites are evident from page research, visited pages, or API data preparation context.
-      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible or API preconditions can create it.
+      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible, API preconditions can create it, or the scenario itself creates the record as its setup.
       If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks write controls, prefer read-only scenarios such as opening panels, inspecting visible lists, filtering, searching, or verifying current state.
       Do not assume hidden data exists just because a control is present.
       For scenarios that act on existing items or search/filter by existing values, use only item names or values visible in research, visited pages, or prior observed flows.

package/dist/src/ai/researcher.js

@@ -53,6 +53,8 @@ export class Researcher extends ResearcherBase {
         throw new Error('not implemented');
     }
     static getCachedResearch(state) {
+        if (state instanceof ActionResult)
+            return getCachedResearch(state.baseHash);
         return getCachedResearch(ActionResult.fromState(state).baseHash);
     }
     getSystemMessage() {

package/dist/src/ai/rules.js

@@ -145,11 +145,11 @@ export const protectionRule = dedent `
 
   Pre-existing data on the page belongs to the application, not the test.
   Items that were not created inside the current test scenario must not be deleted, removed, emptied, reset, archived, or otherwise destroyed.
-  If a scenario needs to verify destructive behaviour, the same scenario must first create a disposable target and then destroy that specific target — never operate on data that was already there when the test started.
+  If a scenario needs to verify destructive behaviour, the same scenario must first create its own target and then destroy that specific target — never operate on data that was already there when the test started.
 
   The resource that the current page URL represents is "under test".
   The test must not destroy the resource it is running against — doing so invalidates every subsequent scenario that starts on the same URL.
-  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on disposable children created within the scenario itself.
+  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on children created within the scenario itself.
   </important>
 `;
 export const dataProtectionRules = dedent `
@@ -164,7 +164,7 @@ export const dataProtectionRules = dedent `
   filter, tab, or list-inspection constraint. Use visible existing data when it is available.
   If no suitable data exists, report the missing precondition instead of creating data.
 
-  Destructive actions are allowed only against disposable data created by the current scenario
+  Destructive actions are allowed only against data created by the current scenario
   or prepared for that scenario by Fisherman/API preconditions. Existing application data must
   remain unchanged.
   </data_protection_rules>

package/dist/src/api/spec-reader.js

@@ -5,7 +5,7 @@ import { dereference } from '@scalar/openapi-parser';
 import { tag } from "../utils/logger.js";
 export function validateSpecs(specs) {
     if (!specs?.length) {
-        throw new Error('API spec is required. Set api.spec in your config file.');
+        throw new Error('API spec is required. Pass --spec, set EXPLORBOT_API_SPEC, or set api.spec in your config file.');
     }
 }
 export async function loadSpec(specPaths, outputDir) {

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

@@ -32,7 +32,7 @@ export class ConfigCommand extends BaseCommand {
         const dirs = {};
         if (options.root) {
             for (const [name, dir] of Object.entries({ output: 'output', ...config.dirs })) {
-                dirs[name] = path.join(options.root, dir);
+                dirs[name] = path.resolve(options.root, dir);
             }
         }
         const env = {};

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

@@ -21,7 +21,7 @@ export class DrillCommand extends BaseCommand {
         });
     }
     parseKnowledgeArg(args) {
-        const match = args.match(/--knowledge\s+(\S+)/);
+        const match = args.match(/--save-knowledge\s+(\S+)/);
         return match ? match[1] : undefined;
     }
     parseMaxArg(args) {

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

@@ -256,9 +256,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));
@@ -297,6 +303,11 @@ export class ExploreCommand extends BaseCommand {
             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/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/config.d.ts

@@ -255,6 +255,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>;

package/dist/src/config.js

@@ -46,6 +46,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 +130,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 +271,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;

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()));

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