explorbot 0.4.5 → 0.4.6

package/docs/superpowers/specs/2026-09-09-pagination-rule-design.md

@@ -0,0 +1,317 @@
+# Pagination rule: page numbers and infinite scroll
+
+## Problem
+
+Explorbot cannot reach list content that is not already loaded. A list shows a window onto
+a larger collection, and when the item under test is outside that window the tester concludes
+it is absent.
+
+Nothing in the repo scrolls anything. `<actions>` (`src/ai/rules.ts:307`) documents no scroll
+command, so the model has no way to know scrolling is available. Where scrolling is mentioned
+at all it is as a passing hint inside an unrelated suggestion string
+(`src/ai/tools.ts:875`, `:989`, `:1297`).
+
+Two strategies cover practically every paginated list on the web:
+
+- **Controls that replace the window** — next, previous, page numbers, load more.
+- **Appending on scroll** — new items are fetched and appended as the list is scrolled.
+
+The second is the hard one, because the scroller is often a container with its own scrollbar
+rather than the page. `I.scrollPageToBottom()` moves the window and leaves such a container
+untouched.
+
+## Approach
+
+Detection finds out which strategy a list uses; a rule tells the tester what to do about it,
+and is injected only when there is something to say. No new tool: the gesture already exists in
+CodeceptJS and is reachable through `form`.
+
+Splitting it that way is what keeps the rule short. The tester never has to discover anything
+at run time, and never carries guidance for a strategy this page does not use.
+
+### Why `I.scrollTo` is sufficient
+
+`Playwright.scrollTo(locator)` calls `el.scrollIntoViewIfNeeded()`
+(`node_modules/codeceptjs/lib/helper/Playwright.js:1679`), which scrolls **every scrollable
+ancestor** of the target. Pointing it at the last item currently in a list therefore scrolls
+that list's own scroller.
+
+Verified against Chromium on a page with both a scrollable `div` and a scrollable window:
+
+```
+before          {"box":0,    "win":0}
+scrollIntoView  {"box":2200, "win":1821}
+after cjs tail  {"box":2200, "win":1821}
+```
+
+Both scrollers moved. The `window.scrollBy` call CodeceptJS runs afterwards is a no-op: it
+passes one object to a two-positional-parameter function, so both deltas coerce to `NaN` and
+normalize to zero. Nothing needs to be worked around.
+
+The gesture is a single line beginning with `I.`, so it passes the `form` tool's line check
+(`src/ai/tools.ts:384`) and needs no new tool.
+
+### Signals already on the wire
+
+- **`pageDiff.ariaChanges` / `ariaChangeCount`** — `diffAriaSnapshots` (`src/utils/aria.ts:503`)
+  counts node summaries, so appended rows surface as counted additions.
+- **`pageDiff.requests`** — `Action.recordNetworkCall` (`src/action.ts:314`) captures same-origin
+  xhr/fetch as `{method, path, status}`, deduped. It stores `url.pathname` only, so the query
+  string is dropped: presence of a call, never a page number.
+
+## Design
+
+### A. Researcher determines each list's pagination strategy
+
+Four steps, cheapest first, stopping as soon as one answers. This is the escalation ladder from
+CLAUDE.md end to end: a table lookup, then AI judgment, then a probe whose result converts
+judgment back into a recorded fact.
+
+**0. Do the ARIA/HTML conventions name it? (deterministic, no research, no AI)**
+
+Some markup states the answer outright. These are spec-defined attributes and values, so this
+tier is a lookup, not a guess — and it is the only step that works when research has not run.
+
+| Marker | Means | Available in |
+|---|---|---|
+| `[aria-current="page"]` | current page of a pagination set | HTML only |
+| `a[rel="next"]`, `a[rel="prev"]` | sequential document relations | HTML only |
+| `[role="feed"]` | scrollable list that grows as it is scrolled | HTML and ARIA snapshot |
+| `[aria-setsize="-1"]` | total count unknown, so the set loads lazily | HTML only |
+
+The first two mean `controls`, the last two mean `infinite`.
+
+Verified against Chromium: `ariaSnapshot()` does **not** emit `aria-current`, so a link marked
+as the current page is indistinguishable from its neighbours in the ARIA path. Explorbot also
+dissolves `navigation` wrappers (`src/utils/aria.ts:46`, `:147`) and treats the role as
+template chrome (`src/utils/aria.ts:543`), so a `nav` labelled "Pagination" never reaches the
+model either. **These markers must be read from HTML.** `role="feed"` is the one exception —
+it survives as `- feed "…"` in the snapshot.
+
+Two constraints that keep this a lookup rather than a heuristic:
+
+- The value must be `aria-current="page"` exactly. `aria-current="true"` is what tabs and
+  breadcrumbs use and would over-match — confirmed in the same probe.
+- A `nav` whose `aria-label` reads "Pagination" is author prose, not closed grammar. It is not
+  part of this tier.
+
+**Absence proves nothing.** A pager built from plain buttons, and an infinite feed built from
+plain divs, carry none of these. That is what steps 1–3 are for.
+
+**1. Are there pagination controls? (AI, free)**
+
+Only asked when step 0 found nothing. Controls are named in open-ended ways — words, arrows,
+bare numbers — so this is AI judgment, not a pattern match. Researcher is already describing
+the section, so it costs nothing extra:
+a new `rules/researcher/pagination.md`, loaded alongside the existing three at
+`src/ai/researcher/sections.ts:81`, asks it to note when a section contains controls that move
+between pages of the same collection.
+
+If found, the section records `> Pagination: controls` and the remaining steps are skipped.
+
+**2. Can the section scroll at all? (deterministic gate)**
+
+Only asked when no controls were found. One `page.evaluate` per container:
+
+- `el.scrollHeight > el.clientHeight` → the container has its own scroller.
+- `el.getBoundingClientRect().bottom > innerHeight` → the list continues below the fold.
+- Neither → nothing more to do; no line recorded.
+
+This gate exists to keep step 3 from running on every short list.
+
+**3. Probe: does scrolling load more? (deterministic measurement)**
+
+Scroll the container to its end, wait for readiness (`waitForPageReadiness`,
+`src/utils/page-readiness.ts`), and compare. More descendant rows than before, or a same-origin
+xhr/fetch fired during the scroll, means the list appends. Record `> Pagination: infinite`.
+
+Then restore `scrollTop` to what it was, so screenshots, coordinates and later research see the
+page as they found it. Scroll position is not app state, so this needs none of the modal
+cleanup `_restorePageState` does in `deep-analysis.ts:453` — there is nothing to reuse there.
+
+**Recorded vocabulary:** `controls` or `infinite`, as a line in the section's container
+blockquote. Nothing is written when a list neither paginates nor grows, which is the common
+case and should stay silent.
+
+```
+> Container: '.semantic-container'
+> Pagination: infinite
+```
+
+**This line has a reader**, because section B injects the rule only when pagination was
+detected, and that decision is code. `extractPaginationFromBlockquote` joins
+`extractContainerFromBlockquote` (`src/ai/researcher/parser.ts:86`) and returns the recorded
+value or null.
+
+That makes `Pagination:` a closed vocabulary read deterministically by code, so the envelope
+checklist from CLAUDE.md applies and holds: read by code, scoped to a section of a state,
+optional with "absent" as the default, and written by one module.
+
+### A2. Where the code goes
+
+New `src/ai/researcher/pagination.ts` mixin, composed into `ResearcherBase`
+(`src/ai/researcher.ts:47`), owning steps 2 and 3. Step 1 is prompt text in
+`rules/researcher/pagination.md` and needs no code.
+
+It runs after `validateContainers` (`src/ai/researcher/locators.ts:268`), on containers that
+survived validation, so a probe never targets a selector already known to be broken.
+
+Not `deep-analysis.ts`: that mixin owns the same interact-measure-restore shape, but it is
+gated behind `deep` (`src/ai/researcher.ts:287`), and infinite scroll has to be detected on
+ordinary research runs too. It is also already 26k.
+
+Not `locators.ts`: that mixin owns locator validity, not list behaviour.
+
+**One writer for the blockquote.** `updateSectionContainer`
+(`src/ai/researcher/locators.ts:300`) currently owns that `blockquote[0]` replace. The
+pagination mixin must not write it independently. Extract the blockquote composition into one
+helper both call, so `Container:` and `Pagination:` are always emitted by the same code.
+
+A new `src/utils/pagination.ts` owns the two deterministic halves — the step 0 marker scan over
+HTML, and the in-page evaluate functions for steps 2 and 3, self-contained with no outer-scope
+references. One concern: how a list continues. `measureLayout` in `overlay.ts` is not reused:
+it is xpath-based and returns a modal-scoring `RegionLayout`, while sections carry CSS
+selectors and need neither.
+
+### B. The pagination rule, injected only when pagination was detected
+
+Not part of the static system message. A page with no list should not carry list guidance, and
+a page with page numbers should not be told how to scroll.
+
+**Seam:** `reinjectContextIfNeeded` (`src/ai/tester.ts:554`), which already injects per-state
+blocks conditionally — `focusedElementRule` when something is focused, an `<overlay>` block
+when a region is open. A `<pagination>` block joins them. Navigator gets the same block where
+it builds its own per-state context (`src/ai/navigator.ts:414`).
+
+**Condition:** the state shows pagination if step 0's markers are present in the current HTML,
+or `extractPaginationFromBlockquote` finds a recorded value for a section. Markers win when
+both are available, since they describe the page as it is now rather than as research left it.
+
+**Which text:** the strategy selects the fragment, so the model is never shown the other one.
+
+`paginationControlsRule`:
+
+```
+<pagination>
+This list pages through a larger collection. If what you need is not on screen,
+click next or the page number you need before concluding it is absent.
+</pagination>
+```
+
+`infiniteScrollRule`:
+
+```
+<pagination>
+This list grows as it is scrolled. If what you need is not on screen, scroll to
+the last item in the list — every scrollable ancestor of that item scrolls, so
+this reaches a list with its own scrollbar.
+
+New rows in the aria changes mean more arrived; a request with none means nothing
+was left. Stop on the first attempt that adds no rows: the end of a collection is
+an answer, not a failure.
+</pagination>
+```
+
+Both live in `src/ai/rules.ts` as exports. Not `rules/*.md`: those load per agent, and these
+have two consumers.
+
+**Reach narrows from the earlier draft.** Composing into `actionRule` would have reached
+Rerunner (`src/ai/rerunner.ts:450`) and Captain web-mode (`src/ai/captain/web-mode.ts:148`) too;
+conditional injection reaches only agents that build per-state context, which is Tester and
+Navigator. That is the cost of making it conditional, and it is the right trade: Rerunner heals
+known steps rather than traversing lists.
+
+Constraints both fragments keep: general phrasing, no selectors, no site names, no example
+taken from a debug session, one to three lines per bullet.
+
+### C. `actionRule` documents the gesture
+
+`<actions>` (`src/ai/rules.ts:307`) gains a scroll entry covering `I.scrollTo(<locator>)` —
+stating that it scrolls every scrollable ancestor of the target — and
+`I.scrollPageToBottom()` for the window. The `form` tool description
+(`src/ai/tools.ts:354`) gains "reach items further down a list" as a use case, since it
+currently reads as a typing tool.
+
+### D. Tool output that contradicts the rule
+
+Both are wrong reporting on existing tools, not new behaviour.
+
+**`src/ai/tools.ts:415`** — `hasObservablePageChange` (`src/ai/tools.ts:1236`) ignores
+`pageDiff.requests`. A scroll that fires a fetch which has not yet rendered rows, and a scroll
+at the true end of a list, both return `failedToolResult` carrying the suggestion "Treat the
+field/form action as not completed. Re-locate the editable control…" and commit
+`TestResult.FAILED` into the note. That note is read by final review and by Historian, so a
+correct end-of-list check is recorded as a failed test step.
+
+Fix: one line in `hasObservablePageChange` — `if (data.pageDiff.requests?.length) return true;`
+— and a no-change message that states what was observed rather than prescribing a
+form-specific recovery.
+
+**`src/ai/tools.ts:1208`** — `isMajorPageChange` (`src/ai/tools.ts:1220`) fires at
+`ariaChangeCount >= 50` with no URL change (`LARGE_ARIA_CHANGE_THRESHOLD`,
+`src/utils/aria.ts:581`), producing "MAJOR PAGE CHANGE. Page entered a different mode."
+`diffByCount` (`src/utils/aria.ts:309`) pushes one entry per surplus occurrence, so a batch of
+appended rows clears 50 easily. The rule says growth is the same state; the tool says the mode
+changed.
+
+Fix: a diff consisting of additions with no corresponding removals is growth, not a mode
+change. Mode changes churn — they remove as well as add.
+
+The added/removed split exists inside `diffAriaSnapshots` but is flattened into a single
+`count` before it reaches the check, so it has to be threaded through:
+
+1. `AriaDiff` (`src/utils/aria.ts:587`) gains `added: number; removed: number` — both arrays
+   are already computed at `src/utils/aria.ts:522`.
+2. `Diff` (`src/action-result.ts:650`) stores them alongside `_ariaChangeCount`, set where
+   `diffAriaSnapshots` is called (`src/action-result.ts:740`), and exposes them.
+3. `PageDiff` (`src/action-result.ts:46`) gains `ariaAdded` / `ariaRemoved`, populated next to
+   `ariaChanges` / `ariaChangeCount` (`src/action-result.ts:552`).
+4. `isMajorPageChange` then reads the split instead of the total.
+
+## Risks
+
+- **The probe costs a scroll per candidate section.** Steps 1 and 2 narrow it to sections that
+  have no pagination controls and can actually scroll, which on most pages is zero or one. If
+  it still proves too slow, the gate to tighten is step 2, not the probe itself.
+- **Region misclassification.** `OverlayPage.detectRegion` (`src/utils/overlay.ts:41`) accepts
+  in-flow added content that is `sizable` (≥5,000 chars, `src/utils/region.ts:99`), dominant
+  (≥70% of added raw size) and carries a name or root. A large appended batch in one list
+  container fits all three, which would fork the state hash with `region_<name>` and record a
+  transition. The probe can trigger this during research as well as the tester during a run.
+  Watch for it on the first real run; not changed here.
+- **Virtualized lists.** Recycled nodes keep counts flat, so the probe sees no growth and the
+  aria diff shows renames (`src/utils/aria.ts:325`) rather than additions. Such a list records
+  nothing and the rule will not know to scroll it. Out of scope.
+- **The stop condition lives only in the prompt.** No tool enforces it, so a model that keeps
+  scrolling past an attempt which added no rows will keep scrolling. Accepted: the tester's own
+  iteration cap is the only backstop.
+- **A REST call alone no longer stops the loop, by design.** After the D fix an empty-payload
+  200 counts as an observable change, so the tool reports success. The rule makes rows, not
+  calls, the evidence that more arrived — otherwise a list that answers every scroll with an
+  empty page would loop.
+
+## Testing
+
+- Unit coverage for step 0's marker scan: `aria-current="page"` and `rel=next/prev` yield
+  `controls`; `role="feed"` and `aria-setsize="-1"` yield `infinite`; `aria-current="true"` on a
+  tab list yields nothing.
+- `tests/integration/researcher-sections.test.ts` — `> Pagination: controls` appears for a
+  section whose UI map holds next/prev controls, and step 1 is not asked when step 0 already
+  answered.
+- A browser test for steps 2 and 3, following `tests/integration/overlay-modal-browser.test.ts`:
+  a container with its own scroller that appends on scroll (`infinite`), one that does not
+  (silent), a list with pagination controls (`controls`, no probe runs), and confirmation that
+  `scrollTop` is restored afterwards.
+- An aimock prompt-inspection test that the matching fragment reaches the tester on a paginated
+  state, the other fragment does not, and neither appears on a state with no list, per
+  `docs/contributing/ai-integration-tests.md`.
+- Unit coverage for the two `tools.ts` corrections: requests-only diff counts as observable;
+  an additions-only diff over the threshold is not a major page change.
+
+## Out of scope
+
+- Any new tool. The gesture is reachable through `form` today.
+- Persisting the strategy across runs. Research recomputes it, and the research cache is
+  session-scoped.
+- Virtualized list support.
+- Changing `detectRegion` thresholds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -101,7 +101,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "4.0.0-rc.16",
+    "codeceptjs": "4.2.0-beta.2",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",
@@ -123,8 +123,8 @@
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.62",
-    "playwright-core": "^1.62",
+    "playwright": "^1.63",
+    "playwright-core": "^1.63",
     "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",

package/src/ai/researcher/deep-analysis.ts

@@ -116,7 +116,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       );
 
       tag('substep').log(`Researching overlay: ${region.name}`);
-      const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
+      const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded, region.root);
       if (!sectionMarkdown) {
         debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
         return null;
@@ -421,9 +421,9 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       await new Promise((r) => setTimeout(r, 500));
 
       let diff: Diff;
+      let currAR: ActionResult;
       try {
-        await this.explorer.capture();
-        const currAR = ActionResult.fromState(this.stateManager.getCurrentState()!);
+        currAR = await this.explorer.capture();
         diff = await currAR.diff(previousState);
       } catch (err) {
         tag('warning').log(`State capture failed after click: ${err instanceof Error ? err.message : err}`);
@@ -444,7 +444,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
         return { status: 'none', code: clickCode };
       }
 
-      const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded);
+      const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded, currAR.overlay.root);
       await this._restorePageState(state.url, originalAria);
       if (!sectionMarkdown) return { status: 'none', code: clickCode };
       return { status: 'revealed', code: clickCode, sectionMarkdown };
@@ -467,7 +467,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       }
     }
 
-    private async _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[]): Promise<string | null> {
+    private async _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[], containerCss: string | null = null): Promise<string | null> {
       const alreadyHint = alreadyExpanded.length > 0 ? `\nAlready expanded sections:\n${alreadyExpanded.join('\n')}` : '';
 
       let intro: string;
@@ -532,7 +532,14 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       const sections = parseResearchSections(text);
       if (sections.length === 0) return null;
 
-      return sections[0].rawMarkdown;
+      const sectionMarkdown = sections[0].rawMarkdown;
+      if (!containerCss) return sectionMarkdown;
+
+      let heading = mdq(sectionMarkdown).query('h3[0]');
+      if (heading.count() === 0) heading = mdq(sectionMarkdown).query('h2[0]');
+      if (heading.count() === 0) return sectionMarkdown;
+
+      return heading.replace(`${heading.text().trimEnd()}\n\n> Container: '${containerCss}'\n\n`);
     }
 
     private _deduplicateExpandedSections(sections: string[]): string[] {

package/src/ai/tools.ts

@@ -1,18 +1,18 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import type { ExecutedStep } from '../action.ts';
 import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
+import type { ExecutedStep } from '../action.ts';
 import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
 import { type Task, TestResult } from '../test-plan.js';
+import { ariaRefSelector, describeRef, refIsGone } from '../utils/aria-ref.ts';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { cleanHtmlSnippet } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { pause } from '../utils/loop.js';
-import { ariaRefSelector, describeRef, refIsGone } from '../utils/aria-ref.ts';
+import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
@@ -133,7 +133,13 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
             }
 
             await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-            return successToolResult('click', { ...toolResult, attempts, code: command }, action);
+            const data: Record<string, any> = { ...toolResult, attempts, code: command };
+            const notExecuted = commands.slice(i + 1);
+            if (notExecuted.length) {
+              data.notExecuted = notExecuted;
+              data.suggestion = `SKIPPED: ${notExecuted.join('; ')}`;
+            }
+            return successToolResult('click', data, action);
           }
         }
 
@@ -1265,7 +1271,7 @@ export async function failedToolResult(action: string, message: string, data?: R
   const errorTexts = [message, ...(data?.attempts?.map((a: any) => a.error || '') || [])];
   if (errorTexts.some((t: string) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
     const matched = await extractWebElements(error);
-    result.suggestion = getMultipleElementsSuggestion(matched);
+    result.suggestion = getMultipleElementsSuggestion();
     result.multipleElementsDetected = true;
     result.elements = formatElementList(matched);
     return result;
@@ -1280,16 +1286,12 @@ export async function failedToolResult(action: string, message: string, data?: R
   return result;
 }
 
-function getMultipleElementsSuggestion(matched: MatchedElement[] | null): string {
-  const visible = (matched || []).filter((element) => element.visible !== false);
-  let onlyVisible = '';
-  if (matched && visible.length === 1) onlyVisible = `\nOnly element ${matched.indexOf(visible[0]) + 1} is on screen, so that is the one to act on.`;
-
+function getMultipleElementsSuggestion(): string {
   return dedent`
     Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
     Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
-    A match reported as not visible can never be acted on — pick one that is.${onlyVisible}
+    A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
@@ -1365,6 +1367,8 @@ function formatElementList(matched: MatchedElement[] | null): string {
     .map((el, i) => {
       const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
       if (el.visible !== undefined) lines.push(`Visible: ${el.visible}`);
+      const wrapped = matched.map((_, j) => j).filter((j) => j !== i && matched[j].xpath.startsWith(`${el.xpath}/`));
+      if (wrapped.length) lines.push(`Wraps: element ${wrapped.map((j) => j + 1).join(', ')}`);
       lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
       return lines.join('\n');
     })

package/src/api/spec-reader.ts

@@ -51,7 +51,7 @@ export function extractEndpointDefinition(schema: any, endpoint: string, baseEnd
   }
 
   const basePath = toBasePath(baseEndpoint);
-  const matched = collectMatchingPaths(schema, basePath, (normalized) => matchesEndpoint(normalized, endpoint));
+  const matched = collectEndpointPaths(schema, basePath, endpoint);
 
   if (!Object.keys(matched).length) {
     const available = listNormalizedPaths(schema, basePath);
@@ -61,6 +61,35 @@ export function extractEndpointDefinition(schema: any, endpoint: string, baseEnd
   return safeStringify(matched);
 }
 
+export function resolveEndpoints(schema: any, pattern: string, baseEndpoint?: string): string[] {
+  if (!schema?.paths) {
+    throw new Error('OpenAPI spec has no paths defined');
+  }
+
+  const basePath = toBasePath(baseEndpoint);
+  const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+  const matched = normalized.filter((specPath) => matchesPattern(specPath, pattern));
+
+  if (!matched.length) {
+    throw new Error(`Endpoint "${pattern}" not found in spec. Available: ${listNormalizedPaths(schema, basePath)}`);
+  }
+
+  const roots = matched.map((specPath) => toCollection(specPath, normalized, pattern));
+  const resolved = [...new Set(roots.map((root) => fillParameters(root, pattern)))];
+  const endpoints = resolved.filter((specPath) => !specPath.includes('{'));
+
+  if (!endpoints.length) {
+    throw new Error(`Endpoint "${pattern}" leaves ${listParameters(resolved)} unresolved. Give the value in the endpoint or in the base endpoint.`);
+  }
+
+  const skipped = resolved.filter((specPath) => specPath.includes('{'));
+  if (skipped.length) {
+    tag('warning').log(`Skipped, no value for their parameters: ${skipped.join(', ')}`);
+  }
+
+  return endpoints;
+}
+
 export function searchEndpoints(schema: any, query: string, baseEndpoint?: string): string {
   if (!schema?.paths) return 'No endpoints available';
 
@@ -166,6 +195,82 @@ function stripBasePath(specPath: string, basePath: string): string {
   return `/${specSegments.slice(i).join('/')}`;
 }
 
+function collectEndpointPaths(schema: any, basePath: string, endpoint: string): Record<string, any> {
+  const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+  const roots = resolveEndpoint(normalized, endpoint);
+
+  if (!roots.length) return collectMatchingPaths(schema, basePath, (path) => matchesEndpoint(path, endpoint));
+
+  return collectMatchingPaths(schema, basePath, (path) => roots.some((root) => path === root || path.startsWith(`${root}/`)));
+}
+
+function resolveEndpoint(specPaths: string[], endpoint: string): string[] {
+  const wanted = toSegments(endpoint);
+  if (!wanted.length) return [];
+
+  const matched = specPaths.filter((specPath) => {
+    const segments = toSegments(specPath);
+    if (segments.length !== wanted.length) return false;
+    return segmentsMatch(segments, wanted);
+  });
+
+  const literals = matched.map((specPath) => toSegments(specPath).filter((segment, i) => segment === wanted[i]).length);
+  const best = Math.max(0, ...literals);
+  return matched.filter((_, i) => literals[i] === best);
+}
+
+function matchesPattern(specPath: string, pattern: string): boolean {
+  const wanted = toSegments(pattern);
+  const segments = toSegments(specPath);
+  if (segments.length < wanted.length) return false;
+  return segmentsMatch(segments, wanted);
+}
+
+function segmentsMatch(segments: string[], wanted: string[]): boolean {
+  return wanted.every((want, i) => want === '*' || segments[i] === want || segments[i].startsWith('{'));
+}
+
+function toCollection(specPath: string, specPaths: string[], pattern: string): string {
+  const segments = toSegments(specPath);
+  const filled = toSegments(fillParameters(specPath, pattern));
+
+  let deepest = segments.length;
+  const unfilled = filled.findIndex((segment) => segment.startsWith('{'));
+  if (unfilled >= 0) deepest = unfilled;
+
+  for (let i = Math.max(1, Math.min(toSegments(pattern).length, deepest)); i <= deepest; i++) {
+    const prefix = `/${segments.slice(0, i).join('/')}`;
+    if (specPaths.includes(prefix)) return prefix;
+  }
+
+  return specPath;
+}
+
+function fillParameters(specPath: string, pattern: string): string {
+  const wanted = toSegments(pattern);
+  const segments = toSegments(specPath);
+  for (let i = 0; i < wanted.length && i < segments.length; i++) {
+    if (wanted[i] === '*') continue;
+    if (!segments[i].startsWith('{')) continue;
+    segments[i] = wanted[i];
+  }
+  return `/${segments.join('/')}`;
+}
+
+function listParameters(specPaths: string[]): string {
+  const found = new Set<string>();
+  for (const specPath of specPaths) {
+    for (const segment of toSegments(specPath)) {
+      if (segment.startsWith('{')) found.add(segment);
+    }
+  }
+  return [...found].join(', ');
+}
+
+function toSegments(path: string): string[] {
+  return path.split('/').filter(Boolean);
+}
+
 function matchesEndpoint(specPath: string, endpoint: string): boolean {
   if (specPath === endpoint) return true;
   if (specPath.startsWith(`${endpoint}/`)) return true;

package/src/commands/base-command.ts

@@ -15,7 +15,7 @@ export interface Suggestion {
   hint: string;
 }
 
-export abstract class BaseCommand {
+export abstract class BaseCommand<T = ExplorBot> {
   abstract name: string;
   abstract description: string;
   aliases: string[] = [];
@@ -23,9 +23,9 @@ export abstract class BaseCommand {
   tuiEnabled = true;
   suggestions: Suggestion[] = [];
 
-  protected explorBot: ExplorBot;
+  protected explorBot: T;
 
-  constructor(explorBot: ExplorBot) {
+  constructor(explorBot: T) {
     this.explorBot = explorBot;
   }
 

package/src/commands/init-command.ts

@@ -39,7 +39,7 @@ ${moduleExport}
 `;
 }
 
-function envTemplate(provider: string): string {
+export function envTemplate(provider: string): string {
   const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
     if (name === provider) return `${envKey}=`;
     return `# ${envKey}=`;
@@ -253,7 +253,7 @@ async function renderLocalProviderWizard(): Promise<string | null> {
   });
 }
 
-function modelLines(provider: string): string {
+export function modelLines(provider: string, only?: ModelRole[]): string {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
   const roles: Array<[ModelRole, string]> = [
     ['model', 'fast model with tool calling capabilities'],
@@ -261,7 +261,10 @@ function modelLines(provider: string): string {
     ['agenticModel', 'agentic model for decision making'],
   ];
 
-  return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+  let selected = roles;
+  if (only) selected = roles.filter(([role]) => only.includes(role));
+
+  return selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
 }
 
 function globalConfigTemplate(provider: string): string {

package/src/explorer.ts

@@ -263,7 +263,7 @@ class Explorer {
   }
 
   private convertToCodeceptConfig(config: ExplorbotConfig): any {
-    const playwrightConfig = { ...config.playwright };
+    const playwrightConfig = { visibleLocator: true, ...config.playwright };
 
     if (this.options?.show !== undefined) {
       playwrightConfig.show = this.options.show;