explorbot 0.5.7 → 0.5.9

package/src/ai/quartermaster.ts

@@ -1,36 +1,53 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import dedent from 'dedent';
+import type { Locator, Page } from 'playwright';
 import { z } from 'zod';
 import type { ActionResult } from '../action-result.ts';
 import { outputPath } from '../config.ts';
 import type Explorer from '../explorer.ts';
 import type { StateManager, StateTransition, WebPageState } from '../state-manager.ts';
 import type { Task } from '../test-plan.ts';
+import { ariaRefSelector, ariaRefSnapshot, parseAriaRefs } from '../utils/aria-ref.ts';
+import { compactAriaSnapshot } from '../utils/aria.ts';
 import { createDebug, tag } from '../utils/logger.ts';
+import { RulesLoader } from '../utils/rules-loader.ts';
 import { isCodeceptToolName } from '../utils/step-analyzer.ts';
+import { UX_FOCUS_ATTR, type UxMeasurements, countRunningAnimations, measureUx, renderUxMeasurements, uxProbeArgs } from '../utils/ux-probe.ts';
 import type { Conversation, ToolExecution } from './conversation.ts';
 import type { Provider } from './provider.ts';
 
 const debugLog = createDebug('explorbot:quartermaster');
 
+const UX_RULES = ['ux/accessibility', 'ux/interaction', 'ux/responsive', 'ux/navigation', 'ux/copy', 'ux/forms', 'ux/readability', 'ux/motion', 'ux/charts'];
+const UX_BREAKPOINTS = [768, 375];
+const UX_FOCUS_SELECTOR = `[${UX_FOCUS_ATTR}]`;
+const UX_SETTLE_MS = 400;
+const UX_ARIA_CAP = 8000;
+const UX_SCREENSHOT_TIMEOUT = 5000;
+const UX_MAX_FINDINGS = 6;
+const AGENT_NAME = 'quartermaster';
+const FOCUS_CONTAINER_ROLES = ['main', 'region', 'form', 'dialog', 'alertdialog', 'navigation', 'complementary', 'article', 'table', 'grid', 'tabpanel', 'list', 'group', 'banner', 'contentinfo', 'search'];
+
 export class Quartermaster {
   private provider: Provider;
   private model?: any;
   private outputDir: string;
   private pageAnalyses: Map<string, PageAnalysis> = new Map();
   private unsubscribe: (() => void) | null = null;
-  private explorer: Explorer | null = null;
+  private explorer: Explorer;
   private pendingAnalyses: Promise<void>[] = [];
 
-  constructor(provider: Provider, options?: { model?: any }) {
+  constructor(provider: Provider, explorer: Explorer, options?: { model?: any }) {
     this.provider = provider;
+    this.explorer = explorer;
     this.model = options?.model;
 
     this.outputDir = outputPath('a11y');
   }
 
-  start(explorer: Explorer, stateManager: StateManager): void {
-    this.explorer = explorer;
+  start(stateManager: StateManager): void {
+    if (this.unsubscribe) return;
     mkdirSync(this.outputDir, { recursive: true });
 
     this.unsubscribe = stateManager.onStateChange((event) => {
@@ -61,26 +78,14 @@ export class Quartermaster {
   }
 
   private async runAxeAnalysis(state: WebPageState): Promise<void> {
-    const page = this.explorer?.page;
+    const page = this.explorer.page;
     if (!page || !state.hash) {
       debugLog('No page available for axe analysis');
       return;
     }
 
     try {
-      const { AxeBuilder } = await import('@axe-core/playwright');
-      const results = await new AxeBuilder({ page }).analyze();
-
-      const violations: AxeViolation[] = results.violations.map((v) => ({
-        id: v.id,
-        impact: v.impact as AxeViolation['impact'],
-        description: v.description,
-        helpUrl: v.helpUrl,
-        nodes: v.nodes.map((n) => ({
-          html: n.html,
-          target: n.target as string[],
-        })),
-      }));
+      const violations = await this.axeViolations(page);
 
       this.pageAnalyses.set(state.hash, {
         url: state.url,
@@ -138,6 +143,24 @@ export class Quartermaster {
     }
   }
 
+  async auditUx(result: ActionResult, context: UxAuditContext): Promise<string> {
+    const focus = await this.markUxFocus(result, context);
+    tag('step').log(`Auditing UX of ${focus.area}`);
+
+    try {
+      const evidence = await this.explorer.withPage((page) => this.collectUxEvidence(page));
+      return await this.writeUxReport(result, focus, evidence, context);
+    } finally {
+      await this.explorer
+        .withPage((page) =>
+          page.evaluate((attr) => {
+            for (const el of Array.from(document.querySelectorAll(`[${attr}]`))) el.removeAttribute(attr);
+          }, UX_FOCUS_ATTR)
+        )
+        .catch(() => {});
+    }
+  }
+
   private async generateSemanticAnalysis(axeViolations: AxeViolation[], executions: ToolExecution[], initialState: ActionResult): Promise<SemanticIssue[]> {
     const failedExecs = executions.filter((e) => !e.wasSuccessful);
     if (failedExecs.length === 0 && axeViolations.length === 0) return [];
@@ -247,6 +270,265 @@ Focus on what would confuse a real user or caused the agent to make mistakes.`;
 
     return content;
   }
+
+  private async axeViolations(page: Page, include?: string): Promise<AxeViolation[]> {
+    const { AxeBuilder } = await import('@axe-core/playwright');
+    let builder = new AxeBuilder({ page });
+    if (include) builder = builder.include(include);
+    const results = await builder.analyze();
+
+    return results.violations.map((v) => ({
+      id: v.id,
+      impact: v.impact as AxeViolation['impact'],
+      description: v.description,
+      helpUrl: v.helpUrl,
+      nodes: v.nodes.map((n) => ({
+        html: n.html,
+        target: n.target as string[],
+      })),
+    }));
+  }
+
+  private async markUxFocus(result: ActionResult, context: UxAuditContext): Promise<UxFocus> {
+    const mark = (locator: Locator) =>
+      locator
+        .first()
+        .evaluate((el, attr) => el.setAttribute(attr, ''), UX_FOCUS_ATTR)
+        .then(() => true)
+        .catch(() => false);
+
+    const region = result.overlay;
+    const locateRegion = (page: Page) => {
+      if (region.root) return page.locator(region.root);
+      if (region.xpath) return page.locator(`xpath=${region.xpath}`);
+      const name = region.name || undefined;
+      return page.getByRole('dialog', { name }).or(page.getByRole('alertdialog', { name }));
+    };
+    const regionFocus = { area: region.name || `open ${region.type}`, reason: `it is the ${region.type} open on the page` };
+
+    if (!context.focus && region.isOpen && (await this.explorer.withPage((page) => mark(locateRegion(page))))) return regionFocus;
+
+    if (context.focus || context.commands.length) {
+      const picked = await this.pickUxFocus(context, mark);
+      if (picked) return picked;
+    }
+
+    if (region.isOpen && (await this.explorer.withPage((page) => mark(locateRegion(page))))) return regionFocus;
+
+    let reason = 'nothing narrower is open or was touched by the session on this page';
+    if (context.focus) reason = `"${context.focus}" matched no single container`;
+    return this.explorer.withPage(async (page) => {
+      if (await mark(page.locator('main, [role="main"]'))) return { area: 'main content', reason };
+      await mark(page.locator('body'));
+      return { area: 'whole page', reason: `${reason} and the page has no main landmark` };
+    });
+  }
+
+  private async pickUxFocus(context: UxAuditContext, mark: (locator: Locator) => Promise<boolean>): Promise<UxFocus | null> {
+    const snapshot = await this.explorer.withPage(ariaRefSnapshot).catch(() => '');
+    const candidates = parseAriaRefs(snapshot).filter((entry) => FOCUS_CONTAINER_ROLES.includes(entry.role));
+    if (!candidates.length) return null;
+
+    const hints: string[] = [];
+    if (context.focus) hints.push(`The developer asked to review: ${context.focus}`);
+    if (context.commands.length) hints.push('Commands the session ran on this page, latest last:', ...context.commands.map((command) => `- ${command}`));
+
+    const schema = z.object({
+      ref: z.enum(['none', ...candidates.map((entry) => entry.ref)]).describe('ref of the chosen container, or none'),
+      area: z.string().describe('the area named as a user would call it, a few words'),
+    });
+
+    const prompt = dedent`
+      Pick the page area a developer is working on, so a UX review covers it and nothing else.
+      Choose the smallest container that holds everything the hints point at.
+      Answer none when no listed container fits the hints.
+
+      <hints>
+      ${hints.join('\n')}
+      </hints>
+
+      <containers>
+      ${candidates.map((entry) => `- [${entry.ref}] ${entry.role} "${entry.name}"`).join('\n')}
+      </containers>
+
+      <page_aria>
+      ${snapshot.slice(0, UX_ARIA_CAP)}
+      </page_aria>
+    `;
+
+    const response = await this.provider.generateObject([{ role: 'user', content: prompt }], schema, this.model, { agentName: AGENT_NAME }).catch(() => null);
+    const ref = response?.object?.ref;
+    if (!ref || ref === 'none') return null;
+    if (!(await this.explorer.withPage((page) => mark(page.locator(ariaRefSelector(ref)))))) return null;
+
+    let reason = 'the session commands on this page act inside it';
+    if (context.focus) reason = `it holds "${context.focus}"`;
+    return { area: response.object.area, reason };
+  }
+
+  private async collectUxEvidence(page: Page): Promise<UxEvidence> {
+    const evidence: UxEvidence = { breakpoints: [], axe: [], notes: [] };
+    evidence.axe = await this.axeViolations(page, UX_FOCUS_SELECTOR).catch((error) => {
+      evidence.notes.push(`axe could not run: ${error.message}`);
+      return [];
+    });
+
+    const ignoredMotion = await this.animationsIgnoringReducedMotion(page);
+    if (ignoredMotion) evidence.notes.push(`${ignoredMotion} animations in the area keep running when reduced motion is requested`);
+
+    const width = await page.evaluate(() => window.innerWidth);
+    evidence.breakpoints.push(await this.captureUxBreakpoint(page));
+
+    const narrower = UX_BREAKPOINTS.filter((breakpoint) => breakpoint < width);
+    if (!narrower.length) return evidence;
+
+    const viewport = page.viewportSize();
+    if (!viewport) {
+      evidence.notes.push('the browser window has no fixed viewport, so narrower widths were not measured');
+      return evidence;
+    }
+
+    try {
+      for (const breakpoint of narrower) {
+        await page.setViewportSize({ width: breakpoint, height: viewport.height });
+        await page.waitForTimeout(UX_SETTLE_MS);
+        if ((await page.evaluate(() => window.innerWidth)) !== breakpoint) {
+          evidence.notes.push(`resizing to ${breakpoint}px had no effect, so that width was not measured`);
+          continue;
+        }
+        evidence.breakpoints.push(await this.captureUxBreakpoint(page));
+      }
+    } finally {
+      await page.setViewportSize(viewport);
+    }
+
+    return evidence;
+  }
+
+  private async animationsIgnoringReducedMotion(page: Page): Promise<number> {
+    if (!(await page.evaluate(countRunningAnimations, UX_FOCUS_SELECTOR))) return 0;
+
+    try {
+      await page.emulateMedia({ reducedMotion: 'reduce' });
+      await page.waitForTimeout(UX_SETTLE_MS);
+      return await page.evaluate(countRunningAnimations, UX_FOCUS_SELECTOR);
+    } finally {
+      await page.emulateMedia({ reducedMotion: null });
+    }
+  }
+
+  private async captureUxBreakpoint(page: Page): Promise<UxBreakpoint> {
+    const focus = page.locator(UX_FOCUS_SELECTOR).first();
+    const measurements = await page.evaluate(measureUx, uxProbeArgs(UX_FOCUS_SELECTOR));
+    const aria = await focus.ariaSnapshot().catch(() => '');
+
+    const breakpoint: UxBreakpoint = { measurements, aria: compactAriaSnapshot(aria, true).slice(0, UX_ARIA_CAP) };
+    if (!this.provider.hasVision()) return breakpoint;
+
+    const screenshot = await focus.screenshot({ timeout: UX_SCREENSHOT_TIMEOUT }).catch(() => null);
+    if (screenshot) breakpoint.screenshot = screenshot.toString('base64');
+    return breakpoint;
+  }
+
+  private async writeUxReport(result: ActionResult, focus: UxFocus, evidence: UxEvidence, context: UxAuditContext): Promise<string> {
+    const url = result.url || '';
+    const rules = [RulesLoader.loadRules(AGENT_NAME, UX_RULES, url), this.provider.getSystemPromptForAgent(AGENT_NAME, url)].filter(Boolean).join('\n\n');
+
+    const system = dedent`
+      <role>
+      You review the UX of one area of a web page a developer is building right now.
+      The report goes back to that developer, so every finding must point at something they can find in that area.
+      </role>
+
+      <focus>
+      Area under review: ${focus.area}, chosen because ${focus.reason}.
+      Report only on elements inside it. Page-wide header, navigation and footer are out of scope unless they are the area under review.
+      </focus>
+
+      <scope>
+      You see one page of one app, not the app.
+      - Report that a text fails and why. Never propose replacement wording, terminology, tone or language: the app's vocabulary is unknown to you.
+      - Never recommend colors, fonts, spacing values, design tokens or visual style: the project owns its design system.
+      - Sizes, gaps, overflow and contrast come only from <measurements> and <axe>. Never estimate them from a screenshot.
+      - Report only what the evidence shows. A check the evidence cannot settle is skipped, not guessed.
+      </scope>
+
+      <rules>
+      Each rule set carries the priority its findings are reported under.
+
+      ${rules}
+      </rules>
+
+      <output>
+      Markdown, no preamble.
+
+      ## Focus
+      One line: the area reviewed and the widths covered.
+
+      Then one section per priority that has findings, in this order: ## Critical, ## High, ## Medium, ## Low. Omit empty sections.
+      Each finding is one bullet of one sentence, at most 30 words:
+      - **<element as the user sees it>** (<rule set>, <width or "all widths">): <evidence>, <what it costs the user>.
+
+      One bullet per cause: elements failing the same check share a bullet naming at most three of them.
+      Write at most ${UX_MAX_FINDINGS} bullets in total across all sections, most severe first; drop the rest.
+      No fix wording, no rule ids, no list of skipped checks, no summary, no tables.
+      When nothing fails, write the Focus section and the line: No UX issues found in this area.
+      </output>
+    `;
+
+    const sections = [`<page url="${url}" title="${result.title || ''}"></page>`];
+    if (context.commands.length) sections.push(`<session_commands>\n${context.commands.join('\n')}\n</session_commands>`);
+    sections.push(`<axe>\n${evidence.axe.map((v) => `[${v.impact}] ${v.id}: ${v.description} — ${v.nodes[0]?.html.slice(0, 100) || ''}`).join('\n') || 'no violations'}\n</axe>`);
+    if (evidence.notes.length) sections.push(`<notes>\n${evidence.notes.join('\n')}\n</notes>`);
+    for (const breakpoint of evidence.breakpoints) {
+      const aria = breakpoint.aria || 'the area is not rendered at this width';
+      sections.push(`<breakpoint width="${breakpoint.measurements.width}">\n<measurements>\n${renderUxMeasurements(breakpoint.measurements)}\n</measurements>\n<aria>\n${aria}\n</aria>\n</breakpoint>`);
+    }
+
+    const shots = evidence.breakpoints.filter((breakpoint) => breakpoint.screenshot);
+    if (!shots.length) sections.push('No screenshots are attached: judge from ARIA and measurements only, and say in Focus that visual checks were not possible.');
+
+    const content: any[] = [{ type: 'text', text: sections.join('\n\n') }];
+    for (const shot of shots) {
+      content.push({ type: 'text', text: `Screenshot of the area at ${shot.measurements.width}px:` });
+      content.push({ type: 'file', mediaType: 'image/png', data: shot.screenshot });
+    }
+
+    let model = this.model || this.provider.getModelForAgent(AGENT_NAME);
+    if (shots.length) model = this.provider.getVisionModel();
+
+    const response = await this.provider.chat(
+      [
+        { role: 'system', content: system },
+        { role: 'user', content },
+      ],
+      model,
+      { agentName: AGENT_NAME }
+    );
+    return response.text;
+  }
+}
+
+export interface UxAuditContext {
+  focus?: string;
+  commands: string[];
+}
+
+interface UxFocus {
+  area: string;
+  reason: string;
+}
+
+interface UxBreakpoint {
+  measurements: UxMeasurements;
+  aria: string;
+  screenshot?: string;
+}
+
+interface UxEvidence {
+  breakpoints: UxBreakpoint[];
+  axe: AxeViolation[];
+  notes: string[];
 }
 
 interface AxeViolation {

package/src/ai/tester.ts

@@ -366,8 +366,9 @@ export class Tester extends TaskAgent implements Agent {
           }
 
           if (actionPerformed && !wasSuccessful) {
+            const noted = new Set(Object.values(task.notes).map((note) => note.message));
             result?.toolExecutions
-              ?.filter((execution: any) => !execution.wasSuccessful && execution.input?.explanation)
+              ?.filter((execution: any) => !execution.wasSuccessful && execution.input?.explanation && !noted.has(execution.input.explanation))
               .forEach((execution: any) => {
                 task.addNote(`Failed to ${execution.input.explanation} (${execution.toolName})`, TestResult.FAILED);
               });
@@ -379,8 +380,9 @@ export class Tester extends TaskAgent implements Agent {
           }
 
           if (assertionPerformed) {
-            const message = result?.toolExecutions?.find((execution: any) => execution.toolName === 'verify')?.output?.message || '';
-            task.addNote(message, wasSuccessful ? TestResult.PASSED : TestResult.FAILED);
+            const passedVerifications = result?.toolExecutions?.filter((execution: any) => this.ASSERTION_TOOLS.includes(execution.toolName) && execution.wasSuccessful) || [];
+            for (const execution of passedVerifications) task.addNote(execution.output?.message || '', TestResult.PASSED);
+            const message = passedVerifications.at(-1)?.output?.message || '';
             if (wasSuccessful) {
               conversation.addUserText(dedent`
                 Assertion "${message}" successfully passed!

package/src/commands/explore-command.ts

@@ -583,6 +583,14 @@ export class ExploreCommand extends BaseCommand {
       });
     }
 
+    sections.push({
+      label: 'Explore more',
+      commands: [
+        { label: 'Whole site', command: `${cli} explore /` },
+        { label: 'Docs', command: 'https://testomat.ai/docs/explorbot' },
+      ],
+    });
+
     printNextSteps(sections);
   }
 

package/src/commands/init-command.ts

@@ -1,25 +1,30 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
+import figureSet from 'figures';
 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';
-import { relativeToCwd } from '../utils/next-steps.ts';
+import { type NextStepCommand, type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
 
-function defaultConfigTemplate(provider: string): string {
+function defaultConfigTemplate(provider: string, url?: string): string {
+  const appUrl = url || 'http://<your-app-host-here>';
   return `// 'provider/model-id' uses a bundled provider.
 // It is also possible to import provider as a module from Vercel AI SDK.
-// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
+// https://testomat.ai/docs/explorbot
 
 const config = {
   web: {
     // use application host without path prefix (e.g., http://localhost:3000)
-    url: 'http://<your-app-host-here>',
+    url: '${appUrl}',
   },
 
   ai: {
-${modelLines(provider)}
+    // every role (model, visionModel, agenticModel) takes the recommended ${provider} models bundled with this version
+    // override a single role as 'provider/model-id':
+    // model: '${provider}/<model-id>',
+    recommendedModels: '${provider}',
   },
 
   reporter: {
@@ -37,8 +42,9 @@ export default config;
 }
 
 export function envTemplate(provider: string): string {
+  const { keyUrl } = PROVIDERS[provider];
   const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
-    if (name === provider) return `${envKey}=`;
+    if (name === provider) return `# Create a key at ${keyUrl} and paste it after '='\n${envKey}=`;
     return `# ${envKey}=`;
   });
 
@@ -69,10 +75,10 @@ export async function runInit(options: InitCommandOptions): Promise<void> {
   const choice = await renderInitWizard('choose');
   if (choice !== 'local') return;
 
-  const provider = await renderLocalProviderWizard();
-  if (!provider) return;
+  const setup = await renderLocalSetupWizard();
+  if (!setup) return;
 
-  runInitCommand({ ...options, provider });
+  runInitCommand({ ...options, ...setup });
 }
 
 export function writeGlobalConfig(provider: string, apiKey?: string): void {
@@ -82,24 +88,28 @@ export function writeGlobalConfig(provider: string, apiKey?: string): void {
 
   mkdirSync(globalDir(), { recursive: true });
   writeFileSync(globalConfigPath(), globalConfigTemplate(provider), 'utf8');
-  log(`Created global config: ${globalConfigPath()}`);
+  tag('success').log(`${figureSet.tick} Created global config: ${globalConfigPath()}`);
 
   const envKey = PROVIDERS[provider].envKey;
   writeEnvKey(envKey, apiKey || '');
-  log(`Stored ${envKey} in ${globalEnvPath()}`);
+  tag('success').log(`${figureSet.tick} Stored ${envKey} in ${globalEnvPath()}`);
 
   const missing = missingModelRoles(provider);
   if (missing.length) {
     tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${globalConfigPath()}`);
   }
   if (!apiKey && !process.env[envKey]) {
-    tag('warning').log(`Add your API key to ${globalEnvPath()}`);
+    printApiKeySteps(provider, globalEnvPath());
   }
 
   log('');
-  log('Explorbot now runs from any directory:');
-  tag('substep').log(chalk.yellow(`${getCliName()} explore https://your-app.example.com`));
-  tag('substep').log(chalk.yellow(`${getCliName()} sites`));
+  log(`${figureSet.star} What's next:`);
+  printInitNextSteps({
+    siteCommands: [
+      { label: 'Any site', command: `${getCliName()} explore https://your-app.example.com` },
+      { label: 'Saved sites', command: `${getCliName()} sites` },
+    ],
+  });
 }
 
 export function runInitCommand(options: InitCommandOptions): void {
@@ -141,38 +151,42 @@ export function runInitCommand(options: InitCommandOptions): void {
       process.exit(1);
     }
 
-    writeFileSync(outPath, defaultConfigTemplate(provider), 'utf8');
-    log(`Created config file: ${relativeToCwd(outPath)}`);
+    writeFileSync(outPath, defaultConfigTemplate(provider, options.url), 'utf8');
+    tag('success').log(`${figureSet.tick} Created config file: ${relativeToCwd(outPath)}`);
 
     const envPath = resolve(process.cwd(), '.env');
     if (!existsSync(envPath)) {
       writeFileSync(envPath, `${envTemplate(provider)}\n`, 'utf8');
-      log(`Created env file: ${relativeToCwd(envPath)}`);
+      tag('success').log(`${figureSet.tick} Created env file: ${relativeToCwd(envPath)}`);
     } else {
       log(`Env file already exists: ${relativeToCwd(envPath)}`);
     }
 
+    const envKey = PROVIDERS[provider].envKey;
+    if (options.apiKey) {
+      writeEnvKey(envKey, options.apiKey, envPath);
+      tag('success').log(`${figureSet.tick} Stored ${envKey} in ${relativeToCwd(envPath)}`);
+    }
+    if (!options.apiKey && !process.env[envKey]) {
+      printApiKeySteps(provider, relativeToCwd(envPath));
+    }
+    if (!options.url) {
+      tag('warning').log(`Set your application URL in web.url: ${relativeToCwd(outPath)}`);
+    }
+
     const missing = missingModelRoles(provider);
     if (missing.length) {
       tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
     }
 
-    log('');
-    log('Next steps:');
-    log('1. Configure AI provider in .env');
-    log('2. Set AI models config file');
-    log('3. Set web application URL in the config file');
-    log('4. Add initial knowledge (how to authorize to the application, etc.)');
-    tag('substep').log(chalk.yellow(`${getCliName()} 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.');
-
-    log('5. Launch application on a relative URL');
-    tag('substep').log(chalk.yellow(`${getCliName()} start /dashboard`));
-
     if (!existsSync('./output')) {
       mkdirSync('./output', { recursive: true });
-      log('Created directory: output');
+      tag('success').log(`${figureSet.tick} Created directory: output`);
     }
+
+    log('');
+    log(`${figureSet.star} What's next:`);
+    printInitNextSteps({ url: options.url });
   } catch (error) {
     log('Failed to create config file:', error);
     process.exit(1);
@@ -227,13 +241,13 @@ async function renderInitWizard(mode: 'choose' | 'global'): Promise<'local' | 'g
   });
 }
 
-async function renderLocalProviderWizard(): Promise<string | null> {
+async function renderLocalSetupWizard(): Promise<LocalSetup | null> {
   const [{ render }, React, InitWizard] = await Promise.all([import('ink'), import('react'), import('../components/InitWizard.js').then((m) => m.default)]);
 
   return new Promise((resolve) => {
-    const finish = (provider: string | null) => {
+    const finish = (setup: LocalSetup | null) => {
       unmount();
-      resolve(provider);
+      resolve(setup);
     };
     const { unmount } = render(
       React.createElement(InitWizard, {
@@ -242,7 +256,7 @@ async function renderLocalProviderWizard(): Promise<string | null> {
         onLocal: () => finish(null),
         onComplete: () => finish(null),
         onCancel: () => finish(null),
-        onLocalProvider: (provider: string) => finish(provider),
+        onLocalSetup: (setup) => finish(setup),
       }),
       { exitOnCtrlC: false, patchConsole: false }
     );
@@ -274,7 +288,7 @@ function globalConfigTemplate(provider: string): string {
 // Models are written as 'provider/model-id' so they resolve without a local node_modules.
 // The key is read from ${envKey} in ~/.explorbot/.env
 // Model ids are snapshotted from the recommendations of this Explorbot version.
-// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
+// https://testomat.ai/docs/explorbot
 const config = {
   ai: {
 ${modelLines(provider)}
@@ -292,8 +306,47 @@ export default config;
 `;
 }
 
-function writeEnvKey(key: string, value: string): void {
-  const envPath = globalEnvPath();
+function printInitNextSteps(options: { url?: string; siteCommands?: NextStepCommand[] }): void {
+  const cli = getCliName();
+  const sections: NextStepSection[] = [
+    {
+      label: 'Try the demo on a sample app',
+      commands: [{ command: `${cli} explore https://todomvc.com/examples/react/dist/` }],
+    },
+  ];
+
+  if (options.url) {
+    sections.push({
+      label: 'Explore your app',
+      commands: [
+        { label: 'Whole site', command: `${cli} explore ${options.url}` },
+        { label: 'One page', command: `${cli} explore /dashboard` },
+      ],
+    });
+  }
+
+  if (options.siteCommands) sections.push({ label: 'Explore any site', commands: options.siteCommands });
+
+  sections.push(
+    {
+      label: 'Run it from VS Code',
+      commands: [{ command: 'https://testomat.ai/explorbot' }],
+    },
+    {
+      label: 'Docs',
+      commands: [{ command: 'https://testomat.ai/docs/explorbot' }],
+    }
+  );
+
+  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.');
+}
+
+function writeEnvKey(key: string, value: string, envPath = globalEnvPath()): void {
   let content = '# AI provider API keys';
   if (existsSync(envPath)) content = readFileSync(envPath, 'utf8').trimEnd();
 
@@ -306,6 +359,19 @@ function writeEnvKey(key: string, value: string): void {
   writeFileSync(envPath, `${lines.join('\n').trimEnd()}\n`, 'utf8');
 }
 
+function printApiKeySteps(provider: string, envPath: string): void {
+  const { envKey, keyUrl } = PROVIDERS[provider];
+  tag('warning').log(`No API key yet — explorbot needs one to connect to ${provider}`);
+  tag('substep').log(`1. Create a key at ${keyUrl}`);
+  tag('substep').log(`2. Paste it into ${envPath}: ${envKey}=<your-key>`);
+}
+
+type LocalSetup = {
+  provider: string;
+  apiKey: string;
+  url: string;
+};
+
 type InitCommandOptions = {
   configPath?: string;
   force?: boolean;
@@ -313,4 +379,5 @@ type InitCommandOptions = {
   global?: boolean;
   provider?: string;
   apiKey?: string;
+  url?: string;
 };