explorbot 0.5.9 → 0.6.0

package/src/ai/tools.ts

@@ -1,7 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
+import { ActionResult, type PageDiff } from '../action-result.ts';
 import type { ExecutedStep } from '../action.ts';
 import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
@@ -65,8 +65,8 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
           Never mix different elements — use separate click() calls instead.
           REQUIRED: include at least one command WITHOUT a container — a wrong or stale container always fails.
           Order by reliability:
-          1. I.click(text, container) - when the container is verified - e.g. I.click("Save", ".modal")
-          2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
+          1. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
+          2. I.click(text, container) - when the container is verified - e.g. I.click("Save", ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
@@ -292,7 +292,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
           const normalizedKey = key.toLowerCase();
           const matchingStandardKey = Array.from(standardKeys).find((sk) => sk.toLowerCase() === normalizedKey);
           const isStandardKey = !!matchingStandardKey;
-          const keyToUse = matchingStandardKey || key;
+          const keyToUse = KEY_ALIASES[matchingStandardKey || ''] || matchingStandardKey || key;
 
           if (!isSingleChar && !isStandardKey) {
             const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
@@ -480,7 +480,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
               commandsExecuted: lines.length,
               attempts: action.executedSteps,
               code: codeBlock,
-              suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
+              suggestion: 'Check the filled values with verify() before submitting, then submit with click().',
             },
             action
           );
@@ -678,7 +678,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
       inputSchema: z.object({
         reason: z.string().describe('Why do you need fresh context? Required to prevent overuse.'),
       }),
-      execute: async ({ reason }) => {
+      execute: async () => {
         try {
           const currentState = stateManager.getCurrentState();
 
@@ -760,6 +760,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
           }
 
           return failedToolResult('verify', `Verification failed: ${assertion}`, {
+            attempts: result.results.map(({ code, passed, error }) => ({ code, passed, error })),
             suggestion: 'The assertion could not be verified. Check if the condition is actually present on the page or try a different assertion.',
           });
         } catch (error) {
@@ -793,7 +794,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
       inputSchema: z.object({
         reason: z.string().describe('Why do you need research? What information is missing from existing context?'),
       }),
-      execute: async ({ reason }) => {
+      execute: async () => {
         try {
           const currentState = stateManager.getCurrentState();
 
@@ -907,7 +908,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
         element: z.string().describe('Visual description of element to click (e.g., "blue Submit button in the modal footer", "Settings gear icon in top right")'),
         context: z.string().describe('What you already tried and why it failed - helps with accurate identification'),
       }),
-      execute: async ({ element, context }) => {
+      execute: async ({ element }) => {
         if (Stats.visionDisabled) {
           return failedToolResult('visualClick', 'Vision tools are disabled for this session. Use xpathCheck() to find the element, then click() with the discovered locator.');
         }
@@ -1058,7 +1059,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
         xpath: z.string().describe('XPath expression — use broad patterns to avoid missing the element'),
         reason: z.string().describe('What element you are looking for and why'),
       }),
-      execute: async ({ xpath, reason }) => {
+      execute: async ({ xpath }) => {
         const currentState = stateManager.getCurrentState();
 
         if (!currentState) {
@@ -1202,6 +1203,7 @@ const ARIA_OUTPUT_CAP = 4000;
 const HTML_OUTPUT_CAP = 6000;
 const ANALYSIS_OUTPUT_CAP = 2000;
 const JUDGE_RECENT_ACTIONS_LIMIT = 8;
+const KEY_ALIASES: Record<string, string> = { Esc: 'Escape', Del: 'Delete' };
 
 function cap(text: string | undefined | null, max: number): string {
   if (!text) return '';

package/src/application-spec.ts

@@ -10,6 +10,7 @@ import { loadMarkdownFiles } from './utils/markdown-files.ts';
 export class ApplicationSpec {
   private pages: ApplicationSpecPage[] = [];
   readonly sourcePath: string;
+  private totalMarkdownFiles = 0;
 
   constructor(sourcePath: string) {
     this.sourcePath = this.resolveSourcePath(sourcePath);
@@ -38,28 +39,27 @@ export class ApplicationSpec {
     return this.pages.length;
   }
 
+  get markdownFileCount(): number {
+    return this.totalMarkdownFiles;
+  }
+
   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 allFiles = loadMarkdownFiles(bundlePath, { recursive: true });
     const indexPath = path.join(bundlePath, 'index.md');
-    if (!existsSync(indexPath)) {
-      throw new Error(`Application spec index not found: ${indexPath}`);
-    }
+    this.totalMarkdownFiles = allFiles.filter((file) => path.resolve(file.filePath) !== path.resolve(indexPath)).length;
 
-    const pagesPath = path.join(bundlePath, 'pages');
-    if (!existsSync(pagesPath)) {
-      throw new Error(`Application spec pages directory not found: ${pagesPath}`);
-    }
+    for (const file of allFiles) {
+      if (path.resolve(file.filePath) === path.resolve(indexPath)) continue;
+
+      if (!file.data.url && file.data.format === undefined && file.data.version === undefined) continue;
 
-    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}`);
@@ -73,8 +73,14 @@ export class ApplicationSpec {
       this.pages.push({ url: parsed.data.url, content: file.content.trim() });
     }
 
+    if (this.totalMarkdownFiles === 0) {
+      tag('warning').log(`No markdown files found in spec: ${bundlePath}`);
+      return;
+    }
+
     if (this.pages.length === 0) {
-      throw new Error(`Application spec contains no documented pages: ${pagesPath}`);
+      tag('debug').log(`${this.totalMarkdownFiles} spec files found in ${bundlePath}`);
+      return;
     }
   }
 

package/src/commands/clean-command.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { ConfigParser, outputPath } from '../config.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand, type Suggestion } from './base-command.js';

package/src/commands/context-command.ts

@@ -1,4 +1,3 @@
-import { ActionResult } from '../action-result.js';
 import { Researcher } from '../ai/researcher.js';
 import { visuallyAnnotateContainers } from '../ai/researcher/coordinates.js';
 import { outputPath } from '../config.js';

package/src/commands/context-experience-command.ts

@@ -9,7 +9,6 @@ export class ContextExperienceCommand extends BaseCommand {
   description = 'Print all matching experience for current page';
 
   async execute(_args: string): Promise<void> {
-    const explorer = this.explorBot.getExplorer();
     const state = this.explorBot.stateManager().getCurrentState();
 
     if (!state) {

package/src/commands/context-knowledge-command.ts

@@ -9,7 +9,6 @@ export class ContextKnowledgeCommand extends BaseCommand {
   description = 'Print all matching knowledge for current page';
 
   async execute(_args: string): Promise<void> {
-    const explorer = this.explorBot.getExplorer();
     const state = this.explorBot.stateManager().getCurrentState();
 
     if (!state) {

package/src/commands/explore-command.ts

@@ -6,7 +6,7 @@ import { Stats } from '../stats.js';
 import { type Plan, type Test, TestResult } from '../test-plan.js';
 import { browserErrorMessage } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
-import { ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
+import { BlockedError, ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
 import { keepSiteUrls, readSitemap } from '../utils/sitemap.ts';
@@ -14,6 +14,7 @@ import { parseSpecPairs } from '../utils/spec.ts';
 import { safeFilename } from '../utils/strings.ts';
 import { UrlFilter } from '../utils/url-filter.ts';
 import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
+import { PlanCommand } from './plan-command.js';
 
 const MAX_SUB_PAGE_ATTEMPTS = 30;
 const PRIORITY_ORDER: Record<string, number> = { critical: 0, important: 1, high: 2, normal: 3, low: 4 };
@@ -136,7 +137,7 @@ export class ExploreCommand extends BaseCommand {
   }
 
   private async runFreshMode(mainUrl: string | undefined, feature: string | undefined, styles?: string[]): Promise<void> {
-    await this.runAllStyles(mainUrl, feature, undefined, undefined, styles);
+    await this.runAllStyles(mainUrl, feature, undefined, styles);
     this.rememberCurrentPlan();
     const mainPlan = this.explorBot.getCurrentPlan();
     if (!mainPlan) return;
@@ -320,7 +321,7 @@ export class ExploreCommand extends BaseCommand {
       tag('warning').log(`Skipping page: ${errorPage.message}`);
       return false;
     }
-    await this.runAllStyles(url, feature, parentPlan, this.completedPlans, styles);
+    await this.runAllStyles(url, feature, parentPlan, styles);
     const plan = this.explorBot.getCurrentPlan();
     if (plan?.tests.length && !this.completedPlans.includes(plan)) {
       this.completedPlans.push(plan);
@@ -333,14 +334,14 @@ export class ExploreCommand extends BaseCommand {
     for (const style of styleList) {
       if (this.isLimitReached()) break;
       this.explorBot.setCurrentPlan(existingPlan);
-      const opts: { fresh: boolean; style: string; completedPlans?: Plan[]; noSave?: boolean } = { fresh: false, style, completedPlans: this.completedPlans };
+      const opts: { fresh: boolean; style: string; noSave?: boolean } = { fresh: false, style };
       if (this.dryRun) opts.noSave = true;
       await this.planWithRetry(feature, opts, pageUrl);
       await this.runPendingTests();
     }
   }
 
-  private async runAllStyles(pageUrl?: string, feature?: string, parentPlan?: Plan, completedPlans?: Plan[], styles?: string[]): Promise<void> {
+  private async runAllStyles(pageUrl?: string, feature?: string, parentPlan?: Plan, styles?: string[]): Promise<void> {
     const styleList = styles ?? Object.keys(getStyles());
     let fresh = true;
     for (const style of styleList) {
@@ -348,7 +349,7 @@ export class ExploreCommand extends BaseCommand {
       if (!fresh && pageUrl && !this.dryRun) {
         await this.explorBot.visit(pageUrl);
       }
-      const opts: { fresh: boolean; style: string; extend?: Plan; completedPlans?: Plan[]; noSave?: boolean } = { fresh, style, completedPlans };
+      const opts: { fresh: boolean; style: string; extend?: Plan; noSave?: boolean } = { fresh, style };
       if (fresh && parentPlan) opts.extend = parentPlan;
       if (this.dryRun) opts.noSave = true;
       await this.planWithRetry(feature, opts, pageUrl);
@@ -371,10 +372,14 @@ export class ExploreCommand extends BaseCommand {
     this.completedPlans.push(plan);
   }
 
-  private async planWithRetry(feature: string | undefined, opts: { fresh: boolean; style: string; extend?: Plan; completedPlans?: Plan[]; noSave?: boolean }, pageUrl?: string): Promise<void> {
+  private async planWithRetry(feature: string | undefined, opts: { fresh: boolean; style: string; extend?: Plan; noSave?: boolean }, pageUrl?: string): Promise<void> {
     const before = new Set(this.explorBot.getCurrentPlan()?.tests ?? []);
 
     await this.explorBot.plan(feature, opts);
+    if (this.explorBot.lastPlanError instanceof BlockedError) {
+      tag('warning').log(`Skipping page: ${this.explorBot.lastPlanError.message}`);
+      return;
+    }
     if (this.explorBot.lastPlanError) {
       if (this.explorBot.lastPlanError instanceof ErrorPageError) {
         throw this.explorBot.lastPlanError;
@@ -388,12 +393,15 @@ export class ExploreCommand extends BaseCommand {
       }
     }
 
-    const planAfter = this.explorBot.getCurrentPlan();
-    if (!planAfter) return;
-    const added = planAfter.tests.filter((t) => !before.has(t));
-    if (added.length === 0) return;
+    this.printAddedTests(before, opts.style, pageUrl);
+  }
+
+  private printAddedTests(before: Set<Test>, style: string, pageUrl?: string): number {
+    const added = this.explorBot.getCurrentPlan()?.tests.filter((t) => !before.has(t)) ?? [];
+    if (added.length === 0) return 0;
     const urlNote = pageUrl ? ` for ${pageUrl}` : '';
-    this.printPreview(`Planner added ${added.length} new test(s) [style=${opts.style}]${urlNote}:`, added);
+    this.printPreview(`Planner added ${added.length} new test(s) [style=${style}]${urlNote}:`, added);
+    return added.length;
   }
 
   private parseConfigure(raw: string | undefined): ConfigureSpec {
@@ -545,16 +553,7 @@ export class ExploreCommand extends BaseCommand {
     const sections: NextStepSection[] = [];
 
     if (savedPlanPath) {
-      const relPlan = relativeToCwd(savedPlanPath);
-      sections.push({
-        label: 'Plan',
-        path: savedPlanPath,
-        commands: [
-          { label: 'Re-run', command: `${cli} test ${relPlan} 1` },
-          { label: 'Run all', command: `${cli} test ${relPlan} *` },
-          { label: 'Run range', command: `${cli} test ${relPlan} 1-3` },
-        ],
-      });
+      sections.push(PlanCommand.planSection(savedPlanPath));
     }
 
     const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
@@ -594,6 +593,14 @@ export class ExploreCommand extends BaseCommand {
     printNextSteps(sections);
   }
 
+  private skipBlockedTest(test: Test, error: unknown): void {
+    if (!(error instanceof BlockedError)) throw error;
+    tag('warning').log(`Skipping test: ${error.message}`);
+    test.start();
+    test.addNote(error.message, TestResult.SKIPPED);
+    test.finish(TestResult.SKIPPED);
+  }
+
   private isLimitReached(): boolean {
     if (this.maxTests != null && this.testsRun >= this.maxTests) return true;
     return this.isDeadlineReached();
@@ -628,7 +635,13 @@ export class ExploreCommand extends BaseCommand {
       test.start();
       test.finish(TestResult.SKIPPED);
     } else {
-      await this.explorBot.agentTester().test(test, { deadline: this.hardDeadlineAt });
+      const run = () => this.explorBot.agentTester().test(test, { deadline: this.hardDeadlineAt });
+      await run()
+        .catch(async (err) => {
+          if (!(await this.explorBot.agentCaptain().resolveBlocker(err, () => this.explorBot.agentNavigator().isOn(test.startUrl)))) throw err;
+          return run();
+        })
+        .catch((err) => this.skipBlockedTest(test, err));
     }
     this.testsRun++;
   }

package/src/commands/help-json-command.ts

@@ -31,12 +31,14 @@ export class HelpJsonCommand {
         required: argument.required,
         variadic: argument.variadic,
       })),
-      options: helper.visibleOptions(cmd).map((option) => ({
-        flags: option.flags,
-        description: option.description,
-        default: option.defaultValue,
-        choices: option.argChoices,
-      })),
+      options: cmd.options
+        .filter((option) => !option.hidden)
+        .map((option) => ({
+          flags: option.flags,
+          description: option.description,
+          default: option.defaultValue,
+          choices: option.argChoices,
+        })),
       commands: helper.visibleCommands(cmd).map((sub) => HelpJsonCommand.data(sub)),
     };
 

package/src/commands/init-command.ts

@@ -327,6 +327,11 @@ function printInitNextSteps(options: { url?: string; siteCommands?: NextStepComm
 
   if (options.siteCommands) sections.push({ label: 'Explore any site', commands: options.siteCommands });
 
+  sections.push({
+    label: 'Log in for one run (kept in memory, never saved)',
+    commands: [{ command: `${cli} explore /dashboard --auth 'login: admin@example.com password: secret123'` }],
+  });
+
   sections.push(
     {
       label: 'Run it from VS Code',
@@ -338,11 +343,13 @@ function printInitNextSteps(options: { url?: string; siteCommands?: NextStepComm
     }
   );
 
+  sections.push({
+    label: 'Add knowledge (logins, credentials) — created on first use in ./knowledge',
+    commands: [{ command: `${cli} learn '*' 'to authorize use these credentials: admin@example.com / secret123'` }],
+  });
+
   printNextSteps(sections);
 
-  log('');
-  log('Add knowledge (logins, credentials) — created on first use in ./knowledge:');
-  tag('substep').log(chalk.yellow(`${cli} learn '*' 'to authorize use these credentials: admin@example.com / secret123'`));
   tag('substep').log('You can use ${env.LOGIN} and ${env.PASSWORD} to reference environment variables.');
 }
 

package/src/commands/learn-command.ts

@@ -13,7 +13,6 @@ export class LearnCommand extends BaseCommand {
 
     if (!note) {
       const AddKnowledge = (await import('../components/AddKnowledge.js')).default;
-      const explorer = this.explorBot.getExplorer();
       const state = this.explorBot.stateManager().getCurrentState();
       const initialUrl = state?.url || '';
 
@@ -32,7 +31,6 @@ export class LearnCommand extends BaseCommand {
       return;
     }
 
-    const explorer = this.explorBot.getExplorer();
     const state = this.explorBot.stateManager().getCurrentState();
 
     if (!state) {

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

@@ -0,0 +1,15 @@
+import { KnowledgeTracker } from '../../knowledge-tracker.js';
+import { registerSecret } from '../../utils/secrets.js';
+import { BaseOption } from './base-option.js';
+
+export class AuthOption extends BaseOption {
+  flags = '--auth <text>';
+  description = 'Auth details for this run only, not saved to disk, in free form (e.g. "login: admin password: secret" or "Bearer: <token>"). Falls back to EXPLORBOT_AUTH';
+
+  protected apply(options: Record<string, any>): void {
+    const auth = options.auth || process.env.EXPLORBOT_AUTH;
+    if (!auth) return;
+    registerSecret(auth);
+    KnowledgeTracker.appendSessionKnowledge(auth);
+  }
+}

package/src/commands/options/index.ts

@@ -1,9 +1,11 @@
+import { AuthOption } from './auth-option.js';
 import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 
 export { BaseOption } from './base-option.js';
 
+export const authOption = new AuthOption();
 export const decisionModelOption = new DecisionModelOption();
 export const knowledgeOption = new KnowledgeOption();
 export const wsOption = new WsOption();

package/src/commands/plan-command.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
 import figureSet from 'figures';
@@ -17,8 +18,12 @@ export class PlanCommand extends BaseCommand {
   options = [
     { flags: '--fresh', description: 'Regenerate plan from scratch' },
     { flags: '--clear', description: 'Clear plan before regenerating' },
+    { flags: '--append', description: 'Add tests to existing plan file' },
     { flags: '--style <name>', description: 'Planning style (normal, curious, psycho, performer)' },
     { flags: '--focus <feature>', description: 'Focus area for test planning' },
+    { flags: '--tests <count>', description: 'Exact number of tests to generate' },
+    { flags: '--min-tests <count>', description: 'Minimum number of tests to generate' },
+    { flags: '--max-tests <count>', description: 'Maximum number of tests to generate' },
   ];
 
   async execute(args: string): Promise<void> {
@@ -30,11 +35,20 @@ export class PlanCommand extends BaseCommand {
       tag('success').log('Plan cleared');
     }
 
+    if (opts.append) {
+      const existingPlanPath = path.join(this.explorBot.getPlansDir(), this.explorBot.generatePlanFilename());
+      if (existsSync(existingPlanPath)) this.explorBot.loadPlan(existingPlanPath);
+    }
+
     if (focus) {
       tag('info').log(`Planning focus: ${focus}`);
     }
 
-    await this.explorBot.plan(focus, { fresh: !!(opts.fresh || opts.clear), style: opts.style as string });
+    const testsCount = opts.tests ? Number.parseInt(opts.tests as string, 10) : undefined;
+    const minTests = testsCount ?? (opts.minTests ? Number.parseInt(opts.minTests as string, 10) : undefined);
+    const maxTests = testsCount ?? (opts.maxTests ? Number.parseInt(opts.maxTests as string, 10) : undefined);
+
+    await this.explorBot.plan(focus, { fresh: !!(opts.fresh || opts.clear), style: opts.style as string, minTests, maxTests });
 
     const plan = this.explorBot.getCurrentPlan();
     if (!plan?.tests.length) {
@@ -46,29 +60,34 @@ export class PlanCommand extends BaseCommand {
     this.printNextSteps();
   }
 
+  static planSection(planPath: string, cliSuffix = ''): NextStepSection {
+    const cli = getCliName();
+    const planName = path.basename(planPath, '.md');
+    return {
+      label: 'Plan',
+      path: planPath,
+      commands: [
+        { label: 'Run all tests', command: `${cli} test ${planName}${cliSuffix}` },
+        { label: 'Run one test', command: `${cli} test ${planName} 1${cliSuffix}` },
+        { label: 'Run a range', command: `${cli} test ${planName} 1-3${cliSuffix}` },
+      ],
+    };
+  }
+
   private printNextSteps(): void {
     const savedPath = this.explorBot.lastSavedPlanPath;
     if (!savedPath) return;
 
     const cli = getCliName();
-    const relPlan = relativeToCwd(savedPath);
-    const sections: NextStepSection[] = [
-      {
-        label: 'Plan',
-        path: savedPath,
-        commands: [
-          { label: 'Re-run', command: `${cli} test ${relPlan} 1` },
-          { label: 'Run all', command: `${cli} test ${relPlan} *` },
-          { label: 'Run range', command: `${cli} test ${relPlan} 1-3` },
-          { label: 'Reload', command: `/plan:load ${relPlan}` },
-        ],
-      },
-    ];
+    const cliSuffix = this.cliSuffix();
+    const section = PlanCommand.planSection(savedPath, cliSuffix);
+    section.commands?.push({ label: 'Reload', command: `/plan:load ${path.basename(savedPath, '.md')}` });
+    const sections: NextStepSection[] = [section];
 
     const suite = this.explorBot.getSuite();
     const files = suite && suite.automatedTestCount > 0 ? suite.getAutomatedTestFiles() : [];
     if (files.length > 0) {
-      const commands = files.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
+      const commands = files.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}${cliSuffix}` }));
       sections.push({
         label: `Automated tests (${files.length})`,
         commands,
@@ -78,6 +97,14 @@ export class PlanCommand extends BaseCommand {
     printNextSteps(sections);
   }
 
+  private cliSuffix(): string {
+    const options = this.explorBot.getOptions();
+    let suffix = '';
+    if (options.path) suffix += ` --path ${options.path}`;
+    if (options.session) suffix += ' --session';
+    return suffix;
+  }
+
   private printPlanSummary(): void {
     const suite = this.explorBot.getSuite();
     const plan = this.explorBot.getCurrentPlan();
@@ -91,10 +118,10 @@ export class PlanCommand extends BaseCommand {
     }
 
     if (plan?.tests.length) {
-      console.log(`\n${chalk.bold.cyan(`New test scenarios (${plan.tests.length})`)}`);
+      console.log(`\n${chalk.bold.cyan(`New test scenarios (${plan.tests.length})`)}\n`);
       for (let i = 0; i < plan.tests.length; i++) {
         const t = plan.tests[i];
-        console.log(`  ${chalk.dim(`${i + 1}.`)} ${chalk.green(figureSet.pointer)} ${t.scenario} ${chalk.dim(`[${t.priority}]`)}`);
+        console.log(`  ${chalk.cyan(`${i + 1}.`)} ${t.scenario}`);
       }
     }
   }

package/src/commands/plan-save-command.ts

@@ -1,5 +1,6 @@
-import { getCliName } from '../utils/cli-name.ts';
-import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
+import path from 'node:path';
+import { printNextSteps } from '../utils/next-steps.ts';
+import { PlanCommand } from './plan-command.js';
 import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class PlanSaveCommand extends BaseCommand {
@@ -17,20 +18,8 @@ export class PlanSaveCommand extends BaseCommand {
     const savedPath = this.explorBot.savePlan(filename);
     if (!savedPath) return;
 
-    const cli = getCliName();
-    const relPlan = relativeToCwd(savedPath);
-    const sections: NextStepSection[] = [
-      {
-        label: 'Plan',
-        path: savedPath,
-        commands: [
-          { label: 'Re-run', command: `${cli} test ${relPlan} 1` },
-          { label: 'Run all', command: `${cli} test ${relPlan} *` },
-          { label: 'Run range', command: `${cli} test ${relPlan} 1-3` },
-          { label: 'Reload', command: `/plan:load ${relPlan}` },
-        ],
-      },
-    ];
-    printNextSteps(sections);
+    const section = PlanCommand.planSection(savedPath);
+    section.commands?.push({ label: 'Reload', command: `/plan:load ${path.basename(savedPath, '.md')}` });
+    printNextSteps([section]);
   }
 }

package/src/commands/plans-command.ts

@@ -52,7 +52,7 @@ export class PlansCommand extends BaseCommand {
     }
     tag('info').log('');
     tag('info').log('Run test from this plan as:');
-    tag('info').log(`${getCliName()} test 1 --from-plan ${file.name}`);
+    tag('info').log(`${getCliName()} test ${file.name} 1`);
   }
 
   private resolvePlanFile(target: string, files: PlanFile[]): { plan: Plan; file: PlanFile } {

package/src/commands/test-command.ts

@@ -1,5 +1,6 @@
 import { Stats } from '../stats.js';
 import { Plan, Test } from '../test-plan.js';
+import { BlockedError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
 
@@ -18,6 +19,11 @@ export class TestCommand extends BaseCommand {
       this.explorBot.loadPlan(String(opts.fromPlan));
     }
 
+    if (!opts.fromPlan && remaining[0] && Plan.resolveFile(remaining[0], this.explorBot.getPlansDir())) {
+      this.explorBot.loadPlan(remaining.shift()!);
+      if (remaining.length === 0) remaining.push('*');
+    }
+
     const plan = this.explorBot.getCurrentPlan();
     const selector = remaining.join(' ');
     Stats.mode = 'test';
@@ -71,13 +77,16 @@ export class TestCommand extends BaseCommand {
     const tester = this.explorBot.agentTester();
     for (const [index, test] of toExecute.entries()) {
       tag('info').log(`Starting test ${index + 1}/${toExecute.length}: ${test.scenario}`);
-      await tester.test(test);
+      await tester.test(test).catch((err) => {
+        if (!(err instanceof BlockedError)) throw err;
+        tag('warning').log(`Skipping test: ${err.message}`);
+      });
     }
     tag('success').log('Test execution finished');
   }
 
   completeArguments(): ArgumentCompletion[] {
-    return Plan.listFiles(this.explorBot.getPlansDir()).map((file) => ({ value: `--from-plan ${file.name}`, display: file.label }));
+    return Plan.listFiles(this.explorBot.getPlansDir()).map((file) => ({ value: file.name, display: file.label }));
   }
 }