libretto 0.5.5 → 0.6.0

package/dist/runtime/recovery/errors.js

@@ -1,13 +1,14 @@
 import {
   defaultLogger
 } from "../../shared/logger/logger.js";
+import { generateObject } from "ai";
 import { z } from "zod";
 const detectSubmissionErrorSchema = z.object({
   hasError: z.boolean().describe("Whether an error is visible on the page"),
   matchedKnownErrorId: z.string().nullable().describe("The ID of the matched known error, or null if no match"),
   errorMessage: z.string().nullable().describe("The error message visible on screen, or null if no error")
 });
-async function detectSubmissionError(page, error, logContext, llmClient, knownErrors = [], logger) {
+async function detectSubmissionError(page, error, logContext, model, knownErrors = [], logger) {
   const log = logger ?? defaultLogger;
   let screenshot;
   let domSnapshot;
@@ -58,7 +59,8 @@ IMPORTANT:
 ${domSnapshot ? `<dom_snapshot>
 ${domSnapshot}
 </dom_snapshot>` : ""}`;
-  const result = await llmClient.generateObjectFromMessages({
+  const { object: result } = await generateObject({
+    model,
     schema: detectSubmissionErrorSchema,
     messages: [
       {

package/dist/runtime/recovery/index.d.ts

@@ -3,5 +3,4 @@ export { attemptWithRecovery } from './recovery.js';
 export { DetectedSubmissionError, KnownSubmissionError, detectSubmissionError } from './errors.js';
 import 'playwright';
 import '../../shared/logger/logger.js';
-import '../../shared/llm/types.js';
-import 'zod';
+import 'ai';

package/dist/runtime/recovery/recovery.d.ts

@@ -1,12 +1,11 @@
 import { Page } from 'playwright';
 import { MinimalLogger } from '../../shared/logger/logger.js';
-import { LLMClient } from '../../shared/llm/types.js';
-import 'zod';
+import { LanguageModel } from 'ai';
 
 /**
  * Attempts to execute a function, and if it fails, runs popup recovery
  * (if an LLM client is provided) and retries the function once.
  */
-declare function attemptWithRecovery<T>(page: Page, fn: () => Promise<T>, logger?: MinimalLogger, llmClient?: LLMClient): Promise<T>;
+declare function attemptWithRecovery<T>(page: Page, fn: () => Promise<T>, logger?: MinimalLogger, model?: LanguageModel): Promise<T>;
 
 export { attemptWithRecovery };

package/dist/runtime/recovery/recovery.js

@@ -2,7 +2,7 @@ import {
   defaultLogger
 } from "../../shared/logger/logger.js";
 import { executeRecoveryAgent } from "./agent.js";
-async function attemptWithRecovery(page, fn, logger, llmClient) {
+async function attemptWithRecovery(page, fn, logger, model) {
   const log = logger ?? defaultLogger;
   try {
     return await fn();
@@ -13,7 +13,7 @@ async function attemptWithRecovery(page, fn, logger, llmClient) {
       });
       throw error;
     }
-    if (!llmClient) {
+    if (!model) {
       throw error;
     }
     log.info("Action failed, attempting popup recovery", {
@@ -23,7 +23,7 @@ async function attemptWithRecovery(page, fn, logger, llmClient) {
       page,
       "Look at the page to see if there is a popup blocking the screen. If so, close the popup.",
       log,
-      llmClient
+      model
     );
     return await fn();
   }

package/dist/shared/debug/pause.js

@@ -5,31 +5,14 @@ import {
   getPauseSignalPaths,
   removeSignalIfExists
 } from "../../cli/core/pause-signals.js";
-import {
-  listSessionsWithStateFile,
-  readSessionState
-} from "../../cli/core/session.js";
-function isPidRunning(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function getRunningSessions() {
-  return listSessionsWithStateFile().filter((candidate) => {
-    const state = readSessionState(candidate);
-    return state !== null && state.pid != null && isPidRunning(state.pid);
-  });
-}
+import { listRunningSessions } from "../../cli/core/session.js";
 function throwMissingSessionError() {
-  const runningSessions = getRunningSessions();
+  const runningSessions = listRunningSessions();
   const lines = ["pause(session) requires a non-empty session ID."];
   if (runningSessions.length > 0) {
     lines.push("", "Running sessions:");
-    for (const runningSession of runningSessions) {
-      lines.push(`  ${runningSession}`);
+    for (const s of runningSessions) {
+      lines.push(`  ${s.session}`);
     }
   }
   throw new Error(lines.join("\n"));

package/dist/shared/run/api.d.ts

@@ -1,2 +1,4 @@
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './browser.js';
 import 'playwright';
+import '../state/session-state.js';
+import 'zod';

package/dist/shared/run/browser.d.ts

@@ -1,4 +1,6 @@
 import { Browser, BrowserContext, Page } from 'playwright';
+import { SessionAccessMode } from '../state/session-state.js';
+import 'zod';
 
 type LaunchBrowserArgs = {
     sessionName: string;
@@ -8,6 +10,12 @@ type LaunchBrowserArgs = {
         height: number;
     };
     storageStatePath?: string;
+    accessMode?: SessionAccessMode;
+    cdpEndpoint?: string;
+    provider?: {
+        name: string;
+        sessionId: string;
+    };
 };
 type BrowserSession = {
     browser: Browser;
@@ -17,6 +25,6 @@ type BrowserSession = {
     metadataPath: string;
     close: () => Promise<void>;
 };
-declare function launchBrowser({ sessionName, headless, viewport, storageStatePath, }: LaunchBrowserArgs): Promise<BrowserSession>;
+declare function launchBrowser({ sessionName, headless, viewport, storageStatePath, accessMode, cdpEndpoint, provider, }: LaunchBrowserArgs): Promise<BrowserSession>;
 
 export { type BrowserSession, type LaunchBrowserArgs, launchBrowser };

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,8 +63,47 @@ async function launchBrowser({
   sessionName,
   headless = false,
   viewport = { width: 1366, height: 768 },
-  storageStatePath
+  storageStatePath,
+  accessMode = "write-access",
+  cdpEndpoint,
+  provider
 }) {
+  if (cdpEndpoint) {
+    const browser2 = await chromium.connectOverCDP(cdpEndpoint);
+    const context2 = browser2.contexts()[0] ?? await browser2.newContext({ viewport });
+    const page2 = context2.pages()[0] ?? await context2.newPage();
+    page2.setDefaultTimeout(3e4);
+    page2.setDefaultNavigationTimeout(45e3);
+    const metadataPath2 = ensureLibrettoSessionStatePath(sessionName);
+    writeFileSync(
+      metadataPath2,
+      JSON.stringify(
+        {
+          version: SESSION_STATE_VERSION,
+          session: sessionName,
+          port: 0,
+          cdpEndpoint,
+          pid: process.pid,
+          startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          status: "active",
+          mode: accessMode,
+          ...provider ? { provider } : {}
+        },
+        null,
+        2
+      )
+    );
+    return {
+      browser: browser2,
+      context: context2,
+      page: page2,
+      debugPort: 0,
+      metadataPath: metadataPath2,
+      close: async () => {
+        await browser2.close();
+      }
+    };
+  }
   const debugPort = await pickFreePort();
   const windowPosition = headless ? void 0 : resolveWindowPosition();
   const browser = await chromium.launch({
@@ -96,7 +135,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

@@ -7,11 +7,20 @@ declare const SessionStatusSchema: z.ZodEnum<{
     completed: "completed";
     failed: "failed";
     exited: "exited";
+    "cleanup-failed": "cleanup-failed";
+}>;
+declare const SessionAccessModeSchema: z.ZodEnum<{
+    "read-only": "read-only";
+    "write-access": "write-access";
 }>;
 declare const SessionViewportSchema: z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
 }, z.core.$strip>;
+declare const ProviderStateSchema: z.ZodObject<{
+    name: z.ZodString;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
 declare const SessionStateFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     port: z.ZodNumber;
@@ -25,17 +34,27 @@ declare const SessionStateFileSchema: z.ZodObject<{
         completed: "completed";
         failed: "failed";
         exited: "exited";
+        "cleanup-failed": "cleanup-failed";
+    }>>;
+    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>>;
+    provider: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        sessionId: z.ZodString;
+    }, 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 { ProviderStateSchema, 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

@@ -5,12 +5,18 @@ const SessionStatusSchema = z.enum([
   "paused",
   "completed",
   "failed",
-  "exited"
+  "exited",
+  "cleanup-failed"
 ]);
+const SessionAccessModeSchema = z.enum(["read-only", "write-access"]);
 const SessionViewportSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1)
 });
+const ProviderStateSchema = z.object({
+  name: z.string(),
+  sessionId: z.string()
+});
 const SessionStateFileSchema = z.object({
   version: z.literal(SESSION_STATE_VERSION),
   port: z.number().int().min(0).max(65535),
@@ -19,7 +25,9 @@ const SessionStateFileSchema = z.object({
   session: z.string().min(1),
   startedAt: z.string().datetime({ offset: true }),
   status: SessionStatusSchema.optional(),
-  viewport: SessionViewportSchema.optional()
+  mode: SessionAccessModeSchema.default("write-access"),
+  viewport: SessionViewportSchema.optional(),
+  provider: ProviderStateSchema.optional()
 });
 function formatIssues(error) {
   return error.issues.map((issue) => {
@@ -55,7 +63,9 @@ function serializeSessionState(state) {
   });
 }
 export {
+  ProviderStateSchema,
   SESSION_STATE_VERSION,
+  SessionAccessModeSchema,
   SessionStateFileSchema,
   SessionStatusSchema,
   SessionViewportSchema,

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

@@ -21,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.5",
+  "version": "0.6.0",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -8,6 +8,7 @@
     "url": "https://github.com/saffron-health/libretto"
   },
   "type": "module",
+  "packageManager": "pnpm@10.33.0",
   "publishConfig": {
     "access": "public"
   },
@@ -15,7 +16,7 @@
     "dist",
     "src",
     "scripts",
-    "skills/libretto"
+    "skills"
   ],
   "types": "./dist/index.d.ts",
   "bin": {
@@ -28,6 +29,19 @@
       "default": "./dist/index.js"
     }
   },
+  "scripts": {
+    "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",
+    "check:skills": "pnpm run check:mirrors",
+    "build": "tsup --config tsup.config.ts",
+    "type-check": "tsc --noEmit",
+    "test": "pnpm run build && vitest run",
+    "test:watch": "vitest",
+    "cli": "node dist/index.js",
+    "generate-changelog": "tsx scripts/generate-changelog.ts",
+    "prepack": "pnpm run build"
+  },
   "peerDependencies": {
     "@ai-sdk/anthropic": "^3.0.58",
     "@ai-sdk/google": "^3.0.51",
@@ -72,18 +86,5 @@
     "playwright": "^1.58.2",
     "tsx": "^4.21.0",
     "zod": "^4.3.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",
-    "check:skills": "pnpm run check:mirrors",
-    "build": "tsup --config tsup.config.ts",
-    "type-check": "tsc --noEmit",
-    "test": "pnpm run build && vitest run",
-    "test:watch": "vitest",
-    "cli": "node dist/index.js",
-    "generate-changelog": "tsx scripts/generate-changelog.ts"
   }
-}
+}

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