libretto 0.5.3-experimental.5 → 0.5.3

package/scripts/summarize-evals.mjs

@@ -5,7 +5,9 @@ import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 function usage() {
-  console.error("Usage: node scripts/summarize-evals.mjs <score-dir> <summary-json-path>");
+  console.error(
+    "Usage: node scripts/summarize-evals.mjs <score-dir> <summary-json-path>",
+  );
 }
 
 function normalizeFailureRecord(failure) {
@@ -18,8 +20,11 @@ function normalizeFailureRecord(failure) {
 function normalizeRecord(record) {
   const failures = Array.isArray(record?.failures)
     ? record.failures
-      .map(normalizeFailureRecord)
-      .filter((failure) => failure.criterion.length > 0 && failure.reason.length > 0)
+        .map(normalizeFailureRecord)
+        .filter(
+          (failure) =>
+            failure.criterion.length > 0 && failure.reason.length > 0,
+        )
     : [];
 
   return {
@@ -35,14 +40,22 @@ export function loadScoreRecords(scoreDirArg) {
   const scoreDir = resolve(scoreDirArg);
   return readdirSync(scoreDir, { withFileTypes: true })
     .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-    .map((entry) => JSON.parse(readFileSync(join(scoreDir, entry.name), "utf8")))
+    .map((entry) =>
+      JSON.parse(readFileSync(join(scoreDir, entry.name), "utf8")),
+    )
     .map(normalizeRecord)
     .sort((a, b) => String(a.name).localeCompare(String(b.name)));
 }
 
 export function buildSummary(records) {
-  const passed = records.reduce((sum, record) => sum + Number(record.passed || 0), 0);
-  const total = records.reduce((sum, record) => sum + Number(record.total || 0), 0);
+  const passed = records.reduce(
+    (sum, record) => sum + Number(record.passed || 0),
+    0,
+  );
+  const total = records.reduce(
+    (sum, record) => sum + Number(record.total || 0),
+    0,
+  );
   const percent = total > 0 ? Number(((passed / total) * 100).toFixed(2)) : 0;
   const failingRecords = records.filter((record) => record.failures.length > 0);
 
@@ -72,16 +85,22 @@ export function buildMarkdown(summary, summaryPathArg) {
     lines.push("", "## Breakdown", "");
     for (const record of summary.records) {
       const status = record.failures.length > 0 ? "fail" : "pass";
-      lines.push(`- ${status} \`${record.name}\`: \`${record.percent}%\` (${record.passed}/${record.total})`);
+      lines.push(
+        `- ${status} \`${record.name}\`: \`${record.percent}%\` (${record.passed}/${record.total})`,
+      );
     }
   }
 
   if (summary.failingRecordCount > 0) {
     lines.push("", "## Failed Evals", "");
-    for (const record of summary.records.filter((candidate) => candidate.failures.length > 0)) {
+    for (const record of summary.records.filter(
+      (candidate) => candidate.failures.length > 0,
+    )) {
       lines.push(`### \`${record.name}\``);
       lines.push("");
-      lines.push(`- Score: \`${record.percent}%\` (${record.passed}/${record.total})`);
+      lines.push(
+        `- Score: \`${record.percent}%\` (${record.passed}/${record.total})`,
+      );
       for (const failure of record.failures) {
         lines.push(`- ${failure.criterion}: ${failure.reason}`);
       }
@@ -108,6 +127,9 @@ function main(argv) {
   process.stdout.write(buildMarkdown(summary, summaryPath));
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
   main(process.argv);
 }

package/skills/libretto/SKILL.md

@@ -4,41 +4,37 @@ description: "Browser automation CLI for building, maintaining, and running brow
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.4.0"
+  version: "0.5.3"
 ---
 
-# Libretto
+## How Libretto Works
 
-Libretto is a CLI for building and maintaining browser automation scripts.
-Use `npx libretto` to build or debug automations by inspecting live browser state, executing Playwright code, and running existing workflows.
+- Libretto is a CLI for exploring live websites and building or debugging reusable browser automation scripts.
+- 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.
 
-## Intro
+## Default Integration Approach
 
-- Use this skill when the truth is on the page.
-- Prefer Libretto when you need to build, maintain, or debug a browser automation script against the live site.
-- Treat Libretto as a script-authoring workflow: choose or create a workflow file, inspect the page, try focused actions, then update code outside the CLI and verify it with `run`.
-- If the user asks for a new automation or scrape and no workflow file exists yet, create one in the workspace instead of stopping at interactive exploration.
-- For a new automation, make the workflow file a required deliverable before you finish the task, even if you inspect the site first.
-- If the user does not provide a workflow path, choose a reasonable filename in the current workspace and create it yourself.
-- When building a new integration, prefer reverse-engineering network requests first. Fall back to browser automation when the request path is unclear, too fragile, or blocked by anti-bot systems.
+- 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 setup.
-- If they already have credentials, `npx libretto ai configure openai|anthropic|gemini|vertex` is enough.
+- 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.
 
-## Rules
+## Working Rules
 
 - Announce which session you are using and what page you are on.
-- When the task is to build or change an automation, create or update the workflow file and use Libretto commands to gather the information needed for that code change.
-- For a new automation, you may use `open`, `snapshot`, or `exec` first to learn the page, but do not finish or reply as if the task is complete until the workflow file exists.
-- Treat scrape and integration requests as requests for reusable automation code by default, not as requests to manually collect the final data in the live session.
 - Ask instead of guessing when it is unclear what to click, type, or submit.
-- Use `snapshot` to understand unknown page state before trying multiple selectors.
+- 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.
+- 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
 
@@ -53,49 +49,135 @@ npx libretto open https://example.com --headed
 npx libretto open https://example.com --headless --session debug-example
 ```
 
-### `exec`
+### `connect`
 
-- 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.
-- Let failures throw. Do not hide `exec` failures with `try/catch`.
+- Use `connect` to attach to any existing Chrome DevTools Protocol (CDP) endpoint — a browser started with `--remote-debugging-port`, an Electron app, or any other CDP-compatible target.
+- After connecting, `exec`, `snapshot`, `pages`, and all other session commands work normally.
+- Libretto does not manage the connected process's lifecycle. `close` clears the session but does not terminate the remote process.
 
 ```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 connect http://127.0.0.1:9222 --session my-session
+npx libretto connect http://127.0.0.1:9223 --session another-session
 ```
 
 ### `snapshot`
 
 - Use `snapshot` as the primary page observation tool.
-- Use `snapshot` to understand the current page before editing the workflow when the structure or next step is unclear.
-- When you want analysis, provide both `--objective` and `--context`.
-- If you only need the PNG and HTML files, omit `--objective`. That runs capture-only mode and skips AI analysis.
-- When using `--objective`, expect analysis to take time. Use a timeout of at least 2 minutes for shell-wrapped calls.
+- 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.
 
 ```bash
-npx libretto snapshot
 npx libretto snapshot \
   --objective "Find the sign-in form and submit button" \
   --context "I just opened the login page and need the email field, password field, and submit button."
 npx libretto snapshot \
+  --session debug-example \
+  --page <page-id> \
   --objective "Explain why the table is empty" \
-  --context "I opened the referrals page and expected rows after applying filters."
+  --context "I opened the referrals page, applied filters, and expected rows to appear."
+```
+
+### `exec`
+
+- 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.
+- Use `exec -` to run multi-line scripts from stdin, especially when the code is too long or complex for a command line argument.
+- 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 "await page.locator('button:has-text(\"Continue\")').click()"
+echo "return await page.url()" | npx libretto exec - --session debug-example
+```
+
+### `pages`
+
+- Use `pages` when a popup, new tab, or second page appears.
+- If `exec`, `snapshot`, `network`, or `actions` complains about multiple pages, list page ids first and then pass `--page`.
+
+```bash
+npx libretto pages --session debug-example
+npx libretto exec --session debug-example --page <page-id> "return await page.url()"
 ```
 
 ### `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 workflowName --headless --params '{"status":"open"}'
+npx libretto run ./integration.ts workflowName --auth-profile app.example.com
+```
+
+### `resume`
+
+- 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
+npx libretto resume --session debug-example
+```
+
+### `save`
+
+- Use `save` only when the user explicitly asks to save or reuse authenticated browser state.
+
+```bash
+npx libretto save app.example.com
+```
+
+### `close`
+
+- 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
+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
@@ -105,31 +187,16 @@ npx libretto run ./integration.ts main --auth-profile app.example.com --headed
 ```text
 <example>
 [Context: The user wants to build a new browser workflow and does not yet know the page structure]
-Assistant: I'll inspect the real site first if needed, but before I finish I'll create `./target-workflow.mjs` so the task produces reusable automation code.
+Assistant: I'll inspect the real site first if needed, but before I finish I'll create `target-workflow.ts` so the task produces reusable automation code.
 Assistant: [Runs `npx libretto open https://target.example.com --headed`]
-Assistant: I'll first determine whether this flow can be built from captured network requests instead of UI-only automation.
-Assistant: [Runs `npx libretto snapshot --objective "Find the next required action" --context "We are starting the workflow from the landing page."`]
-Assistant: If the page exposes a clear and stable request path, I'll prioritize that. If the request path is unclear, fragile, or heavily defended, I'll fall back to browser automation.
-Assistant: [Uses `network`, `snapshot`, and `exec` as needed to prove the approach]
+Assistant: [Reads `references/site-security-review.md` before choosing between passive network inspection, direct browser fetch calls, and Playwright-first automation]
+Assistant: [Runs `npx libretto snapshot --objective "Find the next required action" --context "We are starting the workflow from the landing page and need the first meaningful step."`]
+Assistant: [Uses `network`, `snapshot`, and `exec` as needed to understand the site and decide the implementation path]
+Assistant: [Reads `references/code-generation-rules.md` before writing production workflow code]
 Assistant: I found the working path. I'll now update the workflow file outside Libretto and verify it with `npx libretto run ...`.
 </example>
 ```
 
-#### Network requests
-
-```text
-<example>
-[Context: The user wants to build an integration using network requests]
-Assistant: [Reads `references/reverse-engineering-network-requests.md`]
-Assistant: Let me open the page in headed mode. Perform the workflow and I'll use the network log to recreate it.
-Assistant: [Runs `npx libretto open https://target.example.com --headed`]
-[User performs workflow]
-User: I've completed the workflow
-Assistant: [Runs `npx libretto network --method POST --last 20`]
-Assistant: I found the relevant requests. I'll recreate the workflow from those requests, then test the resulting script with `npx libretto run ...`.
-</example>
-```
-
 ### Debugging existing workflows
 
 ```text
@@ -140,13 +207,16 @@ Assistant: [Runs `npx libretto run ./integration.ts main --session debug-flow --
 Assistant: The workflow failed and Libretto kept the browser open. I'll inspect the page state before changing code.
 Assistant: [Runs `npx libretto snapshot --session debug-flow --objective "Find the blocking error or broken selector target" --context "The workflow just failed after trying to continue from the review step, and I need to identify the visible blocker on the current page."`]
 Assistant: [Runs `npx libretto exec --session debug-flow "...focused inspection or prototype..."`]
+Assistant: [Reads `references/code-generation-rules.md` before patching the workflow file]
 Assistant: I found the issue. I'll patch the workflow code, then rerun `npx libretto run ...` to verify the fix.
 </example>
 ```
 
 ## References
 
-- For reverse-engineering captured requests, read `references/reverse-engineering-network-requests.md`.
-- For incorporating manual browser steps the user performed, read `references/user-action-log.md`.
-- For saving and reusing login state, read `references/auth-profiles.md`.
-- For multiple open pages and page targeting, read `references/pages-and-page-targeting.md`.
+- 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 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

@@ -0,0 +1,176 @@
+# Code Generation Rules
+
+These rules apply when generating production TypeScript files from interactive browser sessions. Read this file before writing any production code.
+
+Follow the user's existing codebase conventions, abstractions, and patterns whenever possible. Do not introduce a new style unless the codebase does not already have a suitable one.
+
+## Workflow File Structure
+
+Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <workflowName>`. Import `workflow` and its types from `"libretto"`:
+
+```typescript
+import { workflow, pause, 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>(
+  "myWorkflow",
+  async (ctx: LibrettoWorkflowContext, input): Promise<Output> => {
+    const { session, page, logger } = ctx;
+
+    logger.info("workflow-start", { session, query: input.query });
+    await page.goto("https://example.com");
+    await pause(session);
+
+    return { results: [] };
+  },
+);
+```
+
+Key points:
+
+- `workflow(name, handler)` takes a unique workflow name and returns the workflow object that Libretto can run.
+- `npx libretto run ./file.ts myWorkflow` resolves `myWorkflow` from the workflows exported by `./file.ts`, so export or re-export the workflow from that file directly or through a `workflows` object, and make sure the run argument matches the name passed to `workflow("myWorkflow", ...)`.
+- `ctx` provides `session`, `page`, and `logger`
+- `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
+- 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.
+
+## 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:
+
+```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, keep the logic self-contained and return JSON-serializable values:
+
+```typescript
+const data = (await page.evaluate(`(() => {
+  const style = getComputedStyle(document.documentElement);
+  return style.getPropertyValue('--brand-color');
+})()`)) as string;
+```
+
+Do not rely on broad DOM querying inside `page.evaluate()` for production flows when Playwright locators can express the same interaction.
+
+## 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 type errors around DOM access, prefer locator APIs first, then use focused `page.evaluate()` only for browser-native APIs.