libretto 0.5.0 → 0.5.2

package/skills/libretto/SKILL.md

@@ -1,43 +1,47 @@
 ---
 name: libretto
-description: "Browser automation CLI for inspecting live pages, prototyping interactions, and running browser workflows."
+description: "Browser automation CLI for building, maintaining, and running browser automation workflows by inspecting live pages and prototyping interactions."
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.4.0"
+  version: "0.4.2"
 ---
 
-# Libretto
+## How Libretto Works
 
-Use `npx libretto` to inspect live browser state, prototype interactions, and run existing browser 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 see what the browser is doing, not when you only need to edit source files.
-- Treat Libretto as a session-based workflow: open a page, inspect it, try a focused action, then turn what you learned into code outside the CLI.
-- 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.
 - 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
 
 ### `open`
 
 - Open a page before using `exec` or `snapshot`.
+- Use `open` at the start of script authoring when you need live page state to decide how the workflow should work.
 - Use headed mode when the user needs to log in or watch the workflow.
 
 ```bash
@@ -45,47 +49,133 @@ 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.
-- 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.
-- 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.
+- 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()"
+```
+
+### `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 execute an existing Libretto workflow.
+- 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("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
@@ -95,31 +185,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: Let me open the target page in headed mode so we can inspect the real workflow.
+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
@@ -130,13 +205,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,210 @@
+# 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> <exportName>`. 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>(
+  async (ctx, 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:
+
+- The named export (e.g., `myWorkflow`) is what you pass as the second arg to `npx libretto run ./file.ts myWorkflow`
+- `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
+- 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
+
+Use the third generic on `workflow<Input, Output, Services>` to inject
+dependencies that exist in your application but not in libretto's runtime
+(DB transactions, API clients, caches, etc.):
+
+```typescript
+import { type Transaction } from "./db";
+
+type MyServices = { tx?: Transaction };
+
+export const myWorkflow = workflow<Input, Output, MyServices>(
+  async (ctx, input) => {
+    if (ctx.services.tx) {
+      await ctx.services.tx.insert(/* ... */);
+    } else {
+      ctx.logger.info("No DB transaction — skipping write");
+    }
+    // ... browser automation ...
+  },
+);
+```
+
+In production, the caller passes services when invoking `.run()`:
+
+```typescript
+await myWorkflow.run(
+  { session: "debug-flow", page, logger, services: { tx } },
+  input,
+);
+```
+
+When running standalone via `npx libretto run`, services defaults to `{}`,
+so mark fields optional for anything unavailable in that context.
+
+## 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.

package/skills/libretto/references/configuration-file-reference.md

@@ -0,0 +1,53 @@
+# Configuration File Reference
+
+Use this reference when you need to inspect or change the workspace configuration that powers `snapshot` analysis and default viewport behavior.
+
+## When to Use This
+
+- You want to confirm which AI model `snapshot` will use.
+- You want to understand where Libretto stores workspace-level settings.
+- You want a persistent default viewport for `open` or `run`.
+
+## File Location
+
+Libretto reads workspace config from `.libretto/config.json`.
+
+- The file is usually created or updated by `npx libretto ai configure ...`.
+- API credentials still come from your shell environment or `.env`. The config file stores the selected model, not the secret itself.
+- For first-time setup instructions, follow the main `SKILL.md` flow instead of expanding this reference.
+
+## Supported Settings
+
+- `ai.model` selects the configured analysis model for `snapshot`.
+- `viewport` is an optional top-level setting used by `open` and `run` when you do not pass `--viewport`.
+- Viewport precedence is: CLI `--viewport`, then `.libretto/config.json`, then the default `1366x768`.
+
+Example:
+
+```json
+{
+  "version": 1,
+  "ai": {
+    "model": "openai/gpt-5.4",
+    "updatedAt": "2026-01-01T00:00:00.000Z"
+  },
+  "viewport": {
+    "width": 1280,
+    "height": 800
+  }
+}
+```
+
+## Common Commands
+
+```bash
+npx libretto init
+npx libretto ai configure openai
+npx libretto open https://app.example.com --viewport 1440x900
+npx libretto run ./integration.ts main --viewport 1440x900
+```
+
+## Notes
+
+- If you want a persistent default viewport for the workspace, add `viewport` to `.libretto/config.json` instead of repeating `--viewport` on every command.
+- If `snapshot` analysis is not configured yet, return to the setup steps in the main `SKILL.md` flow.

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.