libretto 0.5.1 → 0.5.2

package/dist/shared/condense-dom/condense-dom.js

@@ -1,22 +1,12 @@
-const TEST_ATTRS = /* @__PURE__ */ new Set(["data-testid", "data-test", "data-qa", "data-cy"]);
-const TRUSTED_ATTRS = /* @__PURE__ */ new Set([
-  "id",
-  "name",
-  "for",
-  "tabindex",
-  "contenteditable",
-  "role",
-  "title",
-  "alt",
-  "type",
-  "value",
-  "placeholder",
-  "autocomplete",
-  "href",
-  "action",
-  "method",
-  "src"
-]);
+import {
+  filterSemanticClasses,
+  INTERACTIVE_ROLE_NAMES,
+  INTERACTIVE_TAG_NAMES,
+  TEST_ATTRIBUTE_NAMES,
+  TRUSTED_ATTRIBUTE_NAMES
+} from "../dom-semantics.js";
+const TEST_ATTRS = new Set(TEST_ATTRIBUTE_NAMES);
+const TRUSTED_ATTRS = new Set(TRUSTED_ATTRIBUTE_NAMES);
 const STATE_ATTRS = /* @__PURE__ */ new Set([
   "disabled",
   "hidden",
@@ -55,28 +45,8 @@ const SCRIPT_ATTRS = /* @__PURE__ */ new Set([
   "referrerpolicy"
 ]);
 const STYLE_TAG_ATTRS = /* @__PURE__ */ new Set(["media", "type", "nonce", "title"]);
-const INTERACTIVE_TAGS = /* @__PURE__ */ new Set([
-  "a",
-  "button",
-  "input",
-  "select",
-  "textarea",
-  "form",
-  "details",
-  "dialog",
-  "label"
-]);
-const INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
-  "button",
-  "link",
-  "tab",
-  "menuitem",
-  "checkbox",
-  "radio",
-  "switch",
-  "slider",
-  "combobox"
-]);
+const INTERACTIVE_TAGS = new Set(INTERACTIVE_TAG_NAMES);
+const INTERACTIVE_ROLES = new Set(INTERACTIVE_ROLE_NAMES);
 const OPEN_TAG_PATTERN = /<([a-zA-Z][\w:-]*)(\s(?:[^"'<>/]|"[^"]*"|'[^']*')*)?\s*(\/?)>/g;
 function condenseDom(html) {
   const originalLength = html.length;
@@ -337,21 +307,6 @@ function normalizeUrlValue(value) {
     return `${value.slice(0, 96)}[omitted]`;
   }
 }
-function filterSemanticClasses(value) {
-  const classes = value.split(/\s+/).filter(Boolean);
-  const kept = classes.filter((cls) => !isObfuscatedClass(cls));
-  return kept.join(" ");
-}
-function isObfuscatedClass(cls) {
-  if (cls.length > 80) return true;
-  if (/^_?[0-9a-f]{6,}$/i.test(cls)) return true;
-  if (/^[a-z]+_[0-9a-f]{4,}$/i.test(cls)) return true;
-  if (/^[a-z]{1,2}[0-9]{2,}$/i.test(cls)) return true;
-  const digits = (cls.match(/[0-9]/g) || []).length;
-  const letters = (cls.match(/[a-zA-Z]/g) || []).length;
-  if (cls.length >= 6 && digits >= letters * 0.5 && digits >= 2) return true;
-  return false;
-}
 function parseAttributes(rawAttrs) {
   const attrs = [];
   const attrPattern = /([^\s"'<>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;

package/dist/shared/dom-semantics.d.ts

@@ -0,0 +1,8 @@
+declare const TEST_ATTRIBUTE_NAMES: readonly ["data-testid", "data-test", "data-qa", "data-cy"];
+declare const TRUSTED_ATTRIBUTE_NAMES: readonly ["id", "name", "for", "tabindex", "contenteditable", "role", "title", "alt", "type", "value", "placeholder", "autocomplete", "href", "action", "method", "src"];
+declare const INTERACTIVE_TAG_NAMES: readonly ["a", "button", "input", "select", "textarea", "form", "details", "dialog", "label"];
+declare const INTERACTIVE_ROLE_NAMES: readonly ["button", "link", "tab", "menuitem", "checkbox", "radio", "switch", "slider", "combobox"];
+declare function filterSemanticClasses(value: string): string;
+declare function isObfuscatedClass(cls: string): boolean;
+
+export { INTERACTIVE_ROLE_NAMES, INTERACTIVE_TAG_NAMES, TEST_ATTRIBUTE_NAMES, TRUSTED_ATTRIBUTE_NAMES, filterSemanticClasses, isObfuscatedClass };

package/dist/shared/dom-semantics.js

@@ -0,0 +1,69 @@
+const TEST_ATTRIBUTE_NAMES = [
+  "data-testid",
+  "data-test",
+  "data-qa",
+  "data-cy"
+];
+const TRUSTED_ATTRIBUTE_NAMES = [
+  "id",
+  "name",
+  "for",
+  "tabindex",
+  "contenteditable",
+  "role",
+  "title",
+  "alt",
+  "type",
+  "value",
+  "placeholder",
+  "autocomplete",
+  "href",
+  "action",
+  "method",
+  "src"
+];
+const INTERACTIVE_TAG_NAMES = [
+  "a",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "form",
+  "details",
+  "dialog",
+  "label"
+];
+const INTERACTIVE_ROLE_NAMES = [
+  "button",
+  "link",
+  "tab",
+  "menuitem",
+  "checkbox",
+  "radio",
+  "switch",
+  "slider",
+  "combobox"
+];
+function filterSemanticClasses(value) {
+  const classes = value.split(/\s+/).filter(Boolean);
+  const kept = classes.filter((cls) => !isObfuscatedClass(cls));
+  return kept.join(" ");
+}
+function isObfuscatedClass(cls) {
+  if (cls.length > 80) return true;
+  if (/^_?[0-9a-f]{6,}$/i.test(cls)) return true;
+  if (/^[a-z]+_[0-9a-f]{4,}$/i.test(cls)) return true;
+  if (/^[a-z]{1,2}[0-9]{2,}$/i.test(cls)) return true;
+  const digits = (cls.match(/[0-9]/g) || []).length;
+  const letters = (cls.match(/[a-zA-Z]/g) || []).length;
+  if (cls.length >= 6 && digits >= letters * 0.5 && digits >= 2) return true;
+  return false;
+}
+export {
+  INTERACTIVE_ROLE_NAMES,
+  INTERACTIVE_TAG_NAMES,
+  TEST_ATTRIBUTE_NAMES,
+  TRUSTED_ATTRIBUTE_NAMES,
+  filterSemanticClasses,
+  isObfuscatedClass
+};

package/dist/shared/run/browser.js

@@ -8,6 +8,7 @@ import {
   SESSION_STATE_VERSION,
   SessionStateFileSchema
 } from "../state/session-state.js";
+import { readLibrettoConfig } from "../../cli/core/ai-config.js";
 async function pickFreePort() {
   return await new Promise((resolve, reject) => {
     const server = createServer();
@@ -23,6 +24,41 @@ async function pickFreePort() {
     });
   });
 }
+function resolveWindowPosition() {
+  return readLibrettoConfig().windowPosition;
+}
+async function applyWindowPosition(browser, context, page, windowPosition) {
+  if (!windowPosition) {
+    return;
+  }
+  const requestedBounds = {
+    left: windowPosition.x,
+    top: windowPosition.y,
+    windowState: "normal"
+  };
+  const pageCdp = await context.newCDPSession(page);
+  let browserCdp;
+  try {
+    const targetInfo = await pageCdp.send("Target.getTargetInfo");
+    const targetId = targetInfo.targetInfo?.targetId;
+    browserCdp = await browser.newBrowserCDPSession();
+    const windowResult = await browserCdp.send(
+      "Browser.getWindowForTarget",
+      targetId ? { targetId } : {}
+    );
+    await browserCdp.send("Browser.setWindowBounds", {
+      windowId: windowResult.windowId,
+      bounds: requestedBounds
+    });
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  } catch {
+  } finally {
+    await pageCdp.detach().catch(() => {
+    });
+    await browserCdp?.detach().catch(() => {
+    });
+  }
+}
 async function launchBrowser({
   sessionName,
   headless = false,
@@ -30,12 +66,14 @@ async function launchBrowser({
   storageStatePath
 }) {
   const debugPort = await pickFreePort();
+  const windowPosition = headless ? void 0 : resolveWindowPosition();
   const browser = await chromium.launch({
     headless,
     args: [
       "--disable-blink-features=AutomationControlled",
       `--remote-debugging-port=${debugPort}`,
-      "--no-focus-on-check"
+      "--no-focus-on-check",
+      ...windowPosition ? [`--window-position=${windowPosition.x},${windowPosition.y}`] : []
     ]
   });
   const context = await browser.newContext({
@@ -43,6 +81,7 @@ async function launchBrowser({
     ...storageStatePath ? { storageState: storageStatePath } : {}
   });
   const page = await context.newPage();
+  await applyWindowPosition(browser, context, page, windowPosition);
   page.setDefaultTimeout(3e4);
   page.setDefaultNavigationTimeout(45e3);
   const metadataPath = ensureLibrettoSessionStatePath(sessionName);

package/dist/shared/visualization/ghost-cursor.js

@@ -1,7 +1,7 @@
 const DEFAULTS = {
   style: "minimal",
   color: "rgba(255, 70, 70, 0.9)",
-  size: 20,
+  size: 23,
   zIndex: 2147483646,
   easing: "cubic-bezier(0.16, 1, 0.3, 1)",
   minDurationMs: 100,
@@ -16,19 +16,32 @@ function buildCursorSvg(style, color, size) {
   if (style === "screenstudio") {
     return `<div style="width:${size * 1.4}px;height:${size * 1.4}px;border-radius:50%;background:${color};box-shadow:0 0 ${size * 0.6}px ${color};opacity:0.7;"></div>`;
   }
-  return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+  return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" style="display:block;filter:drop-shadow(0 2px 6px rgba(15,23,42,0.22));">
 		<path d="M5 3L19 12L12 13L9 20L5 3Z" fill="${color}" stroke="rgba(0,0,0,0.3)" stroke-width="1"/>
 	</svg>`;
 }
+function buildCursorMarkup(style, color, size) {
+  const cursor = buildCursorSvg(style, color, size);
+  const badgeHeight = Math.max(12, Math.round(size * 0.54));
+  const fontSize = Math.max(8, Math.round(size * 0.28));
+  const minWidth = Math.max(28, Math.round(size * 1.28));
+  const paddingX = Math.max(5, Math.round(size * 0.2));
+  const left = Math.round(size * 0.84);
+  const top = Math.round(size * 0.74);
+  const width = Math.round(size * 2.4);
+  const height = Math.round(size * 1.95);
+  const badge = `<div aria-hidden="true" style="position:absolute;left:${left}px;top:${top}px;display:flex;align-items:center;justify-content:center;min-width:${minWidth}px;height:${badgeHeight}px;padding:0 ${paddingX}px;border-radius:${badgeHeight}px;background:${color};color:rgba(255,255,255,0.96);font:700 ${fontSize}px/1 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;letter-spacing:0.02em;white-space:nowrap;border:1px solid rgba(0,0,0,0.16);box-shadow:0 4px 12px rgba(0,0,0,0.14);transform-origin:left center;">Agent</div>`;
+  return `<div style="position:relative;width:${width}px;height:${height}px;overflow:visible;">${cursor}${badge}</div>`;
+}
 function buildInitScript(opts) {
-  const svg = buildCursorSvg(opts.style, opts.color, opts.size);
+  const markup = buildCursorMarkup(opts.style, opts.color, opts.size);
   return `
 (function() {
 	if (document.getElementById("${CURSOR_ID}")) return;
 	var el = document.createElement("div");
 	el.id = "${CURSOR_ID}";
 	el.style.cssText = "position:fixed;top:0;left:0;z-index:${opts.zIndex};pointer-events:none;transform:translate3d(-100px,-100px,0);transition:none;will-change:transform,opacity;opacity:0;";
-	el.innerHTML = ${JSON.stringify(svg)};
+	el.innerHTML = ${JSON.stringify(markup)};
 	document.documentElement.appendChild(el);
 })();
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {

package/skills/libretto/SKILL.md

@@ -10,30 +10,31 @@ metadata:
 ## How Libretto Works
 
 - Libretto is a CLI for exploring live websites and building or debugging reusable browser automation scripts.
-- Use Libretto to inspect the real site first: open pages, observe state, inspect requests, and prototype interactions before writing code.
+- Use Libretto commands to inspect the site and open pages, observe state, inspect requests, and prototype interactions.
 - Libretto work must end in script changes. Create or edit the workflow file instead of stopping at interactive exploration.
 
 ## Default Integration Approach
 
-- Prefer network requests first for new integrations.
+- Prefer network requests first for new integrations unless the user explicitly asks for Playwright or UI automation, then do not use the site's internal API.
 - Read `references/site-security-review.md` before committing to a network-first approach on a new site.
 - Fall back to passive interception or Playwright-driven UI automation when the security review rules network requests out, the request path is not workable, or the user explicitly asks for Playwright.
 
 ## Setup
 
-- Ask the user to set up snapshot analysis before relying on `snapshot` for page understanding.
-- Use `npx libretto init` for first-time workspace setup.
+- Use `npx libretto init` for first-time workspace setup (sets up config file and snapshot command).
 - If credentials are already available, `npx libretto ai configure openai|anthropic|gemini|vertex` is usually enough.
 
 ## Working Rules
 
 - Announce which session you are using and what page you are on.
 - Ask instead of guessing when it is unclear what to click, type, or submit.
+- Do not treat visibility as interactivity. If an element will not act, inspect blockers before retrying.
+- Defer repo/code review until you begin generating code, unless the user explicitly asks for it earlier.
 - Read and follow guidelines in `references/code-generation-rules.md` before generating or editing production workflow code.
-- After interactive exploration and code generation, test key logic with `exec`, then verify the workflow file with `run --headless`.
+- Validation requires a successful clean `run --headless` with confirmation of the actual returned output, not just process success. If the user wants to watch the finished workflow, do a final headed `run` after headless validation succeeds.
+- Treat exploration sessions as disposable unless the user explicitly wants one kept open.
 - Get explicit user confirmation before mutating actions or replaying network requests that may have side effects.
 - Never run multiple `exec` commands at the same time.
-- Keep the browser session open until the user says the session is done.
 
 ## Commands
 
@@ -63,6 +64,7 @@ npx libretto connect http://127.0.0.1:9223 --session another-session
 
 - Use `snapshot` as the primary page observation tool.
 - Always provide both `--objective` and `--context`.
+- A single snapshot objective can include multiple questions or analysis tasks.
 - Use it before guessing at selectors, after workflow failures, and whenever the visible page state is unclear.
 - When analysis is involved, expect it to take time. Use a timeout of at least 2 minutes for shell-wrapped calls.
 
@@ -81,13 +83,14 @@ npx libretto snapshot \
 
 - Use `exec` for focused inspection and short-lived interaction experiments.
 - Use `exec` to validate selectors, inspect data, or prototype a step before you encode it in the workflow file.
+- Available globals: `page`, `context`, `browser`, `state`, `fetch`, `Buffer`.
 - Let failures throw. Do not hide `exec` failures with `try/catch` or `.catch()`.
 - Do not run multiple `exec` commands in parallel.
 
 ```bash
 npx libretto exec "return await page.url()"
 npx libretto exec "return await page.locator('button').count()"
-npx libretto exec --visualize "await page.locator('button:has-text(\"Continue\")').click()"
+npx libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
 ```
 
 ### `pages`
@@ -100,45 +103,25 @@ npx libretto pages --session debug-example
 npx libretto exec --session debug-example --page <page-id> "return await page.url()"
 ```
 
-### `network`
-
-- Use `network` to inspect the requests the page already made.
-- Prefer this when discovering how a site loads data or when validating whether a network-first approach is workable.
-- Filter aggressively by method, URL pattern, and page when the log is noisy.
-
-```bash
-npx libretto network --session debug-example --last 20
-npx libretto network --session debug-example --method POST --filter 'referral|patient'
-npx libretto network --session debug-example --page <page-id>
-```
-
-### `actions`
-
-- Use `actions` when you need a quick record of recent user or agent interactions in the current session.
-- Keep it lightweight. It is a helper for orientation, not the main integration-building workflow.
-
-```bash
-npx libretto actions --session debug-example --last 20
-npx libretto actions --session debug-example --action click --source user
-```
-
 ### `run`
 
-- Use `run` to verify a workflow file after creating it or editing it.
+- Use `run` to verify a workflow file after creating it or editing it, preferring `run --headless` for the normal fix/verify loop.
+- Plain `run` defaults to headed mode.
 - If the workflow fails, Libretto keeps the browser open. Inspect the failed state with `snapshot` and `exec` before editing code.
+- Insert `await pause(session)` statements in the workflow file when you need to stop at specific states for interactive debugging, like breakpoints in the browser flow.
 - If the workflow pauses, resume it with `npx libretto resume --session <name>`.
 - Re-run the same workflow after each fix to verify the browser behavior end to end.
 
 ```bash
-npx libretto run ./integration.ts main
-npx libretto run ./integration.ts main --params '{"status":"open"}'
-npx libretto run ./integration.ts main --auth-profile app.example.com --headed
+npx libretto run ./integration.ts main --headless --params '{"status":"open"}'
+npx libretto run ./integration.ts main --auth-profile app.example.com
 ```
 
 ### `resume`
 
-- Workflows pause by calling `await pause()` in the workflow file.
-- Use `resume` when a workflow hit `await pause()`.
+- Workflows pause by calling `await pause("session-name")` in the workflow file. Import `pause` from `"libretto"`.
+- `pause(session)` is a no-op when `NODE_ENV === "production"`.
+- Use `resume` when a workflow hit a `pause()` call.
 - Keep resuming the same session until the workflow completes or pauses again.
 
 ```bash
@@ -147,7 +130,7 @@ npx libretto resume --session debug-example
 
 ### `save`
 
-- Use `save` when the user logs in manually and wants to reuse that authenticated browser state later.
+- Use `save` only when the user explicitly asks to save or reuse authenticated browser state.
 
 ```bash
 npx libretto save app.example.com
@@ -155,7 +138,7 @@ npx libretto save app.example.com
 
 ### `close`
 
-- Use `close` only when the user is done with the session.
+- Use `close` when the user is done with the session or an exploration session is no longer helping progress (unless the user asked to keep watching that browser).
 - `close --all` is available for workspace cleanup.
 
 ```bash
@@ -163,6 +146,36 @@ npx libretto close --session debug-example
 npx libretto close --all
 ```
 
+## Session Logs
+
+Session state is stored in `.libretto/sessions/<session>/state.json`.
+
+Session logs are JSONL files at `.libretto/sessions/<session>/`:
+
+- CLI logs are in `.libretto/sessions/<session>/logs.jsonl`.
+- Action logs are in `.libretto/sessions/<session>/actions.jsonl`.
+- Network logs are in `.libretto/sessions/<session>/network.jsonl`.
+
+Use `jq` to query jsonl logs directly — for any filtering, slicing, or inspection task.
+
+```bash
+# Last 20 action entries
+tail -n 20 .libretto/sessions/<session>/actions.jsonl | jq .
+
+# POST requests only
+jq 'select(.method == "POST")' .libretto/sessions/<session>/network.jsonl
+```
+
+### Action log (`actions.jsonl`)
+
+Key fields: `ts` (ISO timestamp), `source` (`user` or `agent`), `action` (`click`, `fill`, `goto`, etc.), `selector` (locator used by the agent), `bestSemanticSelector` (canonical selector for user DOM events), `success` (boolean), `url` (navigation target), `value` (typed or submitted value), `error` (message on failure).
+
+Read `references/action-logs.md` for full field descriptions and user-vs-agent entry semantics.
+
+### Network log (`network.jsonl`)
+
+Key fields: `ts` (ISO timestamp), `method` (HTTP method, e.g. `GET`, `POST`), `url` (request URL), `status` (HTTP status code), `contentType` (response content type), `responseBody` (response body string, may be null).
+
 ## Examples
 
 ### Building new browser automation workflows
@@ -202,5 +215,6 @@ Assistant: I found the issue. I'll patch the workflow code, then rerun `npx libr
 - Read `references/configuration-file-reference.md` when you need to inspect or change `.libretto/config.json` for snapshot model selection or viewport defaults.
 - Read `references/site-security-review.md` before reviewing the site's security posture and deciding whether to lead with network requests, passive interception, or Playwright DOM automation on a new site.
 - Read `references/code-generation-rules.md` before writing or editing production workflow files.
-- Read `references/auth-profiles.md` when the site requires login and the simplest path is to save local browser state.
+- Read `references/auth-profiles.md` when auth-profile behavior is relevant.
 - Read `references/pages-and-page-targeting.md` when a session has multiple open pages or you need `--page`.
+- Read `references/action-logs.md` for full action log field descriptions and user-vs-agent event semantics.

package/skills/libretto/references/action-logs.md

@@ -0,0 +1,101 @@
+# Action Logs
+
+- Stored at `.libretto/sessions/<session>/actions.jsonl`.
+- One JSON object per line.
+- Query the file directly with `jq`, for example `tail -n 20 .libretto/sessions/<session>/actions.jsonl | jq .`.
+- This is an orientation log, not a replay trace.
+
+## User vs Agent
+
+- `agent` entries log the Playwright action Libretto observed, usually as `action` plus `selector`, and sometimes `value`, `url`, `duration`, or `error`.
+- `user` entries log the browser DOM event Libretto captured, so they can include `bestSemanticSelector`, `targetSelector`, `ancestorSelectors`, `nearbyText`, `composedPath`, and `coordinates`.
+- This is why agent entries usually describe what Playwright tried to do, while user entries can describe what element was actually interacted with in the page.
+
+## Fields
+
+- `ts`
+  ISO timestamp.
+
+- `pageId`
+  Playwright target id for the page that produced the entry.
+
+- `action`
+  Logged action name, such as `click`, `dblclick`, `fill`, `goto`, or `reload`.
+
+- `source`
+  `user` for captured DOM events, `agent` for logged Playwright calls.
+
+- `success`
+  `true` if the action completed, `false` if Libretto logged a failure.
+
+- `selector`
+  Selector or locator hint for agent entries.
+
+- `bestSemanticSelector`
+  Canonical selector for user DOM events.
+
+- `targetSelector`
+  Selector for the raw DOM event target. Usually only present for user DOM events.
+
+- `ancestorSelectors`
+  Meaningful ancestor selector candidates for a user DOM event. Ordered from closest meaningful ancestor to farthest meaningful ancestor.
+
+- `nearbyText`
+  Short visible text near the event target, used as human context.
+
+- `composedPath`
+  Compact event-path summaries. Ordered from the raw event target to farthest ancestor.
+
+- `coordinates`
+  Rounded `clientX` and `clientY` for pointer-style events:
+
+```json
+{ "x": 42, "y": 24 }
+```
+
+- `value`
+  Typed, selected, or submitted value when the action had one.
+
+- `url`
+  Navigation target or recorded page URL for navigation-style actions.
+
+- `duration`
+  Elapsed time in milliseconds when Libretto recorded it.
+
+- `error`
+  Error message when the action failed.
+
+## User Example
+
+```json
+{
+  "ts": "2026-03-20T22:34:56.123Z",
+  "pageId": "A1B2C3D4E5F6",
+  "action": "dblclick",
+  "source": "user",
+  "bestSemanticSelector": "button#saveBtn",
+  "targetSelector": "span",
+  "ancestorSelectors": ["button#saveBtn", "form[action=\"/save\"]"],
+  "nearbyText": "Save",
+  "composedPath": ["span [text=\"Save\"]", "button#saveBtn [text=\"Save\"]"],
+  "coordinates": {
+    "x": 42,
+    "y": 24
+  },
+  "success": true
+}
+```
+
+## Agent Example
+
+```json
+{
+  "ts": "2026-03-20T22:35:10.456Z",
+  "pageId": "A1B2C3D4E5F6",
+  "action": "click",
+  "source": "agent",
+  "selector": "page.getByRole(\"button\", {\"name\":\"Save\"})",
+  "duration": 187,
+  "success": true
+}
+```

package/skills/libretto/references/auth-profiles.md

@@ -1,12 +1,11 @@
 # Auth Profiles
 
-Use this reference when the target site requires login and the user wants to reuse local authenticated browser state.
+Use this reference only when the user explicitly asks to save or reuse local authenticated browser state.
 
 ## When to Use This
 
 - The site requires manual login.
 - The user is running workflows locally.
-- Reusing a saved session is simpler than building credential-handling logic into the workflow.
 
 ## Workflow
 

package/skills/libretto/references/code-generation-rules.md

@@ -41,8 +41,8 @@ Key points:
 - `workflow(handler)` returns a branded workflow object with a `.run(ctx, input)` method. The CLI expects that contract.
 - `ctx` provides `session`, `page`, `logger`, and `services` (generic, default `{}`)
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
-- If the site requires a saved login session, pass `--auth-profile <domain>` to the CLI (created via `npx libretto save <domain>`)
 - Use `await pause(ctx.session)` (or `await pause(session)`) to pause the workflow for debugging. It is a no-op in production.
+- After validation is complete and the workflow is confirmed working end to end, remove all `pause()` calls and pause-only workflow params unless the user explicitly says to keep them.
 - The browser is launched and closed automatically by the CLI. Do not launch or close it in the handler.
 
 ## Passing Application Dependencies via Services
@@ -80,12 +80,14 @@ await myWorkflow.run(
 When running standalone via `npx libretto run`, services defaults to `{}`,
 so mark fields optional for anything unavailable in that context.
 
-## Playwright Locators for DOM Interaction
+## Playwright DOM Interaction Rules
 
 Generated code must use Playwright locator APIs for all DOM interactions. Do not use `page.evaluate()` with `document.querySelector`, `querySelectorAll`, `textContent`, `click()`, or other DOM APIs when a Playwright locator can do the same thing.
 
 During the interactive `exec` phase, `page.evaluate` is fine for quick prototyping. In generated production code, translate those patterns into Playwright locators.
 
+Before extracting data (for example text, rows, or field values), wait for the target content itself to be ready, not just its container.
+
 ### Anti-Patterns
 
 These patterns come up frequently during interactive sessions and should not carry over into production code:

package/skills/libretto/references/pages-and-page-targeting.md

@@ -26,4 +26,4 @@ npx libretto snapshot --session debug-flow --page <page-id> --objective "Find th
 
 - A session can contain more than one page.
 - When multiple pages are open, think about page targeting first before debugging selectors.
-- Use `pages` to resolve the correct page id, then pass `--page` to `exec`, `snapshot`, `network`, or `actions` when needed.
+- Use `pages` to resolve the correct page id, then pass `--page` to `exec` or `snapshot` when needed.