libretto 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -13,7 +13,9 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "scripts",
+    "skill"
   ],
   "bin": {
     "libretto": "./bin/libretto.mjs",

package/scripts/postinstall.mjs

@@ -0,0 +1,48 @@
+import { cpSync, existsSync, lstatSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function isDirectory(path) {
+	if (!existsSync(path)) return false;
+	return lstatSync(path).isDirectory();
+}
+
+function log(message) {
+	console.log(`[libretto postinstall] ${message}`);
+}
+
+function main() {
+	const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+	const initCwd = process.env.INIT_CWD ? resolve(process.env.INIT_CWD) : null;
+	const installRoot = initCwd ?? process.cwd();
+
+	const sourceSkillDir = join(packageDir, "skill");
+	if (!isDirectory(sourceSkillDir)) {
+		log(`Skipped: source skill directory not found at "${sourceSkillDir}".`);
+		return;
+	}
+
+	const targets = [
+		join(installRoot, ".agents", "skills"),
+		join(installRoot, ".claude", "skills"),
+	];
+
+	for (const skillsRoot of targets) {
+		if (!isDirectory(skillsRoot)) {
+			log(`Skipped: "${skillsRoot}" does not exist.`);
+			continue;
+		}
+
+		const destinationSkillDir = join(skillsRoot, "libretto");
+		mkdirSync(destinationSkillDir, { recursive: true });
+		cpSync(sourceSkillDir, destinationSkillDir, { recursive: true, force: true });
+		log(`Synced skill "libretto" to "${skillsRoot}/libretto".`);
+	}
+}
+
+try {
+	main();
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	console.warn(`[libretto postinstall] Warning: ${message}`);
+}

package/skill/SKILL.md

@@ -0,0 +1,438 @@
+---
+name: libretto
+description: "Browser automation CLI for building integrations, with a network-first approach.\n\nWHEN TO USE THIS SKILL:\n- When building a new integration or data extraction workflow against a website\n- When you need to interact with a web page (click, fill, navigate) rather than just read it\n- When debugging browser agent job failures (selectors timing out, clicks not working, elements not found)\n- When you need to test or prototype Playwright interactions before codifying them\n- When you need to save or restore login sessions for authenticated pages\n- When you need to understand what's on a page (use the snapshot command)\n- When scraping dynamic content that requires JavaScript execution\n\nWHEN NOT TO USE THIS SKILL:\n- When you only need to read static web content (use read_web_page instead)\n- When you need to modify browser agent source code (edit files directly)\n- When you need to run a full browser agent job end-to-end (use npx browser-agent CLI)"
+---
+
+# Browser Integration with Libretto CLI
+
+Use the `npx libretto` CLI to automate web interactions, debug browser agent jobs, and prototype fixes.
+
+## CRITICAL: Session Access
+
+Libretto sessions are **full-access by default**. You can use `exec` and `run` immediately after opening a session.
+
+**Rules:**
+- Always announce which session you opened and what page you are on.
+- Use `snapshot`, `network`, and `actions` first when debugging unknown page state.
+- Before any potentially mutating action (submit/save/delete, or non-idempotent API calls), describe what you are about to do and wait for explicit user confirmation.
+
+## Ask, Don't Guess
+
+If it's not obvious which element to click or what value to enter, **ask the user** — don't try multiple things hoping one works. Present what you see on the page and let the user tell you where to go. One question is faster than a 30-second timeout from a wrong guess.
+
+## Commands
+
+```bash
+npx libretto open <url> [--headless]   # Launch browser and navigate (headed by default)
+npx libretto exec <code> [--visualize] # Execute Playwright TypeScript code (--visualize enables ghost cursor + highlight)
+npx libretto run <integrationFile> <integrationExport> # Execute integration actions
+npx libretto resume                    # Resume a paused workflow for the current session
+npx libretto snapshot --objective "<what to find>" [--context "<situational info>"]
+npx libretto save <url|domain>         # Save session (cookies, localStorage) to .libretto/profiles/
+npx libretto network                   # Show last 20 captured network requests
+npx libretto actions                   # Show last 20 captured user/agent actions
+npx libretto close                     # Close the browser
+```
+
+All commands accept `--session <name>` for isolated browser instances (default: `default`).
+Built-in sessions: `default`, `dev-server`, `browser-agent`.
+
+## Visualize Mode (`--visualize`)
+
+Add `--visualize` to any `exec` command to show a ghost cursor and element highlight before each action executes. Use it when the user wants to see what will be clicked/filled before it happens.
+
+## Workflow Pause/Resume (`ctx.pause()`)
+
+Workflows pause from inside the workflow function by calling `await ctx.pause()`.
+
+- There are no pause options to pass at call sites. Pause is session-scoped and resolved from the active session.
+- `npx libretto run ...` waits until the workflow either completes or hits the next `ctx.pause()`.
+- On pause, the workflow process stays alive and keeps browser/session state.
+- `npx libretto resume --session <name>` sends resume signal and then waits until completion or the next pause.
+- For multi-pause workflows, call `resume` repeatedly until the workflow completes.
+
+## Globals Available in `exec`
+
+`page`, `context`, `state`, `browser`, `networkLog({ last?, filter?, method? })`, `actionLog({ last?, filter?, action?, source? })`, `console`, `fetch`, `Buffer`, `URL`, `setTimeout`
+
+The `state` object persists across `exec` calls within the same session — use it to carry values between commands.
+
+## CRITICAL: No try/catch in exec
+
+**Never use try/catch or .catch() in exec code.** Let errors throw so they surface as exec failures. When an exec fails, you get the full error message (e.g., "intercepts pointer events", "Timeout 30000ms exceeded") — use that to diagnose the problemand write a corrected exec.
+
+**Why:** A try/catch inside exec hides failures from you. A click that times out takes 30 seconds — if you retry it in a loop with try/catch, you'll silently burn minutes on the same broken selector with no way to recover. Without try/catch, the error comes back immediately and you can reason about what went wrong.
+
+**Instead of try/catch, use check-first patterns:**
+
+```typescript
+// BAD — silently retries for minutes
+try {
+  await btn.click();
+} catch {
+  /* retry or ignore */
+}
+
+// GOOD — check first, fail fast
+if (await btn.isVisible()) await btn.click();
+
+// GOOD — check existence before acting
+if ((await page.locator(".cookie-banner").count()) > 0) {
+  await page.locator(".cookie-banner button").click();
+}
+```
+
+If an action fails despite an element being visible, you should not keep retrying it. Instead you can try the following debugging steps:
+
+1. Take a snapshot to inspect what's covering the element
+2. Try `{ force: true }` to bypass actionability checks
+3. Try a completely different approach (e.g., opening a dialog via a different button)
+
+## Workflow: Browse and Interact
+
+```bash
+# Open a page
+npx libretto open https://example.com
+
+# Interact with elements
+npx libretto exec "await page.locator('button:has-text(\"Sign in\")').click()"
+npx libretto exec "await page.fill('input[name=\"email\"]', 'user@example.com')"
+
+# Understand the page — always provide objective and context
+npx libretto snapshot \
+  --objective "Find the sign-in form fields and submit button" \
+  --context "Navigated to example.com login page. Expecting email/password inputs and a submit button."
+
+# Include relevant network calls in context when debugging API interactions
+npx libretto snapshot \
+  --objective "Find why the referral list is empty" \
+  --context "Logged into eClinicalWorks. Clicked Open Referrals tab. Table appears but shows no rows. Recent POST to /servlet/AjaxServlet returned 200 but with empty body."
+
+# Done
+npx libretto close
+```
+
+## Workflow: Save and Restore Login Sessions
+
+Profiles persist cookies and localStorage across browser launches. They are saved to `.libretto/profiles/<domain>.json` (git-ignored) and loaded automatically on `open`.
+
+```bash
+# Open a site in headed mode so you can log in manually
+npx libretto open https://portal.example.com --headed
+
+# ... manually log in in the browser window ...
+
+# Save the session
+npx libretto save portal.example.com
+
+# Next time you open this domain, you'll be logged in automatically
+npx libretto open https://portal.example.com
+```
+
+## Workflow: Interactive Debugging
+
+When browser automation jobs fail (selectors timing out, clicks not working), use the interactive debugging workflow instead of edit-restart cycles. This reduces iteration time from 5-10 minutes to ~30 seconds.
+
+1. Add `page.pause()` before the problematic code section
+2. Start the job with `npx browser-agent start` (debug mode is always enabled locally)
+3. Wait ~60 seconds for the browser to hit the breakpoint
+4. Use `npx libretto exec` (with `--session browser-agent`) to inspect and prototype fixes
+5. Once the fix works, codify it in source files
+6. Restart the job to verify end-to-end
+
+```bash
+# Start job in background
+npx browser-agent start \
+  --job-type pull-open-referrals \
+  --tenant-slug hhb \
+  --params '{"vendorName":"eClinicalWorks"}'
+
+# Inspect page state
+npx libretto exec --session browser-agent "return await page.url();"
+npx libretto snapshot --session browser-agent \
+  --objective "Find dropdown menus and their current selections" \
+  --context "Browser agent hit breakpoint during pull-open-referrals job. Need to inspect dropdown state."
+
+# List dropdown options
+npx libretto exec --session browser-agent "return await page.locator('option').allTextContents();"
+
+# Test a fix
+npx libretto exec --session browser-agent "await page.locator('.dropdown-trigger').click(); return 'clicked';"
+```
+
+## Snapshot — The Primary Observation Tool
+
+The `snapshot` command captures a PNG screenshot + HTML, sends both to a vision model (Gemini Flash), and returns an analysis with Playwright-ready selectors. `--objective` is required for analysis, and `--context` is optional (but recommended for better results). This is the single way to understand what's on the page — use it any time you need to inspect page structure, find elements, or debug what's happening.
+
+**Never use `page.screenshot()` via `exec` to understand the page.** Use the `snapshot` command instead — it captures the screenshot, HTML, and sends both to a vision model that returns actionable selectors. Raw screenshots give you an image with no analysis; `snapshot` gives you the answer.
+
+### What to Put in `--objective`
+
+The objective tells the vision agent what you're looking for. Be specific:
+
+- "Find the referral status column in the table"
+- "Find the error message or alert preventing form submission"
+- "Identify all dropdown menus on the page and their current selections"
+
+### What to Put in `--context`
+
+Context gives the vision agent situational awareness. Include:
+
+1. **Where you are** — page, step, state (e.g., "On the eClinicalWorks referral list page")
+2. **What you did** — actions taken (e.g., "Clicked 'Open Referrals' tab, selected department 'Cardiology'")
+3. **What you expect** — desired state (e.g., "Expecting a table of open referrals with patient names")
+4. **Relevant selectors** — any CSS selectors, data-testids, or element identifiers you already know about
+5. **Task context** — what the automation is trying to accomplish overall
+6. **Network calls** — any relevant HTTP requests/responses (e.g., "POST /api/referrals returned 200 with empty array")
+
+```bash
+npx libretto snapshot \
+  --objective "Find the referral status column in the table" \
+  --context "Logged into eClinicalWorks as admin. Navigated to Referrals > Open Referrals tab. Expecting a table of open referrals with columns for patient name, provider, and status."
+
+# Debugging example
+npx libretto snapshot \
+  --objective "Find the error message or alert" \
+  --context "Clicked Submit on the new referral form after filling in all required fields. Expected to see a success confirmation, but the page appears to still be on the form."
+```
+
+## Inspecting Raw DOM with `exec`
+
+When the snapshot doesn't give you enough detail — why an element is hidden, what directives or event handlers it has, how it's styled — use `exec` with `page.evaluate` to query the raw DOM directly.
+
+- **`outerHTML`** — See the complete markup of an element including all attributes.
+  ```bash
+  npx libretto exec "const el = await page.locator('#myElement').elementHandle(); return await page.evaluate(el => el.outerHTML.substring(0, 500), el);"
+  ```
+- **Computed styles / parent chain** — Debug why Playwright can't click an element.
+  ```bash
+  npx libretto exec "const el = await page.locator('#myElement').elementHandle(); return await page.evaluate(el => { const chain = []; let n = el; for (let i = 0; i < 8 && n; i++) { const s = getComputedStyle(n); chain.push({ tag: n.tagName, id: n.id, display: s.display, visibility: s.visibility }); n = n.parentElement; } return chain; }, el);"
+  ```
+- **Any DOM property** — `page.evaluate` gives you full access: `getBoundingClientRect()`, `dataset`, `children`, `classList`, attached event listeners, etc.
+
+## Tips
+
+- **Never use `page.screenshot()` via `exec`.** Use `npx libretto snapshot` instead — it captures the viewport, sends the screenshot + HTML to a vision model, and returns actionable selectors. The `fullPage` option is especially dangerous — it scrolls the entire page to stitch a screenshot, which can crash JavaScript-heavy pages (especially EMR portals like eClinicalWorks).
+- **Never run `exec` commands in parallel.** Always wait for one `exec` to finish before starting the next. Do not use `run_in_background` for `exec` calls. Running simultaneous `exec` calls opens multiple CDP connections to the same page, which corrupts the page state and kills the browser.
+- `open` and `run` require an available session. If the session is already active, Libretto fails fast and asks you to close the existing session or use a different `--session`.
+- Use `return <value>` in `exec` to print results. Strings print raw; objects print as JSON.
+- For iframe content, access via `page.locator('iframe[name="..."]').contentFrame()`.
+- Multiple sessions allow parallel browser instances: `--session test1`, `--session test2`.
+
+## Network Logging
+
+Network requests are captured automatically when a browser is opened via `npx libretto open`. All non-static HTTP responses (excluding `.css`, `.js`, `.png`, `.jpg`, `.gif`, `.woff`, `.ico`, `.svg`, and `chrome-extension://` URLs) are logged to `.libretto/sessions/<session>/network.jsonl`.
+
+### CLI: `npx libretto network`
+
+```bash
+npx libretto network                              # show last 20 requests
+npx libretto network --last 50                    # show last 50
+npx libretto network --filter 'referral|patient'  # regex filter on URL
+npx libretto network --method POST                # filter by HTTP method
+npx libretto network --clear                      # truncate the log file
+```
+
+### In exec: `networkLog()`
+
+```bash
+npx libretto exec "return await networkLog()"
+npx libretto exec "return await networkLog({ filter: 'servlet', last: 5 })"
+npx libretto exec "return await networkLog({ method: 'POST' })"
+```
+
+Returns an array of objects with: `ts`, `method`, `url`, `status`, `contentType`, `postData` (POST/PUT/PATCH only, first 2000 chars), `size`, `durationMs`.
+
+**Note:** Network logging only works for sessions opened via `npx libretto open`. It does not capture requests for external sessions like `--session browser-agent`.
+
+## Action Logging
+
+Browser actions are captured automatically when a browser is opened via `npx libretto open`. Both user interactions (manual clicks, typing in the headed browser window) and agent actions (programmatic Playwright API calls via `exec`) are logged to `.libretto/sessions/<session>/actions.jsonl` with a `source` field of `'user'` or `'agent'` to distinguish the two.
+
+### CLI: `npx libretto actions`
+
+```bash
+npx libretto actions                              # show last 20 actions
+npx libretto actions --last 50                    # show last 50
+npx libretto actions --filter 'button|input'      # regex filter on selector/value
+npx libretto actions --action click                # filter by action type
+npx libretto actions --source user                 # only manual user actions
+npx libretto actions --source agent                # only programmatic agent actions
+npx libretto actions --clear                       # truncate the log file
+```
+
+### In exec: `actionLog()`
+
+```bash
+npx libretto exec "return await actionLog()"
+npx libretto exec "return await actionLog({ source: 'user', last: 5 })"
+npx libretto exec "return await actionLog({ action: 'click' })"
+```
+
+Returns an array of objects with: `ts`, `action`, `source` (`'user'` | `'agent'`), `selector`, `value`, `url`, `duration`, `success`, `error`.
+
+**Note:** Action logging only works for sessions opened via `npx libretto open`. It does not capture actions for external sessions like `--session browser-agent`.
+
+## Workflow: Creating a New Integration
+
+Use Libretto CLI interactively to build a brand new integration from scratch. Navigate the real site with the user, discover the network endpoints, and codify the data extraction into a reusable TypeScript script.
+
+**IMPORTANT:** Do NOT explore the codebase or research existing code before starting. This skill file and the CLI commands below contain everything you need. Jump straight into using the CLI interactively — ask the user for the URL, open the browser, and start working. The only exception is if the user mentions a specific file or piece of code to reference — then read that specific file first, but nothing more.
+
+### Approach Selection
+
+By default, use the **preferred ordering of approaches**: try the network-first approach (`page.evaluate(fetch(...))`) first, then fall back to Playwright DOM automation if that doesn't work (see "Integration Approaches" below).
+
+**If the user explicitly specifies an approach**, use it instead.
+
+As part of starting the session, silently run a **security posture review** using the probes from `integration-approach-selection.md` (in this skill's directory) to assess the site's bot detection, fetch interception, and security posture. This tells you:
+
+- Whether `page.evaluate(fetch(...))` is safe (fetch not patched, no aggressive bot detection)
+- Whether `page.on('response', ...)` interception is viable
+- Whether you need to restrict to DOM-only extraction
+
+If the security review reveals that the default network-first approach won't work (e.g., fetch is monkey-patched, aggressive bot detection), **adapt your approach accordingly and tell the user what you found and which approach you're switching to.** You don't need to ask permission to switch — just explain what you discovered and proceed.
+
+The user may also share context during the session that changes the approach (e.g., they know the site blocks direct fetch). Adapt as needed.
+
+### Handling Approach Mismatches
+
+The security review tells you what's _safe_, but not necessarily what _works_ for every endpoint or data source on the site. As you build the integration, you may find that the recommended approach doesn't produce usable data for a specific part of the workflow. When this happens, **explain what you found, adapt your approach** for that specific part, and keep going.
+
+Common mismatches:
+
+- **Unparseable response format** — The fetch call succeeds but returns a proprietary format (RSC wire protocol, protobuf, encrypted payloads) instead of parseable JSON/XML/HTML.
+- **Data not in API responses** — The data is server-rendered into HTML or computed client-side; no network response contains it.
+- **Endpoint requires unpredictable parameters** — CSRF tokens, request signatures, or session values that rotate and aren't easily extractable.
+
+These can surface at any point — the first endpoint you try or the fifteenth. Different parts of the same integration often need different approaches.
+
+### Starting the Session
+
+The browser stays open indefinitely until explicitly closed with `npx libretto close` or by the user closing the window. **Do not** set any timeouts, auto-close timers, or call `close` until the user says the workflow session is done. Ensure that you open the browser in `--headed` mode so the user can see what's happening.
+
+If the site requires login, ask the user how auth should work in the generated workflow:
+
+1. Save a local profile (recommended for local runs): open in `--headed`, have the user log in manually, run `npx libretto save <domain>`, and generate workflow metadata with `authProfile: { type: "local", domain: "<hostname>" }`.
+2. Use user-managed credential logic in Playwright code (no local profile dependency).
+
+If local profile is chosen, include this warning in your generated workflow guidance: local profiles are machine-local (other users/environments will not have them), and sessions can expire so re-login/re-save may be required.
+
+### Integration Approaches
+
+There are two main approaches for building an integration. **Try the network-first approach first** — it's faster, more reliable, and less brittle. Fall back to Playwright automation if it doesn't work. Be flexible — different parts of the same integration may use different approaches, and a single workflow often mixes them. The user can also explicitly tell you which approach to use.
+
+#### Approach 1: Network-First — `page.evaluate(() => fetch(...))` (Try First)
+
+Use `page.evaluate(() => fetch(...))` to make requests directly in the browser's JavaScript context — for both extracting data and performing actions (form submissions, API calls, etc.). The requests share the browser's TLS fingerprint, cookies, and origin, so they look identical to requests the site's own JS would make.
+
+**Why this is preferred:** Maximum control and reliability. You call exactly the endpoints you want with the parameters you want, skip fragile UI rendering, and get structured data back. No brittle DOM selectors, no multi-step UI sequences that break when the site changes its layout.
+
+**How to try it:**
+
+1. Use Playwright to navigate the site normally. Network requests are captured automatically.
+2. Check the network log (`npx libretto network` or `networkLog()`) to find API endpoints the site uses.
+3. Recreate a key request with `page.evaluate(() => fetch(...))` and confirm it works.
+
+If the fetch call succeeds, this is your approach. You'll still use Playwright for navigation, login, and session setup — but data extraction and actions go through direct fetch calls.
+
+**When it won't work:** If `fetch` is monkey-patched, the site detects non-app-originated requests, or the API uses request signatures you can't replicate.
+
+#### Approach 2: Playwright Automation (Fallback)
+
+If direct fetch calls don't work, fall back to driving the UI with Playwright — clicking elements, filling forms, reading text from the DOM.
+
+**How to try it:**
+
+1. Navigate to the page.
+2. Use `npx libretto snapshot` to find selectors.
+3. Drive the UI with Playwright locators (`page.locator(...).click()`, `.fill()`, `.textContent()`, etc.).
+
+This works regardless of the site's architecture but is slower and more fragile against layout changes.
+
+**Supplementing with `page.on('response', ...)`:** When using Playwright automation, you can optionally listen to network responses the browser makes as you navigate — `page.on('response', ...)` lets you capture API data that flows through the site's own code without making extra requests. This is useful when the site has API endpoints but blocks direct fetch calls. Set up listeners before the navigation that triggers the requests. Not all sites will have useful responses to intercept — some are entirely server-rendered.
+
+**The workflow for form submissions and data-heavy actions:**
+
+1. Use Playwright to fill out the form, select dropdowns, check boxes — whatever the UI requires
+2. **Ask the user for confirmation before submitting** — describe what you're about to submit and wait for approval
+3. Submit the form — network requests are captured automatically (see "Network Logging" above)
+4. Check the captured requests with `npx libretto network --method POST` or `networkLog()`
+5. Inspect the captured request (URL, method, headers, body) to understand the payload structure
+6. Test recreating that request directly via `page.evaluate(() => fetch(...))` — confirm with the user before sending
+7. In the generated production code, skip the form-filling steps and fire the network request directly, parameterized with the relevant input values
+
+### Discovering Network Endpoints
+
+Network requests are captured automatically in the background (see "Network Logging" above). Use the network log to discover endpoints instead of manually attaching listeners.
+
+```bash
+# Fill out a form
+npx libretto exec "await page.locator('#department').selectOption('Cardiology'); return 'selected';"
+npx libretto exec "await page.locator('#status').selectOption('Open'); return 'selected';"
+
+# ASK THE USER before submitting — describe what will be submitted
+# Then submit and check what requests fired
+npx libretto exec "await page.locator('#submitBtn').click(); await page.waitForTimeout(3000); return 'submitted';"
+npx libretto network --method POST --last 5
+
+# Or query the log programmatically
+npx libretto exec "return await networkLog({ method: 'POST', last: 5 })"
+```
+
+For page-load requests (data fetched during navigation), just navigate and then check the log:
+
+```bash
+npx libretto exec "await page.goto('https://portal.example.com/encounters'); await page.waitForTimeout(3000); return 'loaded';"
+npx libretto network --last 20
+```
+
+### Testing a Captured Endpoint
+
+**Before making any `fetch()` call (GET or POST), always confirm with the user first.** These hit real server endpoints with real session auth — a wrong request could submit data, modify records, or trigger side effects. Describe the URL, method, and parameters you want to test and wait for approval.
+
+Note: `page.evaluate(() => fetch(...))` works for replaying both fetch-based and XHR-based endpoints — you're making a new request, not replaying the original mechanism.
+
+```bash
+# Recreate the captured request directly — confirm with user first
+npx libretto exec "
+  const resp = await page.evaluate(async () => {
+    const r = await fetch('/servlet/AjaxServlet', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: 'action=getReferrals&department=Cardiology&status=Open'
+    });
+    return await r.text();
+  });
+  return resp.substring(0, 1000);
+"
+
+# Extract session variables (safe — reads window properties, no server call)
+npx libretto exec "
+  return await page.evaluate(() => ({
+    sessionDID: (window as any).sessionDID,
+    userId: (window as any).TrUserId
+  }));
+"
+```
+
+### Generating Code
+
+After completing interactive exploration, **always generate the TypeScript workflow file before ending the session** — do not wait for the user to ask.
+
+**STOP AND ASK BEFORE GENERATING CODE.** Once the interactive workflow is figured out, pause and ask:
+
+1. "Are there any existing files or patterns in the codebase you want me to reference?"
+2. "Do you want me to incorporate any of your manual browser interactions from the actions log (`npx libretto actions --source user`) into the generated code?"
+3. "Any other guidance for how the production code should be structured?"
+
+Wait for the user's response before proceeding. Then:
+
+1. **Read `code-generation-rules.md`** (in this skill's directory) — this is mandatory before writing any code. It contains the authoritative rules for Playwright locator usage, `page.evaluate()` restrictions, network request patterns, and type checking. Do not generate code from memory; always reference this file first.
+2. Run the TypeScript type checker against the file and fix any errors before presenting it as done.
+
+## Patient Safety Warning
+
+Browser automation jobs process real patient health information. The `npx libretto` CLI executes arbitrary code with full page access. **Never** execute code that submits forms, sends referrals, deletes data, or modifies patient records.
+
+See `apps/browser-agent/docs/interactive-debugging-workflow.md` for the complete debugging guide.

package/skill/code-generation-rules.md

@@ -0,0 +1,190 @@
+# Code Generation Rules
+
+These rules apply when generating production TypeScript files from interactive browser sessions. Read this file before writing any production code.
+
+## Workflow File Structure
+
+Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <exportName>`. Import `workflow` and its types from `"libretto"`:
+
+```typescript
+import { workflow, type LibrettoWorkflowContext } from "libretto";
+
+type Input = {
+  // Define the expected input shape — passed via --params JSON
+  query: string;
+  maxResults?: number;
+};
+
+type Output = {
+  // Define what the workflow returns
+  results: Array<{ name: string; value: string }>;
+};
+
+export const myWorkflow = workflow<Input, Output>(
+  {
+    // If the site requires a saved login session:
+    authProfile: { type: "local", domain: "example.com" },
+    // Omit authProfile if no login is needed
+  },
+  async (ctx: LibrettoWorkflowContext, input: Input): Promise<Output> => {
+    const { page } = ctx;
+
+    // workflow logic here — use ctx.page, ctx.context, ctx.browser
+    await page.goto("https://example.com");
+    // ...
+
+    return { results: [] };
+  },
+);
+```
+
+**Key points:**
+
+- The named export (e.g., `myWorkflow`) is what you pass as the second arg to `npx libretto run ./file.ts myWorkflow`
+- `ctx` provides `page`, `context`, `browser`, `session`, `logger`, `headless`, `integrationPath`, `exportName`
+- `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
+- If `authProfile` is set with a domain, libretto loads the saved browser profile for that domain (created via `npx libretto save <domain>`)
+- The browser is launched and closed automatically by the CLI — do not launch or close it in the handler
+
+## Playwright Locators for DOM Interaction
+
+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.
+
+### Translation Table
+
+| Operation        | Interactive (`exec`)                                        | Production file                                                        |
+| ---------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Click            | `page.evaluate(() => document.getElementById('x').click())` | `page.locator('#x').click()`                                           |
+| Check state      | `page.evaluate(() => el.checked)`                           | `page.locator('#x').isChecked()`                                       |
+| Read text        | `page.evaluate(() => el.textContent)`                       | `page.locator('#x').textContent()`                                     |
+| Read all text    | `querySelectorAll(...).map(e => e.textContent)`             | `page.locator('.items').allTextContents()`                             |
+| Element position | `el.getBoundingClientRect()`                                | `page.locator('#x').boundingBox()`                                     |
+| Inline styles    | `el.style.top`                                              | `page.locator('#x').getAttribute('style')`                             |
+| Count elements   | `querySelectorAll(...).length`                              | `page.locator('.items').count()`                                       |
+| Select dropdown  | `selectEl.value = '...'`                                    | `page.locator('select').selectOption('...')`                           |
+| Iterate elements | `querySelectorAll(...).forEach(...)`                        | `const items = await locator.all(); for (const item of items) { ... }` |
+| Scoped query     | `parent.querySelector('.child')`                            | `parentLocator.locator('.child').textContent()`                        |
+| Batch extraction | `querySelectorAll('.item').forEach(e => { ... })`           | `for (const item of await locator.all()) { const text = await item.locator('.text').textContent(); ... }` |
+
+### Anti-Patterns
+
+These patterns come up frequently during interactive sessions and should not carry over into production code:
+
+```typescript
+// DON'T — batch-read via evaluate string
+const data = await page.evaluate(`(() => {
+  const posts = document.querySelectorAll('.post');
+  return Array.from(posts).map(p => ({
+    name: p.querySelector('.name')?.textContent,
+    content: p.querySelector('.content')?.textContent,
+  }));
+})()`);
+
+// DO — Playwright locators with a loop
+const posts = await page.locator('.post').all();
+for (const post of posts) {
+  const name = await post.locator('.name').textContent();
+  const content = await post.locator('.content').textContent();
+}
+```
+
+```typescript
+// DON'T — evaluate to count elements
+const count = await el.evaluate(`(el) => el.querySelectorAll('.item').length`);
+
+// DO
+const count = await el.locator('.item').count();
+```
+
+```typescript
+// DON'T — evaluate to read scoped text
+const text = await post.evaluate(
+  `(el) => el.querySelector('[data-view-name="foo"]')?.textContent`
+);
+
+// DO
+const text = await post.locator('[data-view-name="foo"]').textContent();
+```
+
+### When `page.evaluate()` Is Acceptable
+
+Use `page.evaluate()` only for operations that have no Playwright locator equivalent:
+
+1. **Browser-native APIs** — `getComputedStyle()`, `window.*` globals, `document.cookie`, scroll position
+2. **In-browser `fetch()` calls** — making HTTP requests from the browser context
+3. **Parsing operations** — using `DOMParser` to parse HTML/XML strings inside the browser
+
+A quick test: if the evaluate body contains `querySelector`, `querySelectorAll`, `textContent`, `click()`, `getAttribute()`, or iterates DOM elements, it should be rewritten with Playwright locators.
+
+When `page.evaluate()` is used for the acceptable cases above, use a string expression to avoid DOM type errors:
+
+```typescript
+const data = (await page.evaluate(`(() => {
+  const style = getComputedStyle(document.documentElement);
+  return style.getPropertyValue('--brand-color');
+})()`)) as string;
+```
+
+Do not use `/// <reference lib="dom" />` or add `"dom"` to the tsconfig lib — this project's tsconfig intentionally excludes DOM types.
+
+## Network Request Methods
+
+When codifying network-based data extraction or form submissions, wrap `page.evaluate(() => fetch(...))` calls in typed methods on a shared API client class:
+
+```typescript
+class ApiClient {
+  constructor(private page: Page) {}
+
+  private async apiFetch(
+    url: string,
+    options?: { method?: string; body?: string },
+  ): Promise<string> {
+    return await this.page.evaluate(
+      async ({ url, method, body }) => {
+        const init: RequestInit = { method: method ?? "GET" };
+        if (body) {
+          init.headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+          };
+          init.body = body;
+        }
+        const response = await fetch(url, init);
+        if (!response.ok) throw new Error(`${response.status} for ${url}`);
+        return await response.text();
+      },
+      { url, method: options?.method, body: options?.body },
+    );
+  }
+
+  async fetchReferralList(status: string): Promise<Referral[]> {
+    const raw = await this.apiFetch(`/api/referrals?status=${status}`);
+    // parse and return typed data
+  }
+}
+```
+
+One method per endpoint. No try-catch in API methods — let errors propagate to the orchestrator. Parse XML/HTML inside `page.evaluate()` with `DOMParser`. Use string expressions for `page.evaluate()` to avoid DOM type errors.
+
+## Comments
+
+Add comments throughout generated code to explain what each logical block is doing. Comments should describe **intent**, not restate the code. Group related actions under a single comment rather than commenting every line.
+
+```typescript
+// Log in with credentials
+await page.locator('#username').fill(user);
+await page.locator('#password').fill(pass);
+await page.locator('#login').click();
+
+// Extract author and content from each feed post
+const posts = await page.locator('.post').all();
+for (const post of posts) {
+  const name = await post.locator('.name').textContent();
+  const content = await post.locator('.content').textContent();
+}
+```
+
+## Type Checking
+
+The generated file must pass `npx tsc --noEmit` before it's considered done. If there are DOM type errors (`document`, `HTMLElement`, `getComputedStyle`), convert to locator APIs or string-expression `page.evaluate()`.

package/skill/integration-approach-selection.md

@@ -0,0 +1,174 @@
+# Integration Approach Selection Guide
+
+**Purpose:** You are connected to a live Chrome session on a target website. Your job is to probe the site for bot detection measures, assess its security posture, and determine the best integration strategy for data extraction. All strategies use Playwright for browser control — the question is what to **prioritize** for data capture: in-browser fetch calls, passive network interception, or DOM extraction.
+
+After completing the probes below, produce a **Site Assessment Summary** (see the output format at the end of this document).
+
+---
+
+## Probing the Site
+
+Run these probes to build a picture of the site's detection posture. The examples below are starting points — use your judgment to investigate further based on what you find. Sites may use detection methods not listed here.
+
+### Probe 1: Bot Protection Services & Security Signals
+
+Look for signs that the site uses bot protection — either a third-party service or custom detection. There is no complete list of indicators; these are common examples.
+
+**Cookies to look for (examples, not exhaustive):**
+
+| Cookie Pattern | Associated Service |
+|---|---|
+| `_abck` | Akamai Bot Manager |
+| `_px*` | PerimeterX (HUMAN) |
+| `datadome` | DataDome |
+| `cf_clearance` | Cloudflare |
+| `_imp_apg_r_*` | Shape Security (F5) |
+| `x-kpsdk-*` | Kasada |
+
+But don't just check this list. Examine **all** cookies on the page — look for any cookies with obfuscated names, telemetry-related prefixes, or values that look like fingerprint hashes or encrypted tokens. Unknown security cookies are still security cookies.
+
+**Global variables to check (examples):**
+
+```js
+// Known telemetry globals — but probe broadly, not just these
+window._pxAppId   // PerimeterX
+window.bmak       // Akamai
+window.ddjskey    // DataDome
+```
+
+Also examine the page's scripts: look at the first `<script>` tags in the document source, check what external domains scripts load from (e.g., `*.akamaized.net`, `*.perimeterx.net`, `*.datadome.co`, `*.kasada.io`). Bot protection scripts are typically injected before any application code.
+
+**Challenge pages:**
+
+Check if the page is showing a challenge or interstitial instead of real content — "Checking your browser...", CAPTCHA iframes, blank pages with only a spinner. These indicate active bot protection that has already been triggered.
+
+**General guidance:** The goal is to determine whether the site has bot protection and roughly how aggressive it is. Don't limit yourself to known signatures — look at the overall page behavior, unusual scripts, and anything that seems like security telemetry.
+
+### Probe 2: Fetch / XHR Interception
+
+Check whether the site has monkey-patched `window.fetch` or `XMLHttpRequest`. If it has, making your own fetch calls from `page.evaluate()` is risky because the site can inspect call stacks and detect calls that don't originate from its own code.
+
+```js
+// Check if fetch has been wrapped
+window.fetch.toString()
+// Native: "function fetch() { [native code] }"
+// Patched: shows actual JavaScript source
+
+// Check XMLHttpRequest
+XMLHttpRequest.prototype.open.toString()
+
+// Check property descriptors for tampering
+Object.getOwnPropertyDescriptor(window, 'fetch')
+// Normal: { value: ƒ, writable: true, enumerable: true, configurable: true }
+
+// Proxy-based wrapping is harder to detect — native fetch has no prototype
+window.fetch.hasOwnProperty('prototype')  // true may indicate a Proxy wrapper
+```
+
+**Important:** Some sites use `Proxy` to wrap fetch, which makes `toString()` still return `"[native code]"`. The prototype check is a heuristic, not definitive. If you see any sign of fetch interception, treat it as patched.
+
+### Probe 3: Behavioral Monitoring
+
+Look for signs that the site collects behavioral telemetry (mouse movements, keystrokes, scroll patterns). Heavy monitoring means you should use natural, human-like interaction patterns when driving the UI.
+
+Things to check:
+- Unusually large numbers of event listeners on `document` or `body` for `mousemove`, `keydown`, `scroll`, `touchstart`, `click`
+- Known telemetry collection scripts
+- `MutationObserver` instances watching the DOM for injected elements
+- `requestAnimationFrame` loops that aren't tied to visible animations
+
+If you're in a DevTools context, `getEventListeners(document)` is the quickest way to assess this. Otherwise, use heuristics — heavy behavioral monitoring usually correlates with enterprise bot protection from Probe 1.
+
+---
+
+## Choosing a Data Capture Strategy
+
+Every integration uses Playwright to control the browser. The question is what to **prioritize** for getting data out. In practice, most integrations use a mix — you'll always need some Playwright interaction for navigation, login flows, cookie consent, etc. The strategies below describe what to lean on for the core data extraction.
+
+### Strategy A: Prioritize `page.evaluate(fetch(...))`
+
+Make fetch calls directly from within the browser's JavaScript context. The requests share the browser's TLS fingerprint, cookies, and origin — they look identical to requests the site's own JS would make.
+
+**When to prioritize this:**
+- No enterprise bot protection detected
+- `fetch` is NOT monkey-patched
+- You've identified API endpoints that return the data you need
+- You need data that requires many API calls (deep pagination, bulk queries) where driving the UI would be slow
+
+**Why:** Maximum control and efficiency. You call exactly the endpoints you want with the parameters you want, skip UI rendering, and get structured JSON back. On sites without aggressive detection, this is the fastest and cleanest approach.
+
+**Risk:** If the site monitors fetch call stacks (Layer 4 detection), your calls will be flagged because they don't originate from the site's bundled code. This is uncommon but exists on high-security sites.
+
+**You'll still use Playwright for:** Initial navigation, login/auth flows, cookie consent, and any UI interactions needed to establish session state before making fetch calls.
+
+### Strategy B: Prioritize `page.on('response', ...)` (Passive Interception)
+
+Listen to network responses that the browser naturally makes as you navigate. You don't make any extra requests — you capture data flowing through the site's own API calls.
+
+**When to prioritize this:**
+- Enterprise bot protection is detected
+- `fetch` IS monkey-patched
+- The site's normal UI flow triggers API calls that return the data you need
+- You want to minimize detection risk as much as possible
+
+**Why:** Zero additional network risk. The requests that happen are the ones the site's own code triggers. You're just listening. No anomalous call stacks, no unexpected request patterns, no extra fetch calls for monitoring to flag.
+
+**Trade-off:** You only get data the page naturally loads. If you need page 50 of results, you have to click "next" 49 times via Playwright. You must set up listeners before the navigation that triggers the requests.
+
+**You'll still use Playwright for:** All navigation and interaction to trigger the data-bearing API calls, plus any data that isn't available via intercepted responses (DOM-only content).
+
+### Strategy C: Prioritize Playwright DOM Extraction
+
+Extract data directly from the rendered page using selectors and `page.evaluate()` to read DOM content.
+
+**When to prioritize this:**
+- Data is server-rendered (no JSON API calls observed)
+- The site doesn't expose the data you need via any API
+- You need visual/layout information that only exists in the DOM
+- As a fallback when Strategies A and B can't get specific pieces of data
+
+**Why:** Works regardless of the site's API architecture. If the data is visible on the page, you can extract it.
+
+**Trade-off:** Slower, fragile against DOM changes, and you only get data the UI renders (which may be less than what API responses contain).
+
+---
+
+## Decision Summary
+
+| Site Profile | Primary Strategy | Supplement With |
+|---|---|---|
+| No bot protection, fetch not patched | **A** (`page.evaluate(fetch)`) | Playwright for navigation/auth |
+| No bot protection, fetch IS patched | **B** (`page.onResponse`) | Playwright for navigation; DOM extraction as fallback |
+| Bot protection detected, fetch not patched | **B** (`page.onResponse`) | Playwright for all navigation; cautious use of `page.evaluate(fetch)` only if needed |
+| Bot protection detected, fetch IS patched | **B** (`page.onResponse`) | Playwright for all navigation; DOM extraction as fallback |
+| Server-rendered content (no API calls) | **C** (DOM extraction) | Playwright for all interaction |
+
+---
+
+## Output: Site Assessment Summary
+
+After running the probes, produce a summary in this format. **Do NOT include a final strategy recommendation.** The security assessment determines what's *safe to use*, not what will *work*. Present this to the user for input, then use the safe approaches as you build the integration — adapting if specific endpoints don't work as expected (see "Handling Approach Mismatches" in SKILL.md).
+
+```
+## Site Assessment: [site URL]
+
+### Bot Detection Profile
+- **Enterprise bot protection:** [None detected / Detected — describe what you found (service name if identifiable, cookies, scripts, telemetry globals)]
+- **Fetch/XHR interception:** [Native (not patched) / Patched — describe what you found]
+- **Behavioral monitoring:** [None detected / Light / Heavy — describe indicators]
+- **Challenge pages:** [None / Present — describe type (CAPTCHA, interstitial, etc.)]
+- **Overall security posture:** [None / Low / Moderate / High / Very High]
+
+### API Surface
+- **API calls observed:** [List key endpoints discovered, or "None — content appears server-rendered"]
+- **Data format:** [JSON / GraphQL / HTML fragments / Other — note if any responses use proprietary/binary formats]
+- **Pagination:** [Describe how pagination works if applicable]
+
+### Safe Approaches
+- **`page.evaluate(fetch(...))`:** [Safe / Unsafe — brief rationale based on fetch patching, bot detection, etc.]
+- **`page.on('response', ...)`:** [Viable / Not viable — note if response formats are parseable or proprietary]
+- **DOM extraction:** [Always available as fallback]
+- **Interaction notes:** [any behavioral precautions — natural mouse movements, typing delays, etc.]
+```
+
+**Important:** This assessment tells you which tools are in your toolbox. Present it to the user, get their input, then start building the integration using the safe approaches.