libretto 0.5.4 → 0.5.6

package/dist/shared/run/browser.js

@@ -8,7 +8,7 @@ import {
   SESSION_STATE_VERSION,
   SessionStateFileSchema
 } from "../state/session-state.js";
-import { readLibrettoConfig } from "../../cli/core/ai-config.js";
+import { readLibrettoConfig } from "../../cli/core/config.js";
 async function pickFreePort() {
   return await new Promise((resolve, reject) => {
     const server = createServer();
@@ -63,7 +63,8 @@ async function launchBrowser({
   sessionName,
   headless = false,
   viewport = { width: 1366, height: 768 },
-  storageStatePath
+  storageStatePath,
+  accessMode = "write-access"
 }) {
   const debugPort = await pickFreePort();
   const windowPosition = headless ? void 0 : resolveWindowPosition();
@@ -96,7 +97,8 @@ async function launchBrowser({
         port: debugPort,
         pid: process.pid,
         startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        status: "active"
+        status: "active",
+        mode: accessMode
       },
       null,
       2

package/dist/shared/state/index.d.ts

@@ -1,2 +1,2 @@
-export { SESSION_STATE_VERSION, SessionState, SessionStateFile, SessionStateFileSchema, SessionStatus, SessionStatusSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState } from './session-state.js';
+export { SESSION_STATE_VERSION, SessionAccessMode, SessionAccessModeSchema, SessionState, SessionStateFile, SessionStateFileSchema, SessionStatus, SessionStatusSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState } from './session-state.js';
 import 'zod';

package/dist/shared/state/index.js

@@ -1,4 +1,5 @@
 import {
+  SessionAccessModeSchema,
   SESSION_STATE_VERSION,
   SessionStatusSchema,
   SessionStateFileSchema,
@@ -8,6 +9,7 @@ import {
 } from "./session-state.js";
 export {
   SESSION_STATE_VERSION,
+  SessionAccessModeSchema,
   SessionStateFileSchema,
   SessionStatusSchema,
   parseSessionStateContent,

package/dist/shared/state/session-state.d.ts

@@ -8,6 +8,10 @@ declare const SessionStatusSchema: z.ZodEnum<{
     failed: "failed";
     exited: "exited";
 }>;
+declare const SessionAccessModeSchema: z.ZodEnum<{
+    "read-only": "read-only";
+    "write-access": "write-access";
+}>;
 declare const SessionViewportSchema: z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
@@ -26,16 +30,21 @@ declare const SessionStateFileSchema: z.ZodObject<{
         failed: "failed";
         exited: "exited";
     }>>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        "read-only": "read-only";
+        "write-access": "write-access";
+    }>>;
     viewport: z.ZodOptional<z.ZodObject<{
         width: z.ZodNumber;
         height: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 type SessionStatus = z.infer<typeof SessionStatusSchema>;
+type SessionAccessMode = z.infer<typeof SessionAccessModeSchema>;
 type SessionStateFile = z.infer<typeof SessionStateFileSchema>;
 type SessionState = Omit<SessionStateFile, "version">;
 declare function parseSessionStateData(rawState: unknown, source: string): SessionState;
 declare function parseSessionStateContent(content: string, source: string): SessionState;
 declare function serializeSessionState(state: SessionState): SessionStateFile;
 
-export { SESSION_STATE_VERSION, type SessionState, type SessionStateFile, SessionStateFileSchema, type SessionStatus, SessionStatusSchema, SessionViewportSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState };
+export { SESSION_STATE_VERSION, type SessionAccessMode, SessionAccessModeSchema, type SessionState, type SessionStateFile, SessionStateFileSchema, type SessionStatus, SessionStatusSchema, SessionViewportSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState };

package/dist/shared/state/session-state.js

@@ -7,6 +7,7 @@ const SessionStatusSchema = z.enum([
   "failed",
   "exited"
 ]);
+const SessionAccessModeSchema = z.enum(["read-only", "write-access"]);
 const SessionViewportSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1)
@@ -19,6 +20,7 @@ const SessionStateFileSchema = z.object({
   session: z.string().min(1),
   startedAt: z.string().datetime({ offset: true }),
   status: SessionStatusSchema.optional(),
+  mode: SessionAccessModeSchema.default("write-access"),
   viewport: SessionViewportSchema.optional()
 });
 function formatIssues(error) {
@@ -56,6 +58,7 @@ function serializeSessionState(state) {
 }
 export {
   SESSION_STATE_VERSION,
+  SessionAccessModeSchema,
   SessionStateFileSchema,
   SessionStatusSchema,
   SessionViewportSchema,

package/dist/shared/workflow/workflow.d.ts

@@ -1,11 +1,9 @@
 import { Page } from 'playwright';
-import { MinimalLogger } from '../logger/logger.js';
 
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
 type LibrettoWorkflowContext = {
     session: string;
     page: Page;
-    logger: MinimalLogger;
 };
 type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (ctx: LibrettoWorkflowContext, input: Input) => Promise<Output>;
 declare class LibrettoWorkflow<Input = unknown, Output = unknown> {
@@ -23,7 +21,8 @@ type ExportedLibrettoWorkflow = {
 type WorkflowModuleExports = Record<string, unknown>;
 declare function isLibrettoWorkflow(value: unknown): value is ExportedLibrettoWorkflow;
 declare function getWorkflowsFromModuleExports(moduleExports: WorkflowModuleExports): ExportedLibrettoWorkflow[];
+declare function getDefaultWorkflowFromModuleExports(moduleExports: WorkflowModuleExports): ExportedLibrettoWorkflow | null;
 declare function getWorkflowFromModuleExports(moduleExports: WorkflowModuleExports, workflowName: string): ExportedLibrettoWorkflow | null;
 declare function workflow<Input = unknown, Output = unknown>(name: string, handler: LibrettoWorkflowHandler<Input, Output>): LibrettoWorkflow<Input, Output>;
 
-export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, workflow };
+export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, workflow };

package/dist/shared/workflow/workflow.js

@@ -26,24 +26,30 @@ function addWorkflowOrThrow(workflowsByName, value) {
   }
   workflowsByName.set(value.name, value);
 }
-function getWorkflowsFromModuleExports(moduleExports) {
+function collectWorkflowsOrThrow(values) {
   const workflowsByName = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    addWorkflowOrThrow(workflowsByName, value);
+  }
+  return [...workflowsByName.values()];
+}
+function getWorkflowsFromModuleExports(moduleExports) {
+  const discoveredValues = [];
   for (const [exportName, value] of Object.entries(moduleExports)) {
     if (exportName === "workflows" && value && typeof value === "object") {
       if (isLibrettoWorkflow(value)) {
-        addWorkflowOrThrow(workflowsByName, value);
+        discoveredValues.push(value);
       } else {
-        for (const nestedValue of Object.values(
-          value
-        )) {
-          addWorkflowOrThrow(workflowsByName, nestedValue);
-        }
+        discoveredValues.push(...Object.values(value));
       }
       continue;
     }
-    addWorkflowOrThrow(workflowsByName, value);
+    discoveredValues.push(value);
   }
-  return [...workflowsByName.values()];
+  return collectWorkflowsOrThrow(discoveredValues);
+}
+function getDefaultWorkflowFromModuleExports(moduleExports) {
+  return isLibrettoWorkflow(moduleExports.default) ? moduleExports.default : null;
 }
 function getWorkflowFromModuleExports(moduleExports, workflowName) {
   for (const workflow2 of getWorkflowsFromModuleExports(moduleExports)) {
@@ -59,6 +65,7 @@ function workflow(name, handler) {
 export {
   LIBRETTO_WORKFLOW_BRAND,
   LibrettoWorkflow,
+  getDefaultWorkflowFromModuleExports,
   getWorkflowFromModuleExports,
   getWorkflowsFromModuleExports,
   isLibrettoWorkflow,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,7 @@
     "url": "https://github.com/saffron-health/libretto"
   },
   "type": "module",
-  "packageManager": "pnpm@9.15.4",
+  "packageManager": "pnpm@10.33.0",
   "publishConfig": {
     "access": "public"
   },
@@ -16,7 +16,7 @@
     "dist",
     "src",
     "scripts",
-    "skills/libretto"
+    "skills"
   ],
   "types": "./dist/index.d.ts",
   "bin": {
@@ -30,7 +30,6 @@
     }
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.mjs",
     "sync:mirrors": "node ../dev-tools/scripts/sync-mirrors.mjs",
     "check:mirrors": "node ../dev-tools/scripts/check-mirrors-sync.mjs",
     "sync-skills": "pnpm run sync:mirrors",

package/scripts/postinstall.mjs

@@ -5,7 +5,7 @@ import { dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-import { SKILL_DIRS, syncSkillDir } from "./skills-libretto.mjs";
+import { SKILL_MIRRORS, syncSkillDir } from "./skills-libretto.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
@@ -36,15 +36,17 @@ const repoRoot =
     ? gitResult.stdout.trim()
     : installCwd;
 
-const sourceDir = join(packageRoot, "skills", "libretto");
-if (!existsSync(sourceDir)) process.exit(0);
-
 const syncMissingDirs = repoRoot === packageRoot;
-for (const dir of SKILL_DIRS.slice(1)) {
-  const rootName = dir.split("/")[0];
-  const rootDir = join(repoRoot, rootName);
-  if (!syncMissingDirs && !existsSync(rootDir)) continue;
-  const dest = join(repoRoot, dir);
-  syncSkillDir(sourceDir, dest);
-  console.log(`libretto: synced skills/libretto -> ${dest}`);
+for (const skillMirror of SKILL_MIRRORS) {
+  const sourceDir = join(packageRoot, skillMirror.source.replace(/^packages\/libretto\//, ""));
+  if (!existsSync(sourceDir)) continue;
+
+  for (const dir of skillMirror.targets) {
+    const rootName = dir.split("/")[0];
+    const rootDir = join(repoRoot, rootName);
+    if (!syncMissingDirs && !existsSync(rootDir)) continue;
+    const dest = join(repoRoot, dir);
+    syncSkillDir(sourceDir, dest);
+    console.log(`libretto: synced ${skillMirror.source} -> ${dest}`);
+  }
 }

package/scripts/skills-libretto.mjs

@@ -2,10 +2,20 @@
 
 import { cpSync, mkdirSync, rmSync } from "node:fs";
 
-export const SKILL_DIRS = [
-  "packages/libretto/skills/libretto",
-  ".agents/skills/libretto",
-  ".claude/skills/libretto",
+export const SKILL_MIRRORS = [
+  {
+    name: "libretto",
+    source: "packages/libretto/skills/libretto",
+    targets: [".agents/skills/libretto", ".claude/skills/libretto"],
+  },
+  {
+    name: "libretto-readonly",
+    source: "packages/libretto/skills/libretto-readonly",
+    targets: [
+      ".agents/skills/libretto-readonly",
+      ".claude/skills/libretto-readonly",
+    ],
+  },
 ];
 
 export function syncSkillDir(sourceDir, destDir) {

package/skills/AGENTS.md

@@ -0,0 +1,11 @@
+# Skills Directory
+
+- `skills/libretto` is the source of truth for the interactive Libretto skill.
+- `skills/libretto-readonly` is the source of truth for the read-only diagnosis skill.
+- The mirrored copies in `.agents/skills/*` and `.claude/skills/*` are generated from the matching source directories under `skills/`.
+- Edit files under `skills/` directly. Do not hand-edit the mirrored copies.
+
+## Syncing
+
+- Run `pnpm sync:mirrors` after changing anything under `skills/`.
+- Run `pnpm check:mirrors` to verify that generated READMEs, skill mirrors, and skill version metadata are in sync.

package/skills/libretto/SKILL.md

@@ -4,7 +4,7 @@ description: "Browser automation CLI for building, maintaining, and running brow
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.5.4"
+  version: "0.5.6"
 ---
 
 ## How Libretto Works
@@ -21,8 +21,10 @@ metadata:
 
 ## Setup
 
-- Use `npx libretto init` for first-time workspace setup (sets up config file and snapshot command).
-- If credentials are already available, `npx libretto ai configure openai|anthropic|gemini|vertex` is usually enough.
+- Use `npx libretto setup` for first-time workspace onboarding. It installs Chromium, syncs skills, and pins the default snapshot model to `.libretto/config.json` when provider credentials are available.
+- Re-running `setup` on a healthy workspace shows the current configuration. If credentials are missing for a configured provider, it offers an interactive repair flow.
+- Use `npx libretto status` to inspect AI configuration health and open sessions without triggering setup.
+- Use `npx libretto ai configure openai|anthropic|gemini|vertex` to explicitly change the snapshot model or provider (advanced override).
 
 ## Working Rules
 
@@ -35,6 +37,7 @@ metadata:
 - 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.
+- If the browser must remain read-only, switch to the `libretto-readonly` skill and use `readonly-exec` instead of `exec`.
 
 ## Commands
 
@@ -43,23 +46,38 @@ metadata:
 - 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.
+- Pass `--read-only` when you want the session locked for inspection from the moment it is created.
 
 ```bash
 npx libretto open https://example.com --headed
+npx libretto open https://example.com --headless --read-only --session readonly-example
 npx libretto open https://example.com --headless --session debug-example
 ```
 
 ### `connect`
 
 - 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.
+- After connecting, `exec`, `snapshot`, `pages`, and the rest of the session commands follow that session's stored mode.
 - Libretto does not manage the connected process's lifecycle. `close` clears the session but does not terminate the remote process.
+- Pass `--read-only` if the connected session must stay inspection-only from the start.
 
 ```bash
 npx libretto connect http://127.0.0.1:9222 --session my-session
+npx libretto connect http://127.0.0.1:9222 --read-only --session readonly-session
 npx libretto connect http://127.0.0.1:9223 --session another-session
 ```
 
+### `session-mode`
+
+- Use `session-mode` to inspect whether an existing session is `write-access` or `read-only`.
+- Only a user can change the session mode for an existing session. Never change a session's mode on your own — the user must change it themselves manually.
+- `open`, `run`, and `connect` default new sessions to `write-access` unless the config sets `sessionMode` to `read-only`.
+- Pass `--read-only` or `--write-access` to override the config default for a single command.
+
+```bash
+npx libretto session-mode --session my-session
+```
+
 ### `snapshot`
 
 - Use `snapshot` as the primary page observation tool.
@@ -87,6 +105,7 @@ npx libretto snapshot \
 - 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.
+- Do not use `exec` in read-only diagnosis flows. Use `readonly-exec` from the `libretto-readonly` skill for those sessions.
 
 ```bash
 npx libretto exec "return await page.url()"
@@ -98,7 +117,7 @@ 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`.
+- If `exec` or `snapshot` complains about multiple pages, list page ids first and then pass `--page`.
 
 ```bash
 npx libretto pages --session debug-example
@@ -109,14 +128,16 @@ npx libretto exec --session debug-example --page <page-id> "return await page.ur
 
 - 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.
+- Pass `--read-only` if the preserved session should come back locked for follow-up terminal inspection after the workflow run.
 - 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 workflowName --headless --params '{"status":"open"}'
-npx libretto run ./integration.ts workflowName --auth-profile app.example.com
+npx libretto run ./integration.ts --headless --params '{"status":"open"}'
+npx libretto run ./integration.ts --headless --read-only
+npx libretto run ./integration.ts --auth-profile app.example.com
 ```
 
 ### `resume`
@@ -191,7 +212,7 @@ Assistant: I'll inspect the real site first if needed, but before I finish I'll
 Assistant: [Runs `npx libretto open https://target.example.com --headed`]
 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: [Uses `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>
@@ -203,7 +224,7 @@ Assistant: I found the working path. I'll now update the workflow file outside L
 <example>
 [Context: The user has an existing Libretto workflow that is failing]
 Assistant: I'll reproduce the failure first so we can inspect the exact browser state it leaves behind.
-Assistant: [Runs `npx libretto run ./integration.ts main --session debug-flow --headed`]
+Assistant: [Runs `npx libretto run ./integration.ts --session debug-flow --headed`]
 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..."`]

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

@@ -19,7 +19,7 @@ Use this reference only when the user explicitly asks to save or reuse local aut
 ```bash
 npx libretto open https://app.example.com --headed
 npx libretto save app.example.com
-npx libretto run ./integration.ts main --auth-profile app.example.com
+npx libretto run ./integration.ts --auth-profile app.example.com
 ```
 
 ## Notes

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

@@ -6,7 +6,7 @@ Follow the user's existing codebase conventions, abstractions, and patterns when
 
 ## 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"`:
+Generated files must default-export a `workflow()` instance so they can be run via `npx libretto run <file>`. Import `workflow` and its types from `"libretto"`:
 
 ```typescript
 import { workflow, pause, type LibrettoWorkflowContext } from "libretto";
@@ -22,12 +22,12 @@ type Output = {
   results: Array<{ name: string; value: string }>;
 };
 
-export const myWorkflow = workflow<Input, Output>(
+export default workflow<Input, Output>(
   "myWorkflow",
   async (ctx: LibrettoWorkflowContext, input): Promise<Output> => {
-    const { session, page, logger } = ctx;
+    const { session, page } = ctx;
 
-    logger.info("workflow-start", { session, query: input.query });
+    console.log("workflow-start", { session, query: input.query });
     await page.goto("https://example.com");
     await pause(session);
 
@@ -39,8 +39,8 @@ export const myWorkflow = workflow<Input, Output>(
 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`
+- `npx libretto run ./file.ts` executes the file's default-exported workflow, so always use `export default workflow(...)`.
+- `ctx` provides `session` and `page`. Use `console.log`/`console.warn`/`console.error` for logging — the runtime wraps these with structured metadata automatically.
 - `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.

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

@@ -12,8 +12,9 @@ Use this reference when you need to inspect or change the workspace configuratio
 
 Libretto reads workspace config from `.libretto/config.json`.
 
-- The file is usually created or updated by `npx libretto ai configure ...`.
+- The file is created by `npx libretto setup` during first-time onboarding (auto-pins the default model for the detected provider) or by `npx libretto ai configure ...` for explicit overrides.
 - API credentials still come from your shell environment or `.env`. The config file stores the selected model, not the secret itself.
+- Use `npx libretto status` to inspect the current AI configuration and open sessions without changing anything.
 - For first-time setup instructions, follow the main `SKILL.md` flow instead of expanding this reference.
 
 ## Supported Settings
@@ -21,6 +22,7 @@ Libretto reads workspace config from `.libretto/config.json`.
 - `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`.
+- `sessionMode` sets the default session access mode for new sessions created by `open`, `connect`, and `run`. Must be `"read-only"` or `"write-access"`. When omitted, defaults to `"write-access"`. Pass `--read-only` or `--write-access` to `open`, `connect`, or `run` to override when creating a session.
 
 Example:
 
@@ -34,20 +36,23 @@ Example:
   "viewport": {
     "width": 1280,
     "height": 800
-  }
+  },
+  "sessionMode": "write-access"
 }
 ```
 
 ## Common Commands
 
 ```bash
-npx libretto init
-npx libretto ai configure openai
+npx libretto setup                                         # first-time onboarding, auto-pins default model
+npx libretto status                                        # inspect AI config and open sessions
+npx libretto ai configure openai                           # explicitly change provider/model
 npx libretto open https://app.example.com --viewport 1440x900
-npx libretto run ./integration.ts main --viewport 1440x900
+npx libretto run ./integration.ts --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.
+- If `snapshot` analysis is not configured yet, run `npx libretto setup` to auto-configure, or see the main `SKILL.md` flow.
+- Run `npx libretto status` at any time to check which model is active and whether credentials are present.

package/skills/libretto-readonly/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: libretto-readonly
+description: "Read-only Libretto workflow for diagnosing live browser state without clicks, typing, navigation, or mutation requests."
+license: MIT
+metadata:
+  author: saffron-health
+  version: "0.5.6"
+---
+
+## How Libretto Read-Only Works
+
+- Use this skill when the browser session must stay strictly read-only.
+- Libretto stores read-only vs write-access on the session itself.
+- The primary inspection tools are `snapshot` and `readonly-exec`.
+- `readonly-exec` reuses Libretto's normal execution pipeline, but it only exposes read-only helpers and denies mutating Playwright methods.
+- Only a user can change the session mode for an existing session. Never change a session's mode on your own — the user must change it themselves manually.
+
+## Working Rules
+
+- Announce which session you are using and what page you are inspecting.
+- Do not use `exec`, `run`, or any direct Playwright action that could change browser or application state.
+- Do not click, type, submit forms, navigate, upload files, dispatch DOM events, or send non-GET requests.
+- Prefer `snapshot` first when the visible page state is unclear.
+- Use `readonly-exec` for focused inspection: titles, HTML, locator text, counts, visibility checks, and GET requests.
+- Keep snippets small and purpose-built. Do not run multiple `readonly-exec` commands at the same time.
+- End with diagnosis and handoff guidance, not an attempted in-browser repair.
+
+## Commands
+
+### `connect`
+
+- Use `connect` to attach to an existing CDP endpoint for a preserved browser session.
+- Use `--read-only` when creating the Libretto session handle for a preserved browser session.
+- Libretto read-only mode is enforced through Libretto commands; direct CDP clients that skip Libretto are outside this boundary.
+
+```bash
+npx libretto connect http://127.0.0.1:9222 --read-only --session failed-job-debug
+```
+
+### `pages`
+
+- Use `pages` when a popup, new tab, or second page exists.
+- If `readonly-exec` or `snapshot` complains about multiple pages, list ids first and then pass `--page`.
+
+```bash
+npx libretto pages --session failed-job-debug
+```
+
+### `snapshot`
+
+- Use `snapshot` as the first high-level observation tool.
+- Always provide both `--objective` and `--context`.
+
+```bash
+npx libretto snapshot \
+  --session failed-job-debug \
+  --objective "Identify the visible failure state and likely blocking UI condition" \
+  --context "The workflow already failed and the preserved browser must remain read-only."
+```
+
+### `readonly-exec`
+
+- Use `readonly-exec` for narrow inspection code only.
+- Denied operations fail with `ReadonlyExecDenied: ...`.
+
+#### Helpers
+
+- `page` — a read-only Playwright `Page` proxy. Standard Playwright read methods work normally (`url()`, `title()`, `content()`, `getByRole()`, `locator()`, `textContent()`, `isVisible()`, `count()`, `scrollIntoViewIfNeeded()`, etc.). Anything that mutates the page (`click`, `fill`, `goto`, `evaluate`, `keyboard`, `mouse`) is blocked.
+- `state` — the current Libretto session state object.
+- `get(url, options?)` — HTTP client restricted to **GET and HEAD** requests. Replaces `fetch`, which is blocked in readonly mode. Any request with a body or a non-GET/HEAD method throws `ReadonlyExecDenied`.
+- `scrollBy(deltaX, deltaY)` — scroll the viewport by pixel offset. Use this to inspect content below the fold without targeting a specific element.
+
+Standard JS globals `console`, `URL`, `Buffer`, `setTimeout`, and `setInterval` are also available.
+
+#### Examples
+
+```bash
+npx libretto readonly-exec "return page.url()" --session failed-job-debug
+npx libretto readonly-exec "return await page.getByRole('heading').first().textContent()" --session failed-job-debug
+
+# HTTP GET inspection
+echo "const r = await get('https://api.example.com/status'); return await r.json()" \
+  | npx libretto readonly-exec - --session failed-job-debug
+
+# Scroll down to inspect below-the-fold content
+npx libretto readonly-exec "await scrollBy(0, 500)" --session failed-job-debug
+```
+
+### `close`
+
+- Use `close` when the inspection session is no longer needed.
+
+```bash
+npx libretto close --session failed-job-debug
+```

package/src/cli/cli.ts

@@ -16,6 +16,10 @@ Examples:
 
   libretto exec "await page.locator('button:has-text(\\"Sign in\\")').click()"
   libretto exec "await page.fill('input[name=\\"email\\"]', 'test@example.com')"
+  libretto readonly-exec "return await page.title()" --session test1
+  libretto connect http://127.0.0.1:9222 --read-only --session test1
+  libretto run ./integration.ts --read-only --session test1
+  libretto status
   libretto ai configure openai
   libretto ai configure anthropic
   libretto ai configure gemini
@@ -36,6 +40,9 @@ Examples:
 Available in exec:
   page, context, state, browser, networkLog, actionLog
 
+Available in readonly-exec:
+  page, state, snapshot, scrollBy, get
+
 Profiles:
   Profiles are saved to .libretto/profiles/<domain>.json (git-ignored)
   They persist cookies, localStorage, and session data across browser launches.
@@ -46,6 +53,9 @@ Sessions:
   Session state is stored in .libretto/sessions/<session>/state.json
   CLI logs are stored in .libretto/sessions/<session>/logs.jsonl
   Each session runs an isolated browser instance on a dynamic port.
+  Session mode is stored per session as read-only or write-access.
+  Use --read-only on open, connect, or run to create a read-only session.
+  Session mode is enforced by Libretto commands, not by raw CDP clients outside Libretto.
 `;
 }