libretto 0.4.2 → 0.5.0

package/dist/cli/cli.js

@@ -16,30 +16,30 @@ Options:
                           Built-in sessions: default, dev-server, browser-agent
 
 Examples:
-  libretto-cli open https://linkedin.com
+  libretto open https://linkedin.com
 
   # ... manually log in ...
-  libretto-cli save linkedin.com
+  libretto save linkedin.com
   # Next time you open linkedin.com, you'll be logged in automatically
 
-  libretto-cli exec "await page.locator('button:has-text(\\"Sign in\\")').click()"
-  libretto-cli exec "await page.fill('input[name=\\"email\\"]', 'test@example.com')"
-  libretto-cli ai configure openai
-  libretto-cli ai configure anthropic
-  libretto-cli ai configure gemini
-  libretto-cli ai configure vertex
-  libretto-cli ai configure openai/gpt-4o
-  libretto-cli snapshot
-  libretto-cli snapshot --objective "Find the submit button" --context "Submitting a referral form, already filled in patient details"
-  libretto-cli resume --session default
-  libretto-cli close
-  libretto-cli close --all
-  libretto-cli close --all --force
+  libretto exec "await page.locator('button:has-text(\\"Sign in\\")').click()"
+  libretto exec "await page.fill('input[name=\\"email\\"]', 'test@example.com')"
+  libretto ai configure openai
+  libretto ai configure anthropic
+  libretto ai configure gemini
+  libretto ai configure vertex
+  libretto ai configure openai/gpt-4o
+  libretto snapshot
+  libretto snapshot --objective "Find the submit button" --context "Submitting a referral form, already filled in patient details"
+  libretto resume --session default
+  libretto close
+  libretto close --all
+  libretto close --all --force
 
   # Multiple sessions
-  libretto-cli open https://site1.com --session test1
-  libretto-cli open https://site2.com --session test2
-  libretto-cli exec "return await page.title()" --session test1
+  libretto open https://site1.com --session test1
+  libretto open https://site2.com --session test2
+  libretto exec "return await page.title()" --session test1
 
 Available in exec:
   page, context, state, browser, networkLog, actionLog
@@ -93,7 +93,8 @@ function validateLegacySessionArg(rawArgs) {
   if (value === void 0) return;
   if (value === null) {
     throw new Error(
-      "Usage: libretto-cli <command> [--session <name>]\nMissing or invalid --session value."
+      `Usage: libretto <command> [--session <name>]
+Missing or invalid --session value.`
     );
   }
   validateSessionName(value);

package/dist/cli/commands/ai.js

@@ -23,7 +23,7 @@ const aiCommands = SimpleCLI.group({
           preset: input.preset
         },
         {
-          configureCommandName: "libretto-cli ai configure"
+          configureCommandName: `libretto ai configure`
         }
       );
     })

package/dist/cli/commands/browser.js

@@ -47,7 +47,7 @@ const openInput = SimpleCLI.input({
   }
 }).refine(
   (input) => Boolean(input.url),
-  "Usage: libretto-cli open <url> [--headless] [--viewport WxH] [--session <name>]"
+  `Usage: libretto open <url> [--headless] [--viewport WxH] [--session <name>]`
 ).refine(
   (input) => !(input.headed && input.headless),
   "Cannot pass both --headed and --headless."
@@ -73,7 +73,7 @@ const saveInput = SimpleCLI.input({
   }
 }).refine(
   (input) => Boolean(input.urlOrDomain),
-  "Usage: libretto-cli save <url|domain> [--session <name>]"
+  `Usage: libretto save <url|domain> [--session <name>]`
 );
 function createSaveCommand(logger) {
   return SimpleCLI.command({
@@ -108,7 +108,7 @@ function createCloseCommand(logger) {
     description: "Close the browser"
   }).input(closeInput).use(resolveSessionMiddleware).handle(async ({ input, ctx }) => {
     if (input.force && !input.all) {
-      throw new Error("Usage: libretto-cli close --all [--force]");
+      throw new Error(`Usage: libretto close --all [--force]`);
     }
     if (input.all) {
       await runCloseAllWithLogger(logger, { force: input.force });

package/dist/cli/commands/execution.js

@@ -292,7 +292,7 @@ async function runResume(session, logger, sessionState) {
   } = getPauseSignalPaths(session);
   if (!existsSync(pausedSignalPath)) {
     throw new Error(
-      `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call pause() first.`
+      `Session "${session}" is not paused. Run "libretto run ... --session ${session}" and call pause("${session}") first.`
     );
   }
   if (!isProcessRunning(sessionState.pid)) {
@@ -414,7 +414,7 @@ const execInput = SimpleCLI.input({
   }
 }).refine(
   (input) => input.codeParts.length > 0,
-  "Usage: libretto-cli exec <code> [--session <name>] [--visualize]"
+  `Usage: libretto exec <code> [--session <name>] [--visualize]`
 );
 function createExecCommand(logger) {
   return SimpleCLI.command({
@@ -429,7 +429,7 @@ function createExecCommand(logger) {
     );
   });
 }
-const runUsage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]";
+const runUsage = `Usage: libretto run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]`;
 const runInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("integrationFile", z.string().optional(), {

package/dist/cli/commands/init.js

@@ -1,7 +1,7 @@
 import { createInterface } from "node:readline";
 import { appendFileSync, cpSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readAiConfig } from "../core/ai-config.js";
 import { REPO_ROOT } from "../core/context.js";
@@ -60,6 +60,17 @@ function safeReadAiConfig() {
     return null;
   }
 }
+function printInvalidAiConfigWarning() {
+  try {
+    readAiConfig();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.log("  ! Existing AI config is invalid:");
+    for (const line of message.split("\n")) {
+      console.log(`    ${line}`);
+    }
+  }
+}
 function printSnapshotApiStatus() {
   const config = safeReadAiConfig();
   const selection = resolveSnapshotApiModel(config);
@@ -69,6 +80,7 @@ function printSnapshotApiStatus() {
     "  Libretto uses direct API calls for snapshot analysis when supported credentials are available."
   );
   console.log(`  Credentials are loaded from process env and ${envPath}.`);
+  printInvalidAiConfigWarning();
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  \u2713 Ready: ${selection.model} (${selection.source})`);
     console.log("    Snapshot objectives will use the API analyzer by default.");
@@ -84,7 +96,7 @@ function printSnapshotApiStatus() {
     "      GOOGLE_CLOUD_PROJECT=...  # plus application default credentials for Vertex"
   );
   console.log(
-    "    Or run `npx libretto ai configure <provider>` to set a specific model."
+    "    Or run `npx libretto ai configure openai | anthropic | gemini | vertex` to set a specific model."
   );
   console.log("    Run `npx libretto init` interactively to set up credentials.");
 }
@@ -95,6 +107,7 @@ async function runInteractiveApiSetup() {
   console.log("\nSnapshot analysis setup:");
   console.log("  Libretto uses direct API calls for snapshot analysis.");
   console.log(`  Credentials are loaded from process env and ${envPath}.`);
+  printInvalidAiConfigWarning();
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  \u2713 Ready: ${selection.model} (${selection.source})`);
     console.log("    Snapshot objectives will use the API analyzer by default.");
@@ -119,7 +132,7 @@ async function runInteractiveApiSetup() {
       console.log("    ANTHROPIC_API_KEY=...");
       console.log("    GEMINI_API_KEY=...");
       console.log(
-        "    Or run `npx libretto ai configure <provider>` to set a specific model."
+        "    Or run `npx libretto ai configure openai | anthropic | gemini | vertex` to set a specific model."
       );
       return;
     }
@@ -196,27 +209,21 @@ function getPackageSkillsDir() {
   }
   throw new Error("Could not locate libretto skill files in package");
 }
+function detectAgentDirs(root) {
+  const dirs = [];
+  if (existsSync(join(root, ".agents"))) dirs.push(join(root, ".agents"));
+  if (existsSync(join(root, ".claude"))) dirs.push(join(root, ".claude"));
+  return dirs;
+}
 async function copySkills() {
-  const cwd = process.cwd();
-  const agentDirs = [];
-  if (existsSync(join(cwd, ".agents"))) {
-    agentDirs.push({
-      name: ".agents",
-      skillDest: join(cwd, ".agents", "skills", "libretto")
-    });
-  }
-  if (existsSync(join(cwd, ".claude"))) {
-    agentDirs.push({
-      name: ".claude",
-      skillDest: join(cwd, ".claude", "skills", "libretto")
-    });
-  }
+  const agentDirs = detectAgentDirs(REPO_ROOT);
   if (agentDirs.length === 0) {
-    console.log("\nSkills: No .agents/ or .claude/ directory found \u2014 skipping skill copy.");
+    console.log("\nSkills: No .agents/ or .claude/ directory found in repo root \u2014 skipping.");
     return;
   }
-  const dirNames = agentDirs.map((d) => d.name).join(" and ");
-  const existing = agentDirs.filter((d) => existsSync(d.skillDest));
+  const destinations = agentDirs.map((d) => join(d, "skills", "libretto"));
+  const dirNames = agentDirs.map((d) => basename(d)).join(" and ");
+  const existing = destinations.filter((d) => existsSync(d));
   const verb = existing.length > 0 ? "Overwrite" : "Install";
   const proceed = await askYesNo(`
 ${verb} libretto skills in ${dirNames}?`);
@@ -231,7 +238,9 @@ ${verb} libretto skills in ${dirNames}?`);
     console.error(`  \u2717 ${e instanceof Error ? e.message : String(e)}`);
     return;
   }
-  for (const { name, skillDest } of agentDirs) {
+  for (let i = 0; i < agentDirs.length; i++) {
+    const skillDest = destinations[i];
+    const name = basename(agentDirs[i]);
     if (existsSync(skillDest)) {
       rmSync(skillDest, { recursive: true });
     }

package/dist/cli/commands/logs.js

@@ -26,7 +26,7 @@ async function resolvePageId(session, pageId) {
   const foundPage = pages.find((page) => page.id === pageId);
   if (!foundPage) {
     throw new Error(
-      `Page "${pageId}" was not found in session "${session}". Run "libretto-cli pages --session ${session}" to list ids.`
+      `Page "${pageId}" was not found in session "${session}". Run "libretto pages --session ${session}" to list ids.`
     );
   }
   return pageId;

package/dist/cli/commands/snapshot.js

@@ -13,6 +13,7 @@ import {
 } from "./shared.js";
 import { runApiInterpret } from "../core/api-snapshot-analyzer.js";
 import { readAiConfig } from "../core/ai-config.js";
+import { resolveSnapshotApiModelOrThrow } from "../core/snapshot-api-config.js";
 const DEFAULT_SNAPSHOT_CONTEXT = "No additional user context provided.";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function generateSnapshotRunId() {
@@ -191,6 +192,10 @@ async function runSnapshot(session, logger, pageId, objective, context) {
       "Couldn't run analysis: --objective is required when providing --context."
     );
   }
+  const configuredAi = normalizedObjective ? readAiConfig() : null;
+  if (normalizedObjective) {
+    resolveSnapshotApiModelOrThrow(configuredAi);
+  }
   const { pngPath, htmlPath, condensedHtmlPath } = await captureScreenshot(
     session,
     logger,
@@ -212,7 +217,7 @@ async function runSnapshot(session, logger, pageId, objective, context) {
     htmlPath,
     condensedHtmlPath
   };
-  await runApiInterpret(interpretArgs, logger, readAiConfig());
+  await runApiInterpret(interpretArgs, logger, configuredAi);
 }
 const snapshotInput = SimpleCLI.input({
   positionals: [],

package/dist/cli/core/ai-config.js

@@ -6,7 +6,7 @@ const CURRENT_CONFIG_VERSION = 1;
 const AiConfigSchema = z.object({
   model: z.string().min(1),
   updatedAt: z.string()
-}).strict();
+});
 const ViewportConfigSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1)
@@ -19,22 +19,68 @@ const LibrettoConfigSchema = z.object({
 const DEFAULT_MODELS = {
   openai: "openai/gpt-5.4",
   anthropic: "anthropic/claude-sonnet-4-6",
-  gemini: "google/gemini-2.5-flash",
-  google: "google/gemini-2.5-flash",
+  gemini: "google/gemini-3-flash-preview",
   vertex: "vertex/gemini-2.5-pro"
 };
-const CONFIGURE_PROVIDERS = Object.keys(DEFAULT_MODELS);
-function invalidConfigError(configPath) {
+const PROVIDER_ALIASES = {
+  claude: DEFAULT_MODELS.anthropic,
+  google: DEFAULT_MODELS.gemini
+};
+const CONFIGURE_PROVIDERS = ["openai", "anthropic", "gemini", "vertex"];
+function formatConfigureProviders(separator = " | ") {
+  return CONFIGURE_PROVIDERS.join(separator);
+}
+function formatConfigIssues(error) {
+  return error.issues.map((issue) => `  - ${issue.path.join(".") || "root"}: ${issue.message}`).join("\n");
+}
+function formatExpectedConfigExample() {
+  return JSON.stringify(
+    {
+      version: CURRENT_CONFIG_VERSION,
+      ai: {
+        model: "openai/gpt-5.4",
+        updatedAt: "2026-01-01T00:00:00.000Z"
+      },
+      viewport: {
+        width: 1280,
+        height: 800
+      }
+    },
+    null,
+    2
+  );
+}
+function invalidConfigError(configPath, detail) {
   return new Error(
-    `AI config is invalid at ${configPath}. Fix the file to match the expected schema or delete it.`
+    [
+      `AI config is invalid at ${configPath}.`,
+      detail ? `Problems:
+${detail}` : null,
+      "Expected config example:",
+      formatExpectedConfigExample(),
+      "Notes:",
+      '  - "ai" and "viewport" are optional.',
+      '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
+      "Fix the file to match this shape, or delete it and rerun:",
+      `  npx libretto ai configure ${formatConfigureProviders()}`
+    ].filter(Boolean).join("\n")
   );
 }
 function parseConfig(raw, configPath) {
+  let parsedJson;
   try {
-    return LibrettoConfigSchema.parse(JSON.parse(raw));
-  } catch {
-    throw invalidConfigError(configPath);
+    parsedJson = JSON.parse(raw);
+  } catch (error) {
+    throw invalidConfigError(
+      configPath,
+      `  - root: Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const parsed = LibrettoConfigSchema.safeParse(parsedJson);
+  if (!parsed.success) {
+    throw invalidConfigError(configPath, formatConfigIssues(parsed.error));
   }
+  return parsed.data;
 }
 function readLibrettoConfig(configPath = LIBRETTO_CONFIG_PATH) {
   if (!existsSync(configPath)) {
@@ -88,7 +134,8 @@ function resolveModelFromInput(input) {
   const trimmed = input.trim();
   if (!trimmed) return null;
   if (trimmed.includes("/")) return trimmed;
-  return DEFAULT_MODELS[trimmed.toLowerCase()] ?? null;
+  const normalized = trimmed.toLowerCase();
+  return DEFAULT_MODELS[normalized] ?? PROVIDER_ALIASES[normalized] ?? null;
 }
 function runAiConfigure(input, options = {}) {
   const configureCommandName = options.configureCommandName ?? "npx libretto ai configure";
@@ -97,7 +144,10 @@ function runAiConfigure(input, options = {}) {
   if (!presetArg && !input.clear) {
     const config2 = readAiConfig(configPath);
     if (!config2) {
-      console.log(`No AI config set. Run '${configureCommandName} openai' to set one.`);
+      console.log(
+        `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`
+      );
+      console.log("Provider credentials still come from your shell or .env file.");
       return;
     }
     printAiConfig(config2, configPath);
@@ -120,7 +170,7 @@ function runAiConfigure(input, options = {}) {
        ${configureCommandName} --clear`
     );
     throw new Error(
-      `Invalid provider or model. Use one of: ${CONFIGURE_PROVIDERS.join(", ")}, or a full model string like "openai/gpt-4o".`
+      `Invalid provider or model. Use one of: ${formatConfigureProviders()}, or a full model string like "openai/gpt-4o".`
     );
   }
   const config = writeAiConfig(model, configPath);

package/dist/cli/core/browser.js

@@ -142,9 +142,14 @@ async function connect(session, logger, timeoutMs = 1e4, options) {
       port: state.port,
       pid: state.pid
     });
-    clearSessionState(session, logger);
+    if (!isPidRunning(state.pid)) {
+      clearSessionState(session, logger);
+      throw new Error(
+        `No browser running for session "${session}". Run 'libretto open <url> --session ${session}' first.`
+      );
+    }
     throw new Error(
-      `No browser running for session "${session}". Run 'libretto-cli open <url> --session ${session}' first.`
+      `Could not connect to the browser for session "${session}" at http://127.0.0.1:${state.port}, but the session process (pid ${state.pid}) is still running. Try the command again, or close and reopen the session if it stays stuck.`
     );
   }
   const contexts = browser.contexts();
@@ -170,14 +175,14 @@ async function connect(session, logger, timeoutMs = 1e4, options) {
   }
   if (options?.requireSinglePage && !options.pageId && pages.length > 1) {
     throw new Error(
-      `Multiple pages are open in session "${session}". Pass --page <id> to target a page (run "libretto-cli pages --session ${session}" to list ids).`
+      `Multiple pages are open in session "${session}". Pass --page <id> to target a page (run "libretto pages --session ${session}" to list ids).`
     );
   }
   const pageRefs = await resolvePageReferences(pages);
   const pageRef = options?.pageId ? pageRefs.find((ref) => ref.id === options.pageId) ?? null : pageRefs[pageRefs.length - 1];
   if (!pageRef) {
     throw new Error(
-      `Page "${options?.pageId}" was not found in session "${session}". Run "libretto-cli pages --session ${session}" to list ids.`
+      `Page "${options?.pageId}" was not found in session "${session}". Run "libretto pages --session ${session}" to list ids.`
     );
   }
   const page = pageRef.page;
@@ -293,7 +298,7 @@ function childLog(level, event, data = {}) {
 			timestamp: new Date().toISOString(),
 			id: Math.random().toString(36).slice(2, 10),
 			level,
-			scope: 'libretto-cli.child',
+			scope: 'libretto.child',
 			event,
 			data,
 		});
@@ -606,7 +611,7 @@ async function runCloseAll(logger, options) {
       [
         `Failed to close ${survivors.length} session(s) gracefully: ${formatSessionList(survivors)}.`,
         `Closed ${closed} session(s).`,
-        "Retry with: libretto-cli close --all --force"
+        `Retry with: libretto close --all --force`
       ].join("\n")
     );
   }

package/dist/cli/core/context.js

@@ -1,23 +1,9 @@
 import { Logger, createFileLogSink } from "../../shared/logger/index.js";
-import { spawnSync } from "node:child_process";
-import { cwd } from "node:process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
+import { resolveLibrettoRepoRoot } from "../../shared/paths/repo-root.js";
 import { validateSessionName } from "./session.js";
-function getRepoRoot() {
-  const override = process.env.LIBRETTO_REPO_ROOT?.trim();
-  if (override) {
-    return resolve(override);
-  }
-  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
-    encoding: "utf-8"
-  });
-  if (result.status === 0 && result.stdout) {
-    return result.stdout.trim();
-  }
-  return cwd();
-}
-const REPO_ROOT = getRepoRoot();
+const REPO_ROOT = resolveLibrettoRepoRoot();
 const LIBRETTO_CONFIG_DIR = join(REPO_ROOT, ".libretto");
 const LIBRETTO_CONFIG_PATH = join(LIBRETTO_CONFIG_DIR, "config.json");
 const PROFILES_DIR = join(LIBRETTO_CONFIG_DIR, "profiles");
@@ -63,7 +49,7 @@ function createLoggerForSession(session) {
   const sessionDir = getSessionDir(session);
   mkdirSync(sessionDir, { recursive: true });
   const logFilePath = getSessionLogsPath(session);
-  return new Logger(["libretto-cli"], [createFileLogSink({ filePath: logFilePath })]);
+  return new Logger(["libretto"], [createFileLogSink({ filePath: logFilePath })]);
 }
 async function closeLogger(logger) {
   if (!logger) return;

package/dist/cli/core/session.js

@@ -93,7 +93,7 @@ function throwSessionNotFoundError(session) {
   }
   lines.push("");
   lines.push("Start one with:");
-  lines.push(`  libretto-cli open <url> --session ${session}`);
+  lines.push(`  libretto open <url> --session ${session}`);
   throw new Error(lines.join("\n"));
 }
 function assertSessionStateExistsOrThrow(session) {
@@ -161,7 +161,7 @@ function assertSessionAvailableForStart(session, logger) {
   }
   const endpoint = `http://127.0.0.1:${existingState.port}`;
   throw new Error(
-    `Session "${session}" is already open and connected to ${endpoint} (pid ${existingState.pid}). Create a new session or close the current one with: libretto-cli close --session ${session}`
+    `Session "${session}" is already open and connected to ${endpoint} (pid ${existingState.pid}). Create a new session or close the current one with: libretto close --session ${session}`
   );
 }
 export {

package/dist/cli/core/snapshot-analyzer.js

@@ -76,7 +76,7 @@ ${stripAnsi(result.stderr).trim() || stripAnsi(result.stdout).trim() || "No erro
 }
 class CodexUserCodingAgent extends UserCodingAgent {
   async analyzeSnapshot(prompt, pngPath, logger) {
-    const tempDir = mkdtempSync(join(tmpdir(), "libretto-cli-analyzer-"));
+    const tempDir = mkdtempSync(join(tmpdir(), "libretto-analyzer-"));
     const outputPath = join(
       tempDir,
       `snapshot-analyzer-${Date.now()}-${Math.random().toString(36).slice(2)}.json`
@@ -171,7 +171,7 @@ async function runExternalCommand(command, args, logger, stdinText) {
       if (error.code === "ENOENT") {
         reject(
           new Error(
-            `Command not found: ${command}. Configure AI with 'libretto-cli ai configure'.`
+            `Command not found: ${command}. Configure AI with 'libretto ai configure'.`
           )
         );
         return;

package/dist/cli/core/snapshot-api-config.js

@@ -3,16 +3,15 @@ import { dirname, join, resolve } from "node:path";
 import {
   readAiConfig
 } from "./ai-config.js";
-import { REPO_ROOT } from "./context.js";
+import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
 import {
   hasProviderCredentials,
-  missingProviderCredentialsMessage,
   parseModel
 } from "../../shared/llm/client.js";
 const DEFAULT_SNAPSHOT_MODELS = {
   openai: "openai/gpt-5.4",
   anthropic: "anthropic/claude-sonnet-4-6",
-  google: "google/gemini-2.5-flash",
+  google: "google/gemini-3-flash-preview",
   vertex: "vertex/gemini-2.5-pro"
 };
 class SnapshotApiUnavailableError extends Error {
@@ -21,6 +20,48 @@ class SnapshotApiUnavailableError extends Error {
     this.name = "SnapshotApiUnavailableError";
   }
 }
+function providerSetupSentence(provider) {
+  switch (provider) {
+    case "openai":
+      return "Add OPENAI_API_KEY to .env or as a shell environment variable.";
+    case "anthropic":
+      return "Add ANTHROPIC_API_KEY to .env or as a shell environment variable.";
+    case "google":
+      return "Add GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY to .env or as a shell environment variable.";
+    case "vertex":
+      return "Add GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT to .env or as a shell environment variable, and make sure application default credentials are configured.";
+  }
+}
+function defaultModelCommandLine() {
+  return "npx libretto ai configure openai | anthropic | gemini | vertex";
+}
+function providerMissingCredentialSummary(provider) {
+  switch (provider) {
+    case "openai":
+      return "OPENAI_API_KEY is missing";
+    case "anthropic":
+      return "ANTHROPIC_API_KEY is missing";
+    case "google":
+      return "GEMINI_API_KEY and GOOGLE_GENERATIVE_AI_API_KEY are missing";
+    case "vertex":
+      return "GOOGLE_CLOUD_PROJECT and GCLOUD_PROJECT are missing";
+  }
+}
+function noSnapshotApiConfiguredMessage() {
+  return [
+    "Failed to analyze snapshot because no snapshot analyzer is configured.",
+    `Add OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_CLOUD_PROJECT to .env or as a shell environment variable, or choose a default model with \`${defaultModelCommandLine()}\`.`,
+    "For more info, run `npx libretto init`."
+  ].join(" ");
+}
+function missingProviderSnapshotMessage(selection) {
+  const configuredSource = selection.source === "config" ? ` in ${LIBRETTO_CONFIG_PATH}` : " from process env or .env";
+  return [
+    `Failed to analyze snapshot because ${selection.provider} is configured${configuredSource}, but ${providerMissingCredentialSummary(selection.provider)}.`,
+    providerSetupSentence(selection.provider),
+    "For more info, run `npx libretto init`."
+  ].join(" ");
+}
 function readWorktreeEnvPath() {
   const gitPath = join(REPO_ROOT, ".git");
   if (!existsSync(gitPath)) return null;
@@ -114,12 +155,12 @@ function resolveSnapshotApiModelOrThrow(config = readAiConfig()) {
   const selection = resolveSnapshotApiModel(config);
   if (!selection) {
     throw new SnapshotApiUnavailableError(
-      "No API snapshot analyzer is available. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY/GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_CLOUD_PROJECT, or run `npx libretto ai configure <provider>` to set a default model."
+      noSnapshotApiConfiguredMessage()
     );
   }
   if (!hasProviderCredentials(selection.provider)) {
     throw new SnapshotApiUnavailableError(
-      missingProviderCredentialsMessage(selection.provider)
+      missingProviderSnapshotMessage(selection)
     );
   }
   return selection;

package/dist/cli/router.js

@@ -17,7 +17,7 @@ function buildCLIRoutes(logger) {
   };
 }
 function createCLIApp(logger) {
-  return SimpleCLI.define("libretto-cli", buildCLIRoutes(logger), {
+  return SimpleCLI.define("libretto", buildCLIRoutes(logger), {
     globalNamed: {
       session: sessionOption()
     }

package/dist/cli/workers/run-integration-runtime.js

@@ -6,7 +6,6 @@ import { pathToFileURL } from "node:url";
 import {
   launchBrowser
 } from "../../index.js";
-import { setSessionForPause } from "../../shared/debug/pause.js";
 import { parseSessionStateContent } from "../../shared/state/index.js";
 import { getProfilePath, normalizeDomain } from "../core/browser.js";
 import {
@@ -78,9 +77,9 @@ function getMissingLocalAuthProfileError(args) {
     `Local auth profile not found for domain "${normalizedDomain}".`,
     `Expected profile file: ${args.profilePath}`,
     "To create it:",
-    `  1. libretto-cli open https://${normalizedDomain} --headed --session ${args.session}`,
+    `  1. libretto open https://${normalizedDomain} --headed --session ${args.session}`,
     "  2. Log in manually in the browser window.",
-    `  3. libretto-cli save ${normalizedDomain} --session ${args.session}`
+    `  3. libretto save ${normalizedDomain} --session ${args.session}`
   ].join("\n");
 }
 function getAbsoluteIntegrationPath(integrationPath) {
@@ -181,7 +180,6 @@ async function runIntegrationInternal(args, options) {
       appendFileSync(networkLogPath, JSON.stringify(entry) + "\n");
     }
   });
-  setSessionForPause(args.session);
   const workflowContext = {
     logger: integrationLogger,
     page: browserSession.page,

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

@@ -1 +1 @@
-export { pause, setSessionForPause } from './pause.js';
+export { pause } from './pause.js';

package/dist/shared/debug/index.js

@@ -1,5 +1,4 @@
-import { pause, setSessionForPause } from "./pause.js";
+import { pause } from "./pause.js";
 export {
-  pause,
-  setSessionForPause
+  pause
 };